Hoe gegevens naar de Plecto API te verzenden

Wat is de Plecto API?

De Plecto API stelt ontwikkelaars in staat om een aangepaste geavanceerde integratie te creëren die andere software in staat stelt om te communiceren met ons platform en hun gegevens naar Plecto te exporteren.

Als je de Plecto API handmatig wilt testen, kun je een gratis stuk software zoals Postman gebruiken, maar elk ander hulpmiddel dat in staat is om HTTP-verzoeken te verzenden, wordt ook ondersteund.

Authenticatie

Het authenticatieschema dat voor de Plecto API wordt gebruikt, is Basis Authenticatie. Dit omvat het verzenden van je e-mailadres en wachtwoord samen met het verzoek.
Tip! 💡 We raden aan om per integratie een nieuwe gebruiker (nieuw werknemersprofiel) in je Plecto-organisatie te creëren – op deze manier voorkom je dat je hetzelfde wachtwoord over verschillende integraties deelt.
De gebruiker moet toegang hebben tot de relevante gebieden van Plecto om succesvol te zijn met de meeste API-eindpunten. Als je Plecto-abonnement geavanceerd rechtenbeheer omvat, kun je een specifiek toestemmingsprofiel voor het gebruikersaccount maken.

Om nieuwe werknemers te creëren, ga naar Instellingen > Werknemers > Nieuwe werknemer in Plecto of voeg ze toe via een API-verzoek.

Basis-URL en Eindpunten

Alle Plecto API-eindpunten zijn vermeld onder de volgende basis-URL: https://app.plecto.com/api/v2/

Deze URL is de basis voor alle eindpunten van de Plecto API. Als je bent ingelogd op je Plecto-account, kun je de lijst met API-eindpunten rechtstreeks in de browser zien.

Hoe een API-gegevensbron te creëren

Je kunt een API-gegevensbron op twee manieren creëren:

Plaats een verzoek naar dit eindpunt: https://app.plecto.com/api/v2/datasources/ Het is voldoende om de "title" en "fields" sleutels in het verzoek op te nemen om de gegevensbron te creëren.
Of ga naar Gegevensbronnen > Nieuwe gegevensbron > Plecto API en creëer een nieuwe gegevensbron vanuit de Plecto-interface.

Je kunt een test uitvoeren met het verzoeklichaam hierboven.

Meer velden toevoegen

Als je meer velden aan je API-gegevensbron moet toevoegen, moet je dit via de gebruikersinterface in de instellingen van je gegevensbron doen. Momenteel ondersteunen we geen updates van velden via de API.

Registraties toevoegen: Verplichte sleutels

Eindpunt: https://app.plecto.com/api/v2/registrations/

Het verzoeklichaam hierboven toont hoe je meerdere registraties tegelijk kunt toevoegen. Als je dit wilt gebruiken, zorg er dan voor dat je de data_source en member UUID's van je organisatie toevoegt.

Verplichte sleutels om op te nemen voor elke registratie

Er zijn 3 verplichte sleutels die in het verzoeklichaam voor elke API-aanroep die je verzendt, moeten worden opgenomen. De sleutels zijn als volgt:

data_source,
member (of member_api_provider, member_api_id, en member_name), en
external_id.

#1	data_source	De data_source sleutel vereist de UUID van je gegevensbron. De UUID is een alfanumerieke tekenreeks die je in de URL kunt vinden wanneer je een gegevensbron opent.
#2 Kies de een of de ander	member	Het gebruik van de member UUID vereist dat er een bestaand werknemersprofiel in Plecto is. Om de member UUID te vinden, ga naar de pagina Werknemers en klik op een naam. Je ziet de UUID in de URL.
member_api_providermember_api_idmember_name	Met deze optie kan Plecto nieuwe werknemersprofielen aanmaken wanneer je de gegevens verzendt, en de werknemer zal blijven worden beheerd door jouw systeem. member_api_provider verwijst naar de naam van jouw systeem. In de afbeelding hieronder is de weergegeven systeemnaam Postman. member_api_id verwijst naar de member ID van jouw systeem. In Plecto wordt dit weergegeven onder het veld Externe ID. In de afbeelding hieronder vertegenwoordigt 101032 de member_api_id. De member_api_provider en member_api_id identificeren samen een werknemer in Plecto. member_name is de naam van de member. Deze naam wordt weergegeven in het veld Werknemer in jouw Plecto-gegevensbron en kan worden bijgewerkt, mits je dezelfde member_api_provider en member_api_id waarden gebruikt.
#3	external_id	De external_id is een nummer of een tekenreeks die uniek moet zijn voor elke registratie. Het kan iets zijn als 123, abc of iets anders dat je kunt bedenken. Dit is belangrijk omdat het de referentie van de gemaakte registratie zal zijn. De waarden van de externe ID in jouw verzoeklichaam worden weergegeven in het "ID" veld in jouw Plecto-gegevensbron.

