Bevor Sie beginnen
Über die API kann eine autorisierte Integration mit Informationen aus Talento arbeiten. Jeder Zugang gehört zu einer aktiven Person des Unternehmens: Anfragen werden mit deren Berechtigungen und innerhalb desselben Kontos ausgeführt.
So gilt dieselbe Zugriffskontrolle wie in der Anwendung. Damit gehören die Wahl der Identität, ihre Berechtigungen und die sichere Verwahrung des Tokens zur Sicherheit der Integration.
Hinweis
Ein API-Token funktioniert wie ein Passwort. Fügen Sie es nicht in Chats, Tickets, Dokumente, Webadressen oder Quellcode-Repositories ein. Speichern Sie es in der Geheimnisverwaltung der Integration und übertragen Sie es ausschließlich über HTTPS.
Eine Anfrage mit Bearer authentifizieren
Senden Sie das Token im HTTP-Header Authorization mit dem Schema Bearer:
Authorization: Bearer DEIN_TOKEN
Ersetzen Sie DEIN_TOKEN in der sicheren Konfiguration der Integration. Schreiben Sie den echten Wert weder in Beispiele, Protokolle noch Quellcode. Richten Sie Anfragen an die Adresse des Unternehmens und die für den Vorgang dokumentierte API-Ressource.
Die API prüft vor Annahme der Anfrage drei Bedingungen:
- Das Token ist gültig.
- Der API-Zugang und die zugehörige Person sind weiterhin aktiv.
- Die Person besitzt die Berechtigung für den angeforderten Vorgang.
Protokollieren Sie Fehler und die für den Support benötigten technischen Kennungen. Konfigurieren Sie die Anwendung jedoch so, dass der Header Authorization und alle Geheimnisse ausgeblendet werden.
Lead-Kennzahlen ohne eigenen Endpunkt senden
Ein externes Produkt kann allgemeine benutzerdefinierte Lead-Felder verwenden, ohne einen eigenen Talento-Endpunkt zu benötigen. Erstellen oder ändern Sie zunächst unter /api/v3/custom_field_definitions eine Definition mit target_type: "Lead", einem skalaren field_type und track_history: true. Definitionen und Auswahloptionen verwenden ihre öffentlichen UUIDs. Beim Erstellen eines Leads werden stets alle verpflichtenden Lead-Felder geprüft, auch wenn custom_fields fehlt.
Senden Sie jede Messung an /api/v3/leads/{lead_uuid}/custom_field_observations: mit Definitions-UUID, typgerechtem value und optional mit ISO-8601-observed_at, source und idempotency_key. Der Wert kann skalar, für Währungen { "amount": 18, "currency_code": "eur" } oder zum Leeren null sein. Dieselbe Idempotenzkennung mit derselben kanonischen Anfrage liefert die ursprüngliche Beobachtung; eine geänderte Anfrage liefert 409. Ungültige Werte, ausgeschaltete Verfolgung oder Zeitpunkte mehr als fünf Minuten in der Zukunft liefern 422.
Rufen Sie dieselbe Ressource als Liste ab, um den Verlauf neueste zuerst zu erhalten und nach Definition oder Beobachtungsdatum zu filtern. Lead-Listen- und Detailantworten enthalten vorhandene Feldwertzeilen einschließlich observed_at und source; eine nie gesetzte Definition wird ausgelassen.
Eine nicht autorisierte Antwort beheben
Prüfen Sie bei 401 Nicht autorisiert in dieser Reihenfolge:
- Verwendet der Header exakt das Schema
Bearer, und wird das Token nicht in der URL gesendet? - Ist das konfigurierte Geheimnis das aktuelle Token und kein Wert von vor einer Rotation?
- Ist der API-Zugang weiterhin aktiv?
- Ist die Person aktiv und gehört sie zu dem Unternehmen, über dessen Adresse die Anfrage erfolgt?
- Sind Adresse und angeforderte Ressource korrekt?
Funktioniert die Authentifizierung, aber ein einzelner Vorgang bleibt untersagt, prüfen Sie die Berechtigungen der Person. Vergeben Sie nur den unbedingt notwendigen Zugriff; machen Sie die Identität nicht zur Administration, um eine begrenzte Integration zu reparieren.
Häufige Probleme
Wenn eine Option fehlt, kann dies an Ihren Berechtigungen, den aktiven Modulen oder der Unternehmenskonfiguration liegen. Bitten Sie die Administration, den Zugriff zu prüfen. Sie müssen die Aufgabe weder wiederholen noch eine unpassende Alternative wählen.