Prozess abrufenGET

Rufen Sie einen Human Token-Prozess anhand seiner Kennung ab — nachdem der Nutzer von der Human Token Journey zurückkehrt oder um ein API Only-Ergebnis erneut abzufragen.

Markdown

Endpunkt

Umgebung	URL
Produktion	GET https://humantoken.unico.app/client/v1/process/{processId}

Request

Headers

Header	Wert
x-unico-accesskey	<your_access_key> (siehe Authentifizierung)

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
processId	string (UUID)	ja	Von Prozess erstellen zurückgegebene Prozesskennung.

Beispiel

cURL

curl -X GET https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://humantoken.unico.app/client/v1/process/${processId}`,
  { headers: { 'x-unico-accesskey': process.env.UNICO_ACCESS_KEY } }
);
const result = await res.json();
// result.data.humanToken.value

Antworten

200 OK

Die Antwort hat dasselbe Format wie bei Prozess erstellen. Die Struktur von data hängt vom Flow ab, der beim Erstellen des Prozesses verwendet wurde.

Standard-Flows (api+humantoken, api+liveness+humantoken, humantoken):

{
  "id": "6ed74799-4c2f-4023-b43f-a73cf7c847b2",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": {
      "value": "3f9a1c7e5b2d4086a1e3c5f7092b4d6e8a0c2e4f6183a5c7e9b1d3f5072a4c6e",
      "status": "validated"
    }
  }
}

Revalidierungs-Flows (api+liveness+humantoken+revalidation, humantoken+revalidation):

{
  "id": "cb0472c0-6dbc-46c6-b830-2be7edc35424",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanTokenMatch": "true"
  }
}

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung.
state	string	Prozesszustand — siehe state-Werte.
data.​humanToken.​value	string	Nur Standard-Flows. Stabiler, opaker Bezeichner des Gesichts (bis zu 100 Zeichen). Dieselbe Person ergibt immer denselben Wert.
data.​humanTokenMatch	string	Nur Revalidierungs-Flows. "true", wenn das Selfie mit dem referenzierten humanToken übereinstimmt, andernfalls "false".

state-Werte

Wert	Bedeutung
PROCESS_STATE_UNSPECIFIED	Zustand nicht gesetzt.
PROCESS_STATE_CREATED	Der Prozess wurde erstellt und nimmt noch neue Sitzungen an. data ist {}.
PROCESS_STATE_FINISHED	Der Prozess ist abgeschlossen und nimmt keine neuen Sitzungen mehr an. Bei Standard-Flows ist data.humanToken vorhanden, wenn ein Human Token erzeugt wurde; bei Revalidierungs-Flows zeigt data.humanTokenMatch an, ob das Selfie mit dem referenzierten Token übereinstimmt. Andernfalls ist data {}.
PROCESS_STATE_FAILED	Der Prozess ist fehlgeschlagen. data ist {}.
PROCESS_STATE_CANCELED	Der Prozess wurde abgebrochen. data ist {}.
PROCESS_STATE_AWAITING_FOR_DOCUMENT	Der Prozess wartet auf ein Ausweisdokument. data ist {}.

Warnung

Prüfen Sie immer, dass data.humanToken.value nicht leer ist, bevor Sie den Wert verwenden.

Fehlercodes

400 Bad Request

Code	Meldung	Beschreibung
3	process id is invalid	Wenn die Prozess-ID ungültig ist.

401 Unauthorized

Zugriffsschlüssel fehlt oder ist im Header x-unico-accesskey ungültig. Siehe Authentifizierung.

404 Not Found

Code	Meldung	Beschreibung
5	error getting process: rpc error: code = NotFound desc = process not found	Wenn die Prozess-ID nicht gefunden wurde.

429 Too Many Requests

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.

Warnung

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.

500 Internal Server Error

Code	Meldung	Beschreibung
99999	Internal failure! Try again later	Wenn ein interner Fehler auftritt.

Nächste Schritte

• Zurück zu Prozess erstellen, um ein neues Selfie zu senden.
• Was der humanToken darstellt und wann er nicht generiert wird, erfahren Sie in der Human Token-Übersicht.