Hur man skickar data till Plectos API

Vad är Plecto API?

Plecto API möjliggör för utvecklare att skapa en anpassad avancerad integration som gör det möjligt för annan mjukvara att kommunicera med vår plattform och exportera sin data till Plecto.

Om du vill testa Plecto API manuellt kan du använda en gratis programvara som Postman, men vilket annat verktyg som kan skicka HTTP-förfrågningar stöds också.

Autentisering

Det autentiseringsschema som används för Plecto API är Basic Authentication. Det inkluderar att skicka din e-post och lösenord tillsammans med förfrågan.
Tips! 💡 Vi rekommenderar att skapa en ny användare (ny anställd profil) per integration i din Plecto-organisation – på så sätt undviker du att dela samma lösenord mellan integrationer.
Användaren måste ha åtkomst till de relevanta områdena i Plecto för att lyckas med de flesta API-slutpunkter. Om din Plecto-prenumeration inkluderar avancerad behörighetsadministration kan du skapa en specifik behörighetsprofil för användarkontot.

För att skapa nya anställda, gå till Inställningar > Anställda > Ny anställd i Plecto eller lägg till dem genom en API-förfrågan.

Bas-URL och slutpunkter

Alla Plecto API-slutpunkter listas under följande bas-URL: https://app.plecto.com/api/v2/

Denna URL är grunden för alla slutpunkter i Plecto API. Om du är inloggad på ditt Plecto-konto kan du se listan över API-slutpunkter direkt i webbläsaren.

Hur man skapar en API-datakälla

Du kan skapa en API-datakälla på två sätt:

Skicka en förfrågan till denna slutpunkt: https://app.plecto.com/api/v2/datasources/ Det räcker att inkludera "title" och "fields" nycklar i förfrågan för att skapa datakällan.
Eller gå till Datakällor > Ny datakälla > Plecto API och skapa en ny datakälla från Plecto-gränssnittet.

Du kan köra ett test med förfrågningskroppen ovan.

Lägga till fler fält

Om du behöver lägga till fler fält till din API-datakälla, måste du göra det via användargränssnittet i inställningarna för din datakälla. Vi stöder för närvarande inte att uppdatera fält via API.

Lägga till registreringar: Obligatoriska nycklar

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

Förfrågningskroppen ovan visar hur man lägger till flera registreringar på en gång. Om du vill använda det, se till att lägga till data_source och member UUID:er från din organisation.

Obligatoriska nycklar att inkludera för varje registrering

Det finns 3 obligatoriska nycklar som måste inkluderas i förfrågningskroppen för varje API-förfrågan som du skickar. Nycklarna är följande:

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

#1	data_source	Nyckeln data_source kräver UUID för din datakälla. UUID är en alfanumerisk sträng som du kan hitta i URL:en när du öppnar en datakälla.
#2Välj en eller den andra	member	Att använda member UUID kräver att du har en befintlig anställd profil i Plecto. För att hitta member UUID, gå till sidan Anställda och klicka på ett namn. Du kommer att se UUID:en i URL:en.
member_api_providermember_api_idmember_name	Med detta alternativ kan Plecto skapa nya anställda profiler när du skickar datan, och den anställde kommer att fortsätta att hanteras av ditt system. member_api_provider hänvisar till namnet på ditt system. I bilden nedan är det visade systemnamnet Postman. member_api_id hänvisar till medlem-ID:t för ditt system. I Plecto visas det under fältet Extern ID. I bilden nedan representerar 101032 member_api_id. member_api_provider och member_api_id identifierar tillsammans en anställd i Plecto. member_name är namnet på medlemmen. Detta namn kommer att visas i fältet Anställd i din Plecto datakälla och kan uppdateras, förutsatt att du använder samma member_api_provider och member_api_id värden.
#3	external_id	external_id är ett nummer eller en sträng av tecken som måste vara unik för varje registrering. Det kan vara något som 123, abc eller vad som helst du kan tänka dig. Detta är viktigt eftersom det kommer att vara referensen för den skapade registreringen. Värdena för extern ID i din förfrågningskropp visas i fältet "ID" i din Plecto datakälla.

Kan jag använda samma externa ID?

Om du skickar en förfrågan med samma externa ID som du redan har använt, kommer det att skriva över en befintlig registrering i Plecto och visa den nya uppdaterade informationen.

Namngivningskonventioner – bli inte förvirrad!

Nyckeln member_api_id i din förfrågningskropp representerar Extern ID som visas i den anställdas profil i Plecto, och nyckeln external_id representerar Registrerings-ID i en Plecto datakälla.

Bulkregistreringar

Om du vill tilldela flera registreringar till samma användare kan du använda samma member_api_id. Men external_id nyckeln måste vara olika för varje registrering, om du inte vill skriva över en befintlig registrering med ny data.

Grundläggande exempel: Lägga till registreringar via API

Låt oss skicka nya registreringar till en Plecto datakälla!

Förfrågan för att skapa en registrering i en datakälla måste använda URL:en för registrations slutpunkten, som är följande: https://app.plecto.com/api/v2/registrations/
Förfrågningskroppen för POST måste inkludera de obligatoriska nycklarna plus en nyckel som heter "Value", eftersom datakällan i Plecto har ett anpassat fält som lagts till som heter Value.

Om autentiseringen går igenom och förfrågan är korrekt, kommer Plecto att acceptera registreringen och returnera ett framgångsrikt svar. I svaret är "id" UUID:en för den nyss skapade eller uppdaterade registreringen i Plecto.

Bulkinsättning

Plecto API stöder att skicka en lista med registreringar i en enda förfrågningskropp. API:t upprätthåller dock också en gräns på 100 registreringar som du kan skicka i en enda förfrågan.

Ovan är ett exempel på hur en förfrågningskropp kan se ut.

Notera om externa ID:n

Du kan inte skicka flera registreringar med samma external_id i samma bulkförfrågan. Om det händer får du följande fel:

{ "message": "Duplicerade registreringar hittades", "id": "<ditt id>" }

Lär dig hur man skapar anställda i Plecto i denna artikel: Hur man lägger till anställda till Plecto via API

Hur man uppdaterar befintlig data via API

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

data_source och external_id identifierar en registrering i en datakälla i Plecto. external_id representerar registrerings-ID:t i Plecto. Om du vill uppdatera registreringsvärdena, skicka en förfrågan med samma data_source och external_id nycklar men ändra fältvärdena.
member_api_provider och member_api_id identifierar en anställd i Plecto. Om du vill uppdatera namnet på den anställde kan du skicka samma förfrågan men ändra member_name värdet från, till exempel, "Anställd X" till "Curtis Miller."
Du kan skicka ett date fält till Plecto (valfritt). Det kommer att visas i fältet Skapat datum i din datakälla. När du skickar en registrering lägger Plecto automatiskt till det aktuella datumet och tiden. Om du vill uppdatera en registrering men behålla det ursprungliga datumet och tiden, lägg till följande nyckel i din förfrågningskropp: "date": "2022-12-31T10:22:55"

Datumformat

Om du inkluderar en datumnyckel i förfrågningskroppen måste datumformatet vara av standard ISO 8601 med både datum och tid.

Formatet måste se ut så här: 2018-12-31T22:33:44+00:00 Den sista delen efter + är en valfri tidszon. Om den inte anges antas tidszonen vara UTC.

Översikt över Plecto API-slutpunkter →