Hvordan sende data til Plectos API

Hva er Plecto API?

Plecto API lar utviklere lage en tilpasset avansert integrasjon som gjør det mulig for annen programvare å kommunisere med plattformen vår og eksportere dataene sine til Plecto.

Hvis du vil teste Plecto API manuelt, kan du bruke et gratis program som Postman, men ethvert annet verktøy som kan sende HTTP-forespørsel støttes også.

Autentisering

Autentiseringsordningen som brukes for Plecto API er Basic Authentication. Den inkluderer å sende e-posten din og passordet sammen med forespørselen.
Tips! 💡 Vi anbefaler å opprette en ny bruker (ny ansattprofil) per integrasjon i din Plecto-organisasjon – på denne måten unngår du å dele det samme passordet på tvers av integrasjoner.
Brukeren må ha tilgang til de relevante områdene av Plecto for å lykkes med de fleste API-endepunkter. Hvis Plecto-abonnementet ditt inkluderer avansert tillatelsesadministrasjon, kan du opprette en spesifikk tillatelsesprofil for brukerkontoen.

For å opprette nye ansatte, gå til Innstillinger > Ansatte > Ny ansatt i Plecto eller legg dem til gjennom en API-forespørsel.

Grunnleggende URL og Endepunkter

Alle Plecto API-endepunkter er oppført under følgende grunnleggende URL: https://app.plecto.com/api/v2/

Denne URL-en er grunnlaget for alle endepunkter i Plecto API. Hvis du er logget inn på Plecto-kontoen din, kan du se listen over API-endepunkter direkte i nettleseren.

Hvordan opprette en API-datakilde

Du kan opprette en API-datakilde på to måter:

Send en forespørsel til dette endepunktet: https://app.plecto.com/api/v2/datasources/ Det er nok å inkludere "title" og "fields" nøkler i forespørselen for å opprette datakilden.
Eller gå til Datakilder > Ny datakilde > Plecto API og opprett en ny datakilde fra Plecto-grensesnittet.

Du kan kjøre en test ved å bruke forespørselens kropp ovenfor.

Legge til flere felt

Hvis du trenger å legge til flere felt til API-datakilden din, må du gjøre det gjennom UI i innstillingene for datakilden din. Vi støtter for øyeblikket ikke oppdatering av felt via API.

Legge til registreringer: Obligatoriske nøkler

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

Forespørselens kropp ovenfor viser hvordan du legger til flere registreringer samtidig. Hvis du vil bruke det, må du sørge for å legge til data_source og member UUID-er fra organisasjonen din.

Obligatoriske nøkler å inkludere for hver registrering

Det er 3 obligatoriske nøkler som må inkluderes i forespørselens kropp for hver API-forespørsel du sender. Nøklene er som følger:

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

#1	data_source	Nøkkelen data_source krever UUID-en til datakilden din. UUID-en er en alfanumerisk streng som du kan finne i URL-en når du åpner en datakilde.
#2Velg en eller den andre	member	Bruk av member UUID krever at du har en eksisterende ansattprofil i Plecto. For å finne member UUID, gå til Ansatte-siden og klikk på et navn. Du vil se UUID-en i URL-en.
member_api_providermember_api_idmember_name	Med dette alternativet kan Plecto opprette nye ansattprofiler når du sender dataene, og den ansatte vil fortsette å bli administrert av systemet ditt. member_api_provider refererer til navnet på systemet ditt. I bildet nedenfor er det viste systemnavnet Postman. member_api_id refererer til medlem-ID-en til systemet ditt. I Plecto vises det under feltet Ekstern ID. I bildet nedenfor representerer 101032 member_api_id. member_api_provider og member_api_id identifiserer sammen en ansatt i Plecto. member_name er navnet på medlemmet. Dette navnet vil bli vist i feltet Ansatt i datakilden din i Plecto og kan oppdateres, forutsatt at du bruker de samme verdiene for member_api_provider og member_api_id.
#3	external_id	external_id er et nummer eller en streng av tegn som må være unik for hver registrering. Det kan være noe som 123, abc eller hva som helst du kan tenke på. Dette er viktig da det vil være referansen til den opprettede registreringen. Verdiene for ekstern ID i forespørselens kropp vises i "ID"-feltet i datakilden din i Plecto.

Kan jeg bruke den samme eksterne ID-en?

Hvis du sender en forespørsel med den samme eksterne ID-en som du allerede har brukt, vil det overskrive en eksisterende registrering i Plecto og vise den nye oppdaterte informasjonen.

Navnekonvensjoner – ikke bli forvirret!

Nøkkelen member_api_id i forespørselens kropp representerer Ekstern ID vist i ansattprofilen i Plecto, og nøkkelen external_id representerer Registrerings-ID i en Plecto-datakilde.

Masseregistreringer

Hvis du vil tildele flere registreringer til den samme brukeren, kan du bruke den samme member_api_id. Imidlertid må nøkkelen external_id være forskjellig for hver registrering, med mindre du ønsker å overskrive en eksisterende registrering med nye data.

Grunnleggende eksempel: Legge til registreringer via API

La oss sende nye registreringer til en Plecto-datakilde!

Forespørselen for å opprette en registrering i en datakilde må bruke URL-en for registreringer-endepunktet, som er følgende: https://app.plecto.com/api/v2/registrations/
POST-forespørselens kropp må inkludere de obligatoriske nøklene pluss en nøkkel kalt "Value," siden datakilden i Plecto har et tilpasset felt lagt til som heter Value.

Hvis autentiseringen går gjennom og forespørselen er korrekt, vil Plecto godta registreringen og returnere et vellykket svar. I svaret er "id" UUID-en til den nyopprettede eller oppdaterte registreringen i Plecto.

Masseinnsetting

Plecto API støtter sending av en liste med registreringer i en enkelt forespørsel. Imidlertid håndhever API-en også en grense på 100 registreringer du kan sende i en enkelt forespørsel.

Ovenfor er et eksempel på hvordan en forespørselens kropp kan se ut.

Merk om eksterne ID-er

Du kan ikke sende flere registreringer med den samme external_id i samme masseforespørsel. Hvis det skjer, vil du få følgende feil:

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

Lær hvordan du oppretter ansatte i Plecto i denne artikkelen: Hvordan legge til ansatte i Plecto via API

Hvordan oppdatere eksisterende data via API

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

data_source og external_id identifiserer en registrering i en datakilde i Plecto. external_id representerer registrerings-ID-en i Plecto. Hvis du vil oppdatere registreringsverdiene, sender du en forespørsel med de samme data_source og external_id-nøklene, men endrer feltverdiene.
member_api_provider og member_api_id identifiserer en ansatt i Plecto. Hvis du vil oppdatere ansattnavnet, kan du sende den samme forespørselen, men endre member_name verdien fra for eksempel "Ansatt X" til "Curtis Miller."
Du kan sende et date-felt til Plecto (valgfritt). Det vil vises i feltet Opprettet dato i datakilden din. Hver gang du sender en registrering, legger Plecto automatisk til den nåværende datoen og tiden til den. Hvis du vil oppdatere en registrering, men beholde den opprinnelige datoen og tiden, legg til følgende nøkkel i forespørselens kropp: "date": "2022-12-31T10:22:55"

Datoformat

Hvis du inkluderer en datonøkkel i forespørselens kropp, må datoformatet være i standard ISO 8601 med både dato og tid.

Formatet må se slik ut: 2018-12-31T22:33:44+00:00 Den siste delen etter + er en valgfri tidssone. Hvis ikke angitt, antas tidssonen å være UTC.

Oversikt over Plecto API-endepunkter →