Erstellen Sie einen Human Token-Prozess von Ihrem Back-End aus und erhalten Sie den humanToken in data.humanToken.
Human Token läuft auf dem Endpunkt POST /client/v1/process der Human API. Mit den API Only-Flows (api+humantoken, api+liveness+humantoken und api+liveness+humantoken+revalidation) wird der Prozess in einem einzigen Aufruf erstellt und abgeschlossen: Die Antwort enthält das Ergebnis bereits in data.humanToken. Mit den Human Token Journey-Flows (humantoken und humantoken+revalidation) enthält die Antwort die id des Prozesses, einen token und den link der Journey, und das Ergebnis ist verfügbar, nachdem der Nutzer die Journey abgeschlossen hat. Die +revalidation-Flows erfordern ein references-Array mit einem zuvor erhaltenen humanToken zur Revalidierung.
Flows
Human Token wird in zwei Integrationsmodellen ausgeführt:
- API Only — Ihr Back-End sendet das Selfie in
imageBase64. - Human Token Journey — der Nutzer durchläuft die Human Token Journey im Web und kehrt zu Ihrer
callbackUrizurück.
| Flow | Capabilities | Possible result | Integration components required | Example |
|---|---|---|---|---|
api+humantoken | Human Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken | LivenessHuman Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
humantoken | LivenessHuman Token | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb | |
humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb |
Endpunkt
| Umgebung | URL |
|---|---|
| Produktion | POST https://humantoken.unico.app/client/v1/process |
Request
| Header | Wert |
|---|---|
x-unico-accesskey | <your_access_key> (siehe Authentifizierung) |
Content-Type | application/json |
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
flow | string | ja | Human Token-Flow: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) oder humantoken, humantoken+revalidation (Human Token Journey). Siehe Flows. |
imageBase64 | string | API Only | Das von Ihrem Front-End erfasste und direkt gesendete Selfie, base64-kodiert. PNG, JPEG oder WebP, bis zu 800 KB. Befolgen Sie den Aufnahmestandard. |
callbackUri | string | Human Token Journey | URL, an die der Nutzer nach Abschluss der Journey weitergeleitet wird. |
companyBranchId | string | nein | Branch-Kennung. Wenn angegeben, verwendet der Prozess die Konfiguration des angegebenen Branches. |
references | array | Revalidierungs-Flows | Array von Referenzobjekten. Erforderlich für +revalidation-Flows. Jedes Objekt enthält referenceType (REFERENCE_TYPE_HUMAN_TOKEN) und referenceContent (den zuvor erhaltenen humanToken-Wert). |
Antworten
| Feld | Typ | Beschreibung |
|---|---|---|
id | string (UUID) | Prozesskennung. Verwenden Sie sie, um den Prozess über Prozess abrufen erneut abzurufen. |
state | string | Prozesszustand — siehe Ergebnis interpretieren. Nur in den API Only-Flows. |
token | string | Token des erstellten Prozesses, Sie können diesen verwenden, um die Journey SDK-Erfahrung zu öffnen. Nur in den Human Token Journey-Flows (humantoken, humantoken+revalidation). |
link | string | URL der Human Token Journey: Leiten Sie den Nutzer dorthin. Nur in den Human Token Journey-Flows (humantoken, humantoken+revalidation). |
data.humanToken.value | string | Stabiler, opaker Bezeichner des Gesichts (bis zu 100 Zeichen). Dieselbe Person ergibt immer denselben Wert. Nur in den API Only-Flows (ohne Revalidierung). |
data.humanTokenMatch | string | "true", wenn das Selfie mit dem referenzierten humanToken übereinstimmt, andernfalls "false". Nur im +revalidation API Only-Flow. |
state | Bedeutung | Vorgehen |
|---|---|---|
PROCESS_STATE_FINISHED | data.humanToken.value gefüllt: echte Person, mit Human Token. | Suchen Sie value in Ihren Datensätzen: Ist der Wert vorhanden, handelt es sich um einen wiederkehrenden Nutzer oder ein mögliches Duplikat; andernfalls um eine neue Person. |
PROCESS_STATE_FINISHED | Kein data.humanToken oder leeres value: nicht eindeutig. | Behandeln Sie das Ergebnis als nicht eindeutig. Speichern oder vergleichen Sie niemals einen leeren value; wiederholen Sie den Prozess oder lehnen Sie ihn ab, je nach Ihren Geschäftsregeln. |
PROCESS_STATE_FAILED | Der Identifizierungsprozess ist fehlgeschlagen. | Wiederholen Sie den Prozess oder lehnen Sie ihn gemäß Ihren Geschäftsregeln ab. |
PROCESS_STATE_CREATED | Prozess erstellt. | Warten Sie. Rufen Sie das Ergebnis später über Prozess abrufen ab. |
PROCESS_STATE_CANCELED | Der Prozess wurde abgebrochen. | Erstellen Sie einen neuen Prozess, falls der Nutzer noch verifiziert werden muss. |
Prüfen Sie immer, dass data.humanToken.value nicht leer ist, bevor Sie den Wert verwenden.
Fehlercodes
Der HTTP-Status, der zurückgegeben wird, wenn der Zugriffsschlüssel im Header x-unico-accesskey fehlt oder ungültig ist, wird noch bestätigt. Siehe Authentifizierung.
- 400 Bad Request
- 403 Forbidden
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Meldung | Beschreibung |
|---|---|---|
3 | invalid flow | Wenn der angegebene Flow nicht existiert. |
3 | INVALID_IMAGE | Wenn das Bild kein gültiges Base64 ist oder wie ein Injection-Versuch aussieht. |
3 | IMAGE_TOO_LARGE | Wenn das Bild die maximale Größe von 800 KB überschreitet. |
3 | UNSUPPORTED_IMAGE_FORMAT | Wenn das Bildformat nicht PNG, JPEG oder WebP ist. |
3 | MISSING_IMAGE | Wenn das Bild für diesen Flow erforderlich ist und nicht gesendet wurde. |
3 | INVALID_REQUEST | Wenn der Request-Body null ist oder nicht interpretiert werden kann. |
9 | monthly process limit of <monthly_limit> reached for this tenant | Wenn das monatliche Nutzungslimit erreicht wurde. |
9 | PROCESS_FAILED | Wenn der Prozess während der Erstellung einen endgültigen Fehler erreicht hat. |
| Code | Meldung | Beschreibung |
|---|---|---|
7 | PERMISSION_DENIED | Wenn die Anmeldedaten gültig, aber für diese Aktion nicht berechtigt sind. |
Rate-Limit erreicht. Wenn Ihr System einen HTTP-429-Fehler erhält, müssen Sie Mechanismen implementieren, um kaskadierende Ausfälle zu verhindern und eine Verschärfung der Einschränkung zu vermeiden.
Best Practices:
- Abkühlphase (Backoff): Stoppen oder drosseln Sie nachfolgende Anfragen aus Ihrem System sofort. Wiederholen Sie fehlgeschlagene Anfragen nicht kontinuierlich in einer engen Schleife.
- Warteschlange & Drosselung: Puffern oder reihen Sie ausgehende Anfragen auf Ihrer Seite ein, um den Datenverkehr zu kontrollieren, bevor Sie sie erneut senden.
- Exponentieller Backoff mit Jitter: Erhöhen Sie beim erneuten Versuch die Wartezeit zwischen den Versuchen exponentiell (z. B. 1 s, 2 s, 4 s, 8 s) und fügen Sie eine kleine zufällige Verzögerung ("Jitter") hinzu, um einen Herdeneffekt zu vermeiden, bei dem alle in der Warteschlange befindlichen Anfragen exakt zur gleichen Millisekunde erneut versucht werden.
Das kontinuierliche Ansprechen eines rate-limitierten Endpunkts ohne Backoff kann die Einschränkungsperiode verlängern und den operativen Durchsatz Ihres Systems erheblich beeinträchtigen. Eine ordnungsgemäße Drosselung der Anfragen auf Ihrer Seite gewährleistet eine reibungslosere und widerstandsfähigere Integration.
Informationen zu Standardlimits, Erhöhung von Anfragen und weiteren Details finden Sie unter Rate Limits.
| Code | Meldung | Beschreibung |
|---|---|---|
13 | Internal failure! Try again later | Wenn ein interner Fehler auftritt. |
Die vollständige Liste der Codes dieses Endpunkts finden Sie in der Referenz Prozess erstellen der Human API.
Nächste Schritte
- Speichern Sie den Wert von
humanTokenzusammen mit Ihrem Benutzerdatensatz, um dieselbe Person bei späteren Human Token-Aufrufen wiederzuerkennen. - Um den Prozess erneut abzurufen, etwa für Audits oder den Support, verwenden Sie Prozess abrufen.