Comment envoyer des données à l'API de Plecto

Qu'est-ce que l'API Plecto ?

L'API Plecto permet aux développeurs de créer une intégration avancée personnalisée qui permet à d'autres logiciels de communiquer avec notre plateforme et d'exporter leurs données vers Plecto.

Si vous souhaitez tester l'API Plecto manuellement, vous pouvez utiliser un logiciel gratuit comme Postman, mais tout autre outil capable d'envoyer des requêtes HTTP est également pris en charge.

Authentification

Le schéma d'authentification utilisé pour l'API Plecto est l'authentification de base. Il inclut l'envoi de votre email et de votre mot de passe avec la requête.
Astuce ! 💡 Nous vous recommandons de créer un nouvel utilisateur (nouveau profil d'employé) par intégration dans votre organisation Plecto – de cette façon, vous éviterez de partager le même mot de passe entre les intégrations.
L'utilisateur doit avoir accès aux zones pertinentes de Plecto pour réussir avec la plupart des points de terminaison de l'API. Si votre abonnement Plecto inclut une gestion avancée des autorisations, vous pouvez créer un profil d'autorisation spécifique pour le compte utilisateur.

Pour créer de nouveaux employés, allez dans Paramètres > Employés > Nouvel employé dans Plecto ou ajoutez-les via une requête API.

URL de base et points de terminaison

Tous les points de terminaison de l'API Plecto sont listés sous l'URL de base suivante : https://app.plecto.com/api/v2/

Cette URL est la base de tous les points de terminaison de l'API Plecto. Si vous êtes connecté à votre compte Plecto, vous pouvez voir la liste des points de terminaison de l'API directement dans le navigateur.

Comment créer une source de données API

Vous pouvez créer une source de données API de deux manières :

Postez une requête à ce point de terminaison : https://app.plecto.com/api/v2/datasources/ Il suffit d'inclure les clés "title" et "fields" dans la requête pour créer la source de données.
Ou allez dans Sources de données > Nouvelle source de données > API Plecto et créez une nouvelle source de données depuis l'interface Plecto.

Vous pouvez effectuer un test en utilisant le corps de la requête ci-dessus.

Ajout de plus de champs

Si vous devez ajouter plus de champs à votre source de données API, vous devrez le faire via l'interface utilisateur dans les paramètres de votre source de données. Nous ne prenons actuellement pas en charge la mise à jour des champs via l'API.

Ajout d'enregistrements : Clés obligatoires

Point de terminaison : https://app.plecto.com/api/v2/registrations/

Le corps de la requête ci-dessus montre comment ajouter plusieurs enregistrements à la fois. Si vous souhaitez l'utiliser, assurez-vous d'ajouter les UUID data_source et member de votre organisation.

Clés obligatoires à inclure pour chaque enregistrement

Il y a 3 clés obligatoires qui doivent être incluses dans le corps de la requête pour chaque requête API que vous envoyez. Les clés sont les suivantes :

data_source,
member (ou member_api_provider, member_api_id, et member_name), et
external_id.

#1	data_source	La clé data_source nécessite l'UUID de votre source de données. L'UUID est une chaîne alphanumérique que vous pouvez trouver dans l'URL lorsque vous ouvrez une source de données.
#2Choisissez l'un ou l'autre	member	L'utilisation de l'UUID du membre nécessite d'avoir un profil d'employé existant dans Plecto. Pour trouver l'UUID du membre, allez sur la page des employés et cliquez sur un nom. Vous verrez l'UUID dans l'URL.
member_api_providermember_api_idmember_name	Avec cette option, Plecto pourrait créer de nouveaux profils d'employés lorsque vous envoyez les données, et l'employé continuera à être géré par votre système. member_api_provider fait référence au nom de votre système. Dans l'image ci-dessous, le nom du système affiché est Postman. member_api_id fait référence à l'ID du membre de votre système. Dans Plecto, il est affiché sous le champ ID externe. Dans l'image ci-dessous, 101032 représente le member_api_id. Le member_api_provider et le member_api_id identifient ensemble un employé dans Plecto. member_name est le nom du membre. Ce nom sera affiché dans le champ Employé de votre source de données Plecto et peut être mis à jour, à condition que vous utilisiez les mêmes valeurs member_api_provider et member_api_id.
#3	external_id	L'external_id est un nombre ou une chaîne de caractères qui doit être unique pour chaque enregistrement. Cela pourrait être quelque chose comme 123, abc ou tout ce que vous pouvez imaginer. C'est important car ce sera la référence de l'enregistrement créé. Les valeurs d'ID externe dans votre corps de requête sont affichées dans le champ "ID" de votre source de données Plecto.

Puis-je utiliser le même ID externe ?

Si vous envoyez une requête avec le même ID externe que vous avez déjà utilisé, cela écrasera un enregistrement existant dans Plecto et affichera les nouvelles informations mises à jour.

Conventions de nommage – ne vous y trompez pas !

La clé member_api_id dans votre corps de requête représente l'ID externe affiché dans le profil d'employé dans Plecto, et la clé external_id représente l'ID d'enregistrement dans une source de données Plecto.

Enregistrements en masse

Si vous souhaitez attribuer plusieurs enregistrements au même utilisateur, vous pouvez utiliser le même member_api_id. Cependant, la clé external_id doit être différente pour chaque enregistrement, sauf si vous souhaitez écraser un enregistrement existant avec de nouvelles données.

Exemple de base : Ajout d'enregistrements via l'API

Envoyons de nouveaux enregistrements à une source de données Plecto !

La requête pour créer un enregistrement dans une source de données doit utiliser l'URL pour le point de terminaison registrations, qui est le suivant : https://app.plecto.com/api/v2/registrations/
Le corps de la requête POST doit inclure les clés obligatoires plus une clé appelée "Value", puisque la source de données dans Plecto a un champ personnalisé ajouté appelé Value.

Si l'authentification passe et que la requête est correcte, Plecto acceptera l'enregistrement et renverra une réponse réussie. Dans la réponse, "id" est l'UUID de l'enregistrement nouvellement créé ou mis à jour dans Plecto.

Insertion en masse

L'API Plecto prend en charge l'envoi d'une liste d'enregistrements dans un seul corps de requête. Cependant, l'API impose également une limite de 100 enregistrements que vous pouvez envoyer dans une seule requête.

Ci-dessus est un exemple de ce à quoi pourrait ressembler un corps de requête.

Remarque sur les ID externes

Vous ne pouvez pas envoyer plusieurs enregistrements avec le même external_id dans la même requête en masse. Si cela se produit, vous obtiendrez l'erreur suivante :

{ "message": "Enregistrements dupliqués trouvés", "id": "<votre id>" }

Apprenez à créer des employés dans Plecto dans cet article : Comment ajouter des employés à Plecto via l'API

Comment mettre à jour des données existantes via l'API

Point de terminaison : https://app.plecto.com/api/v2/registrations/

Le data_source et external_id identifient un enregistrement dans une source de données dans Plecto. L'external_id représente l'ID d'enregistrement dans Plecto. Si vous souhaitez mettre à jour les valeurs d'enregistrement, envoyez une requête en utilisant les mêmes clés data_source et external_id mais changez les valeurs des champs.
Le member_api_provider et member_api_id identifient un employé dans Plecto. Si vous souhaitez mettre à jour le nom de l'employé, vous pouvez envoyer la même requête mais changer la valeur member_name de, par exemple, "Employé X" à "Curtis Miller".
Vous pouvez envoyer un champ date à Plecto (facultatif). Il apparaîtra dans le champ Date de création de votre source de données. Chaque fois que vous envoyez un enregistrement, Plecto ajoute automatiquement la date et l'heure actuelles. Si vous souhaitez mettre à jour un enregistrement mais conserver la date et l'heure d'origine, ajoutez la clé suivante à votre corps de requête : "date": "2022-12-31T10:22:55"

Format de date

Si vous incluez une clé de date dans le corps de la requête, le format de date doit être conforme à la norme ISO 8601 avec à la fois la date et l'heure.

Le format doit ressembler à ceci : 2018-12-31T22:33:44+00:00 La dernière partie après + est un fuseau horaire optionnel. Si non défini, le fuseau horaire est supposé être UTC.

Aperçu des points de terminaison de l'API Plecto →