Hvordan man sender data til Plectos API

Hvad er Plecto API?

Plecto API gør det muligt for udviklere at oprette en tilpasset avanceret integration, som gør det muligt for anden software at kommunikere med vores platform og eksportere deres data til Plecto.

Hvis du vil teste Plecto API manuelt, kan du bruge et gratis stykke software som Postman, men ethvert andet værktøj, der kan sende HTTP-anmodninger, understøttes også.

Autentificering

Autentificeringsmetoden, der bruges til Plecto API, er Basic Authentication. Den indebærer, at du sender din e-mail og adgangskode sammen med anmodningen.
Tip! 💡 Vi anbefaler, at du opretter en ny bruger (ny medarbejderprofil) pr. integration i din Plecto-organisation – på denne måde undgår du at dele den samme adgangskode på tværs af integrationer.
Brugeren skal have adgang til de relevante områder af Plecto for at kunne bruge de fleste API-endpoints. Hvis dit Plecto-abonnement inkluderer avanceret tilladelsesstyring, kan du oprette en specifik tilladelsesprofil til brugerkontoen.

For at oprette nye medarbejdere skal du gå til Indstillinger > Medarbejdere > Ny medarbejder i Plecto eller tilføje dem via en API-anmodning.

Base-URL og endpoints

Alle Plecto API-endpoints er listet under følgende base-URL: https://app.plecto.com/api/v2/

Denne URL er grundlaget for alle endpoints i Plecto API. Hvis du er logget ind på din Plecto-konto, kan du se listen over API-endpoints direkte i browseren.

Sådan opretter du en API-datakilde

Du kan oprette en API-datakilde på to måder:

Send en anmodning til dette endpoint: https://app.plecto.com/api/v2/datasources/ Det er tilstrækkeligt at inkludere nøglerne "title" og "fields" i anmodningen for at oprette datakilden.
Eller gå til Datakilder > Ny datakilde > Plecto API og opret en ny datakilde fra Plecto-brugerfladen.

Du kan køre en test ved hjælp af anmodningsteksten ovenfor.

Tilføjelse af flere felter

Hvis du har brug for at tilføje flere felter til din API-datakilde, skal du gøre det via brugerfladen i indstillingerne for din datakilde. Vi understøtter i øjeblikket ikke opdatering af felter via API'et.

Tilføjelse af registreringer: Obligatoriske nøgler

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

Anmodningsteksten ovenfor viser, hvordan du tilføjer flere registreringer på én gang. Hvis du vil bruge den, skal du sørge for at tilføje data_source- og member-UUID'erne fra din organisation.

Obligatoriske nøgler, der skal inkluderes for hver registrering

Der er 3 obligatoriske nøgler, som skal inkluderes i anmodningsteksten for hver API-anmodning, du sender. Nøglerne er følgende:

data_source,
member (eller member_api_provider, member_api_id og member_name), og
external_id.

#1	data_source	data_source-nøglen kræver din datakildes UUID. UUID'en er en alfanumerisk streng, som du kan finde i URL'en, når du åbner en datakilde.
#2Vælg den ene eller den anden	member	Brug af member-UUID kræver en eksisterende medarbejderprofil i Plecto. For at finde member-UUID'en skal du gå til siden Medarbejdere og klikke på et navn. Du vil se UUID'en i URL'en.
member_api_providermember_api_idmember_name	Med denne mulighed kan Plecto oprette nye medarbejderprofiler, når du sender dataene, og medarbejderen vil fortsat blive administreret af dit system. member_api_provider henviser til navnet på dit system. På billedet nedenfor er det viste systemnavn Postman. member_api_id henviser til medarbejder-id'et i dit system. I Plecto vises det under feltet External ID. På billedet nedenfor repræsenterer 101032 member_api_id. member_api_provider og member_api_id identificerer tilsammen en medarbejder i Plecto. member_name er navnet på medarbejderen. Dette navn vil blive vist i feltet Medarbejder i din Plecto-datakilde og kan opdateres, forudsat at du bruger de samme værdier for member_api_provider og member_api_id.
#3	external_id	external_id er et tal eller en tegnstreng, som skal være unik for hver registrering. Det kunne være noget i stil med 123, abc eller hvad som helst, du kan finde på. Dette er vigtigt, da det vil være referencen for den oprettede registrering. Værdierne for external ID i din anmodningstekst vises i feltet "ID" i din Plecto-datakilde.

