So senden Sie Daten an die Plecto-API

Was ist die Plecto-API?

Die Plecto-API ermöglicht es Entwicklern, eine benutzerdefinierte, erweiterte Integration zu erstellen, mit der andere Software mit unserer Plattform kommunizieren und ihre Daten zu Plecto exportieren kann.

Wenn Sie die Plecto-API manuell testen möchten, können Sie eine kostenlose Software wie Postman verwenden, aber auch jedes andere Tool, das HTTP-Anfragen senden kann, wird unterstützt.

Authentifizierung

Das für die Plecto-API verwendete Authentifizierungsschema ist die Basic Authentication. Dabei werden Ihre E-Mail-Adresse und Ihr Passwort zusammen mit der Anfrage gesendet.
Tipp! 💡 Wir empfehlen, pro Integration in Ihrer Plecto-Organisation einen neuen Benutzer (neues Mitarbeiterprofil) zu erstellen – so vermeiden Sie, dass dasselbe Passwort für mehrere Integrationen verwendet wird.
Der Benutzer muss Zugriff auf die relevanten Bereiche von Plecto haben, um die meisten API-Endpunkte erfolgreich nutzen zu können. Wenn Ihr Plecto-Abonnement eine erweiterte Berechtigungsverwaltung umfasst, können Sie ein spezifisches Berechtigungsprofil für das Benutzerkonto erstellen.

Um neue Mitarbeiter anzulegen, gehen Sie in Plecto zu Einstellungen > Mitarbeiter > Neuer Mitarbeiter oder fügen Sie sie über eine API-Anfrage hinzu.

Basis-URL und Endpunkte

Alle Plecto-API-Endpunkte sind unter der folgenden Basis-URL aufgelistet: https://app.plecto.com/api/v2/

Diese URL ist die Grundlage für alle Endpunkte der Plecto-API. Wenn Sie in Ihrem Plecto-Konto angemeldet sind, können Sie die Liste der API-Endpunkte direkt im Browser sehen.

So erstellen Sie eine API-Datenquelle

Sie können eine API-Datenquelle auf zwei Arten erstellen:

Senden Sie eine Anfrage an diesen Endpunkt: https://app.plecto.com/api/v2/datasources/ Es genügt, die Schlüssel "title" und "fields" in die Anfrage aufzunehmen, um die Datenquelle zu erstellen.
Oder gehen Sie zu Datenquellen > Neue Datenquelle > Plecto API und erstellen Sie eine neue Datenquelle über die Plecto-Oberfläche.

Sie können mit dem obigen Anfragetext einen Test durchführen.

Weitere Felder hinzufügen

Wenn Sie Ihrer API-Datenquelle weitere Felder hinzufügen müssen, müssen Sie dies über die Benutzeroberfläche in den Einstellungen Ihrer Datenquelle tun. Wir unterstützen derzeit keine Aktualisierung von Feldern über die API.

Registrierungen hinzufügen: Erforderliche Schlüssel

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

Der obige Anfragetext zeigt, wie Sie mehrere Registrierungen gleichzeitig hinzufügen können. Wenn Sie dies nutzen möchten, stellen Sie sicher, dass Sie die UUIDs von data_source und member aus Ihrer Organisation hinzufügen.

Erforderliche Schlüssel für jede Registrierung

Es gibt 3 erforderliche Schlüssel, die in den Anfragetext jeder API-Anfrage aufgenommen werden müssen, die Sie senden. Die Schlüssel sind die folgenden:

data_source,
member (oder member_api_provider, member_api_id und member_name), und
external_id.

#1	data_source	Der Schlüssel data_source erfordert die UUID Ihrer Datenquelle. Die UUID ist eine alphanumerische Zeichenfolge, die Sie in der URL finden, wenn Sie eine Datenquelle öffnen.
#2Wählen Sie eine der beiden Optionen	member	Die Verwendung der member-UUID erfordert ein bestehendes Mitarbeiterprofil in Plecto. Um die member-UUID zu finden, gehen Sie zur Seite Mitarbeiter und klicken Sie auf einen Namen. Sie sehen die UUID in der URL.
member_api_providermember_api_idmember_name	Mit dieser Option kann Plecto beim Senden der Daten neue Mitarbeiterprofile erstellen, und der Mitarbeiter wird weiterhin von Ihrem System verwaltet. member_api_provider bezieht sich auf den Namen Ihres Systems. Im Bild unten lautet der angezeigte Systemname Postman. member_api_id bezieht sich auf die Mitarbeiter-ID in Ihrem System. In Plecto wird sie unter dem Feld External ID angezeigt. Im Bild unten steht 101032 für die member_api_id. member_api_provider und member_api_id identifizieren zusammen einen Mitarbeiter in Plecto. member_name ist der Name des Mitarbeiters. Dieser Name wird im Feld Mitarbeiter in Ihrer Plecto-Datenquelle angezeigt und kann aktualisiert werden, sofern Sie dieselben Werte für member_api_provider und member_api_id verwenden.
#3	external_id	Die external_id ist eine Zahl oder eine Zeichenfolge, die für jede Registrierung eindeutig sein muss. Sie könnte zum Beispiel 123, abc oder etwas anderes sein, das Sie sich ausdenken. Dies ist wichtig, da es die Referenz der erstellten Registrierung sein wird. Die external-ID-Werte in Ihrem Anfragetext werden im Feld "ID" in Ihrer Plecto-Datenquelle angezeigt.