Kan ik dezelfde externe ID gebruiken?

Als je een verzoek verzendt met dezelfde externe ID als die je al hebt gebruikt, zal het een bestaande registratie in Plecto overschrijven en de nieuwe bijgewerkte informatie weergeven.

Naamgevingsconventies – raak niet in de war!

De member_api_id sleutel in jouw verzoeklichaam vertegenwoordigt de Externe ID die wordt weergegeven in het werknemersprofiel in Plecto, en de external_id sleutel vertegenwoordigt de Registratie-ID in een Plecto-gegevensbron.

Bulkregistraties

Als je meerdere registraties aan dezelfde gebruiker wilt toewijzen, kun je dezelfde member_api_id gebruiken. De external_id sleutel moet echter verschillend zijn voor elke registratie, tenzij je een bestaande registratie met nieuwe gegevens wilt overschrijven.

Basisvoorbeeld: Registraties toevoegen via API

Laten we nieuwe registraties naar een Plecto-gegevensbron verzenden!

Het verzoek om een registratie in een gegevensbron te creëren, moet de URL voor het registrations eindpunt gebruiken, welke de volgende is: https://app.plecto.com/api/v2/registrations/
Het POST-verzoeklichaam moet de verplichte sleutels plus een sleutel genaamd "Value" bevatten, aangezien de gegevensbron in Plecto een aangepast veld heeft dat Value wordt genoemd.

Als de authenticatie slaagt en het verzoek correct is, zal Plecto de registratie accepteren en een succesvolle reactie retourneren. In de reactie is de "id" de UUID van de nieuw aangemaakte of bijgewerkte registratie in Plecto.

Bulkinvoer

De Plecto API ondersteunt het verzenden van een lijst met registraties in één verzoeklichaam. De API handhaaft echter ook een limiet van 100 registraties die je in één verzoek kunt verzenden.

Hierboven is een voorbeeld van hoe een verzoeklichaam eruit zou kunnen zien.

Opmerking over externe ID's

Je kunt geen meerdere registraties met dezelfde external_id in dezelfde bulkaanvraag verzenden. Als dat gebeurt, krijg je de volgende fout:

{ "message": "Duplicated registrations found", "id": "<your id>" }

Leer hoe je werknemers in Plecto kunt creëren in dit artikel: Hoe werknemers aan Plecto toe te voegen via API

Hoe bestaande gegevens via API bij te werken

Eindpunt: https://app.plecto.com/api/v2/registrations/

De data_source en external_id identificeren een registratie in een gegevensbron in Plecto. De external_id vertegenwoordigt de registratie-ID in Plecto. Als je de registratiewaarden wilt bijwerken, stuur dan een verzoek met dezelfde data_source en external_id sleutels maar wijzig de veldwaarden.
De member_api_provider en member_api_id identificeren een werknemer in Plecto. Als je de naam van de werknemer wilt bijwerken, kun je hetzelfde verzoek verzenden maar de member_name waarde wijzigen van bijvoorbeeld "Werknemer X" naar "Curtis Miller."
Je kunt een date veld naar Plecto verzenden (optioneel). Dit zal worden weergegeven in het Aangemaakte datum veld in jouw gegevensbron. Wanneer je een registratie verzendt, voegt Plecto automatisch de huidige datum en tijd eraan toe. Als je een registratie wilt bijwerken maar de oorspronkelijke datum en tijd wilt behouden, voeg dan de volgende sleutel toe aan jouw verzoeklichaam: "date": "2022-12-31T10:22:55"

Datumformaat

Als je een datum sleutel in het verzoeklichaam opneemt, moet het datumformaat voldoen aan de standaard ISO 8601 met zowel datum als tijd.

Het formaat moet er als volgt uitzien: 2018-12-31T22:33:44+00:00 Het laatste deel na + is een optionele tijdzone. Als deze niet is ingesteld, wordt de tijdzone verondersteld te zijn UTC.

Overzicht van Plecto API Eindpunten →