Kan jeg bruge det samme external ID?

Hvis du sender en anmodning med det samme external ID, som du allerede har brugt, vil det overskrive en eksisterende registrering i Plecto og vise de nye opdaterede oplysninger.

Navngivningskonventioner – lad dig ikke forvirre!

Nøglen member_api_id i din anmodningstekst repræsenterer External ID, som vises i medarbejderprofilen i Plecto, og nøglen external_id repræsenterer Registration ID i en Plecto-datakilde.

Bulk-registreringer

Hvis du vil tildele flere registreringer til den samme bruger, kan du bruge det samme member_api_id. Nøglen external_id skal dog være forskellig for hver registrering, medmindre du ønsker at overskrive en eksisterende registrering med nye data.

Grundlæggende eksempel: Tilføjelse af registreringer via API

Lad os sende nye registreringer til en Plecto-datakilde!

Anmodningen om at oprette en registrering i en datakilde skal bruge URL'en for registrations-endpointet, som er følgende: https://app.plecto.com/api/v2/registrations/
POST-anmodningsteksten skal inkludere de obligatoriske nøgler samt en nøgle kaldet "Value", da datakilden i Plecto har et tilpasset felt kaldet Value tilføjet.

Hvis autentificeringen godkendes, og anmodningen er korrekt, vil Plecto acceptere registreringen og returnere et vellykket svar. I svaret er "id" UUID'en for den nyoprettede eller opdaterede registrering i Plecto.

Bulk-indsættelse

Plecto API understøtter afsendelse af en liste over registreringer i én enkelt anmodningstekst. API'et håndhæver dog også en grænse på 100 registreringer, som du kan sende i én enkelt anmodning.

Ovenfor er et eksempel på, hvordan en anmodningstekst kunne se ud.

Bemærkning om external ID'er

Du kan ikke sende flere registreringer med det samme external_id i den samme bulk-anmodning. Hvis det sker, vil du få følgende fejl:

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

Lær, hvordan du opretter medarbejdere i Plecto i denne artikel: Sådan tilføjer du medarbejdere til Plecto via API

Sådan opdaterer du eksisterende data via API

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

data_source og external_id identificerer en registrering i en datakilde i Plecto. external_id repræsenterer registrerings-id'et i Plecto. Hvis du vil opdatere registreringsværdierne, skal du sende en anmodning med de samme data_source- og external_id-nøgler, men ændre feltværdierne.
member_api_provider og member_api_id identificerer en medarbejder i Plecto. Hvis du vil opdatere medarbejderens navn, kan du sende den samme anmodning, men ændre værdien for member_name fra f.eks. "Employee X" til "Curtis Miller."
Du kan sende et date-felt til Plecto (valgfrit). Det vil blive vist i feltet Oprettelsesdato i din datakilde. Når du sender en registrering, tilføjer Plecto automatisk den aktuelle dato og det aktuelle klokkeslæt til den. Hvis du vil opdatere en registrering, men beholde den oprindelige dato og det oprindelige klokkeslæt, skal du tilføje følgende nøgle til din anmodningstekst: "date": "2022-12-31T10:22:55"

Datoformat

Hvis du inkluderer en date-nøgle i anmodningsteksten, skal datoformatet følge standarden ISO 8601 med både dato og klokkeslæt.

Formatet skal se sådan ud: 2018-12-31T22:33:44+00:00 Den sidste del efter + er en valgfri tidszone. Hvis den ikke er angivet, antages tidszonen at være UTC.

Oversigt over Plecto API-endpoints →