Kann ich dieselbe external ID verwenden?

Wenn Sie eine Anfrage mit derselben external ID senden, die Sie bereits verwendet haben, wird eine bestehende Registrierung in Plecto überschrieben und die neuen aktualisierten Informationen angezeigt.

Namenskonventionen – lassen Sie sich nicht verwirren!

Der Schlüssel member_api_id in Ihrem Anfragetext entspricht der External ID, die im Mitarbeiterprofil in Plecto angezeigt wird, und der Schlüssel external_id entspricht der Registration ID in einer Plecto-Datenquelle.

Massenregistrierungen

Wenn Sie mehrere Registrierungen demselben Benutzer zuweisen möchten, können Sie dieselbe member_api_id verwenden. Der Schlüssel external_id muss jedoch für jede Registrierung unterschiedlich sein, es sei denn, Sie möchten eine bestehende Registrierung mit neuen Daten überschreiben.

Einfaches Beispiel: Registrierungen über die API hinzufügen

Senden wir neue Registrierungen an eine Plecto-Datenquelle!

Die Anfrage zum Erstellen einer Registrierung in einer Datenquelle muss die URL für den registrations-Endpunkt verwenden, die wie folgt lautet: https://app.plecto.com/api/v2/registrations/
Der POST-Anfragetext muss die erforderlichen Schlüssel sowie einen Schlüssel namens "Value" enthalten, da die Datenquelle in Plecto über ein benutzerdefiniertes Feld namens Value verfügt.

Wenn die Authentifizierung erfolgreich ist und die Anfrage korrekt ist, akzeptiert Plecto die Registrierung und gibt eine erfolgreiche Antwort zurück. In der Antwort ist die "id" die UUID der neu erstellten oder aktualisierten Registrierung in Plecto.

Massenerstellung

Die Plecto-API unterstützt das Senden einer Liste von Registrierungen in einem einzigen Anfragetext. Die API setzt jedoch auch eine Grenze von 100 Registrierungen fest, die Sie in einer einzigen Anfrage senden können.

Oben sehen Sie ein Beispiel dafür, wie ein Anfragetext aussehen könnte.

Hinweis zu external IDs

Sie können keine mehreren Registrierungen mit derselben external_id in derselben Massenanfrage senden. Wenn dies geschieht, erhalten Sie den folgenden Fehler:

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

Erfahren Sie in diesem Artikel, wie Sie Mitarbeiter in Plecto erstellen: So fügen Sie Mitarbeiter über die API zu Plecto hinzu

So aktualisieren Sie vorhandene Daten über die API

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

data_source und external_id identifizieren eine Registrierung in einer Datenquelle in Plecto. Die external_id entspricht der Registrierungs-ID in Plecto. Wenn Sie die Registrierungswerte aktualisieren möchten, senden Sie eine Anfrage mit denselben data_source- und external_id-Schlüsseln, ändern jedoch die Feldwerte.
member_api_provider und member_api_id identifizieren einen Mitarbeiter in Plecto. Wenn Sie den Namen des Mitarbeiters aktualisieren möchten, können Sie dieselbe Anfrage senden, aber den Wert von member_name ändern, z. B. von "Employee X" zu "Curtis Miller."
Sie können ein date-Feld an Plecto senden (optional). Es wird im Feld Erstellungsdatum in Ihrer Datenquelle angezeigt. Wann immer Sie eine Registrierung senden, fügt Plecto automatisch das aktuelle Datum und die aktuelle Uhrzeit hinzu. Wenn Sie eine Registrierung aktualisieren, aber das ursprüngliche Datum und die ursprüngliche Uhrzeit beibehalten möchten, fügen Sie den folgenden Schlüssel zu Ihrem Anfragetext hinzu: "date": "2022-12-31T10:22:55"

Datumsformat

Wenn Sie einen date-Schlüssel in den Anfragetext aufnehmen, muss das Datumsformat dem Standard ISO 8601 mit Datum und Uhrzeit entsprechen.

Das Format muss wie folgt aussehen: 2018-12-31T22:33:44+00:00 Der letzte Teil nach dem + ist eine optionale Zeitzone. Ist sie nicht angegeben, wird davon ausgegangen, dass die Zeitzone UTC ist.

Übersicht der Plecto-API-Endpunkte →