--- title: Prozess erstellen description: POST /v1/processes – die gemeinsamen Felder, die Validierungslimits, die Flow-Felder und die 201-Antwort mit dem Human Token und der Intelligence. canonical: https://developer.unico.io/de/human-plugin/api-reference/create-process locale: de generated_by: markdown-export --- # Prozess erstellen Starten Sie einen Prozess und erhalten Sie den Human Token und die Intelligence der Person. `POST /v1/processes` Startet einen Prozess mit einem der [Flows](#flows) und antwortet mit `id`, `state` und dem Ergebnis in `data`: dem Human Token und der [Intelligence](/de/human-plugin/get-started/intelligence) der Person, `data.ndocs`. ## Vor dem Aufruf - Human Plugin läuft und `GET /health/ready` antwortet mit `200`. - Ihr Access Key ist für den von Ihnen verwendeten [Flow](#flows) aktiviert. - Wenn Sie ein Dokument senden, steht dessen `type` im [Attributkatalog](/de/human-plugin/additional-resources/attribute-catalog). ## Flows Das Feld `flow` legt fest, was der Prozess tut. Human Plugin führt diese Flows in zwei Integrationsmodellen aus: - **API Only**: Ihr Back-end sendet das Selfie in `imageBase64`, und das Create antwortet mit dem Ergebnis. - **Human Token Journey**: Die Person nimmt das Selfie in der Capture Journey auf und kehrt zu Ihrer `callbackUri` zurück. Das Create antwortet mit einem `token` und einem `link`, und Sie lesen das Ergebnis mit [Prozess abrufen](/de/human-plugin/api-reference/get-process). | Flow | Description | Possible result | Integration components required | | --- | --- | --- | --- | | `api+humantoken` | Empfängt ein Selfie über Ihr Back-end und erzeugt den Human Token, einen eindeutigen Gesichtsbezeichner. Die Antwort ist endgültig: keine Erfassung, kein zweiter Aufruf. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API | | `humantoken` | Erfasst ein Selfie in der Capture Journey mit einer Lebenderkennung und erzeugt den Human Token. Das Create liefert den `token` und den `link`; lesen Sie das Ergebnis, wenn die Erfassung endet. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web | | `humantoken+revalidation` | Erfasst ein Selfie und vergleicht das Gesicht mit dem erwarteten Human Token. Liefert, ob es sich um dieselbe Person handelt oder nicht, zum Beispiel vor einer sensiblen Aktion. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web | `clientId`, `correlationId` und `credential` sind in jedem Flow gleich. ## Request ```json { "flow": "api+humantoken", "clientId": "client-a", "correlationId": "onboarding-001", "credential": { "type": "DUI_TYPE_NG_BVN", "value": "" }, "imageBase64": "" } ``` ### Gemeinsame Felder | Feld | Erforderlich | Limit (Bytes) | Hinweise | | --- | --- | --- | --- | | `flow` | Ja | 64 | Einer der [Flows](#flows) | | `clientId` | Ja | 128 | Ihre ID für den Client. Die Intelligence zählt verschiedene Werte | | `correlationId` | Ja | 128 | Ihre Referenz für diesen Prozess. **Eindeutig**: Eine, die ein anderer Prozess bereits hat, wird unabhängig von dessen Zustand mit `409` abgelehnt | | `credential` | Ja, darf aber leer sein | | Der Schlüssel muss vorhanden sein. Siehe unten | | `credential.type` | Mit einem Dokument | | Ein Code des Attributkatalogs, exakt und unter Beachtung der Groß- und Kleinschreibung | | `credential.value` | Mit einem Dokument | 64 | Die Dokumentnummer | `flow`, `clientId` und `correlationId` müssen Strings sein, ohne Steuerzeichen und ohne führende oder nachgestellte Leerzeichen. Ungültige Werte werden abgelehnt, nie umgeschrieben. ### Das Feld `credential` - **Mit einem Dokument:** ein Objekt mit genau `type` und `value`, beide Strings, gemeinsam gesendet. - **Ohne Dokument:** `null` oder `{}`. Der Prozess zählt in der Intelligence trotzdem als Transaktion und als Client. - **Weggelassen oder ein Objekt mit leeren Strings:** wird mit `400 MISSING_CREDENTIAL_TYPE` abgelehnt. So wird ein falsch geschriebener Schlüssel erkannt, bevor etwas verarbeitet wird. - Jeder andere Schlüssel in `credential` wird abgelehnt. ### Flow-Felder Was jeder Flow zu den gemeinsamen Feldern hinzufügt: | Feld | Flow | Erforderlich | Wert | | --- | --- | --- | --- | | `imageBase64` | `api+humantoken` | Ja | Das Selfie in Base64. PNG, JPEG oder WebP, bis 800 KB | | `callbackUri` | `humantoken`, `humantoken+revalidation` | Ja | Wohin die Person zurückkehrt, wenn die Erfassung endet: eine Seite von Ihnen oder das URL-Schema Ihrer App | | `references` | `humantoken+revalidation` | Ja | Ein Element mit dem erwarteten Human Token, wie im Beispiel oben | Human Plugin speichert diese Felder nicht, und ein falsch geschriebenes optionales Feld wird möglicherweise ohne Fehler ignoriert. Verwenden Sie bei `api+humantoken` ein frontales, gut beleuchtetes Selfie mit einem einzelnen Gesicht. Ein Wert, der kein Bild ist, wird abgelehnt, und der Prozess wird als fehlgeschlagen gespeichert: siehe [Flow-Ablehnungen](#flow-refusals). Bei `humantoken+revalidation` enthält das Ergebnis `humanTokenMatch` statt `humanToken`: - `"true"`: Es ist dieselbe Person. Der Prozess zählt für diese Person, und `ndocs` beschreibt sie. - Alles andere oder eine Erfassung ohne Liveness: Es ist nicht bestätigt. Der Prozess zählt für niemanden, und es gibt kein `ndocs`. In beiden Fällen wird `PROCESS_STATE_FINISHED` geantwortet: Lesen Sie `humanTokenMatch`. Siehe [Prozess abrufen](/de/human-plugin/api-reference/get-process#finished-and-failed-processes). Einige Namen sind von Human Plugin reserviert und werden mit `400 INVALID_REQUEST` abgelehnt, etwa `clientReference`. Dasselbe gilt für eine andere Schreibweise der eigenen Felder von Human Plugin, wie `client_id`, `correlation_id` oder `Flow`: Gelesen werden nur `flow`, `clientId`, `correlationId` und `credential`, exakt so geschrieben. ### Body-Regeln - Ein JSON-Objekt, höchstens **2 MiB** (etwa ausreichend für ein Selfie in Base64). Ein größerer Body wird mit `400 REQUEST_TOO_LARGE` abgelehnt. - Nach dem JSON-Objekt darf nichts folgen. ## Response `201 Created`, mit `Location: /v1/processes/`. ```json { "id": "b063041c-7529-4e70-a2b4-c71c00f19801", "state": "PROCESS_STATE_FINISHED", "data": { "humanToken": { "value": "6d3d71…", "status": "validated" }, "ndocs": { "distinctClientsCount": 2, "transactionsCount": 3, "firstSeen": "2026-09-08", "lastSeen": "2026-11-03", "credentials": [ { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 } ] } } } ``` - `id` ist die UUID von Human Plugin. Jede akzeptierte Anfrage erzeugt eine neue. - `state` ist der lokale Status. Siehe [Lebenszyklus](/de/human-plugin/api-reference/process-lifecycle). - `humantoken` und `humantoken+revalidation` antworten mit `PROCESS_STATE_CREATED` und einem `token` sowie einem `link`. Diese werden **einmal** zurückgegeben und nie gespeichert: Bewahren Sie sie auf. Siehe [Human Token Journey](/de/human-plugin/integrations/human-token-journey) und die Capture-Anleitung für Ihre Plattform. - `data.ndocs` ist die Intelligence der Person. Sie kann fehlen: siehe [Intelligence](/de/human-plugin/get-started/intelligence). ### Das Ergebnis in `data` Ein abgeschlossener Prozess hat diese Felder in `data`. Die Journey-Flows liefern sie, wenn Sie den [Prozess nach der Erfassung lesen](/de/human-plugin/api-reference/get-process). | Feld | Wann | Wert | | --- | --- | --- | | `humanToken` | `api+humantoken`, `humantoken` | Wer die Person ist: `value` ist der Human Token, und `status` ist `validated`, wenn er erzeugt wurde | | `humanTokenMatch` | `humantoken+revalidation` | `"true"`, wenn es dieselbe Person ist wie der Human Token in `references` | | `liveness` | Flows, die eine Lebenderkennung durchführen, etwa die Journey-Flows | `value` ist `live`, wenn die Erfassung von einer lebenden Person stammt, oder `not_live`, wenn nicht; `status` ist `validated`, wenn die Prüfung gelaufen ist | | `ndocs` | Wenn es Intelligence zur Person gibt | Die [Intelligence](/de/human-plugin/get-started/intelligence) der Person | Ein Journey-Ergebnis sieht so aus: ```json { "id": "b063041c-7529-4e70-a2b4-c71c00f19801", "state": "PROCESS_STATE_FINISHED", "data": { "humanToken": { "value": "6d3d71…", "status": "validated" }, "liveness": { "value": "live", "status": "validated" }, "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] } } } ``` Prüfen Sie `liveness`, bevor Sie dem Ergebnis vertrauen: Behandeln Sie die Erfassung bei `not_live` als fehlgeschlagen und bitten Sie die Person, es erneut zu versuchen. Ein Prozess mit `not_live` zählt für die Intelligence von niemandem. ## Fehler | Status | `message` | Bedeutung | | --- | --- | --- | | 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | Kein einzelnes JSON-Objekt, ein reserviertes Feld, ein falscher Typ oder ein Body über 2 MiB | | 400 | `MISSING_`, `INVALID_` | Ein Pflichtfeld fehlt oder ist fehlerhaft, etwa `MISSING_CLIENT_ID` | | 401 | Leer (`""`) | Unico hat Ihren Access Key abgelehnt: Er fehlt, ist falsch oder nicht mehr gültig. Der Prozess wird als fehlgeschlagen gespeichert. Prüfen Sie `HUMAN_API_ACCESS_KEY` | | 409 | `CORRELATION_ID_ALREADY_USED` | Ein anderer Prozess hat die `correlationId` bereits. Es wird nichts gespeichert oder gesendet | | 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` steht nicht im Katalog. Es wird nichts gespeichert oder gesendet | | 4xx | Die `message` des Flows | Der Flow hat die Anfrage abgelehnt, zum Beispiel wegen eines ungültigen Bildes. Siehe [Flow-Ablehnungen](#flow-refusals) | | 502 | `UPSTREAM_UNAVAILABLE` | Der Prozess konnte nicht rechtzeitig bestätigt werden | | 503 | `DATABASE_UNAVAILABLE` | Die Datenbank ist ausgefallen. Es wurde nichts verarbeitet | | 500 | `INTERNAL` | Unerwarteter Fehler | ### Flow-Ablehnungen Wenn ein Flow die Anfrage ablehnt, antwortet das Create mit `4xx` und dem Grund in `message`, im üblichen [Envelope](/de/human-plugin/api-reference/errors-and-retries). Die häufigsten: | `message` | Ursache | | --- | --- | | `invalid flow` | `flow` ist kein für Ihr Konto aktivierter Flow | | `INVALID_IMAGE` (`400`) | `api+humantoken` ohne `imageBase64` | | `INVALID_REQUEST` (`400`) | `imageBase64` ist kein Bild in Base64 | | `IMAGE_TOO_LARGE` | Das Bild ist größer als 800 KB | | `UNSUPPORTED_IMAGE_FORMAT` | Das Bild ist weder PNG, JPEG noch WebP | | `PERMISSION_DENIED` (`403`) | Ihr Access Key ist für diesen Flow nicht aktiviert | Ein abgelehnter Prozess wird als fehlgeschlagen gespeichert. Korrigieren Sie die Anfrage und erstellen Sie einen neuen Prozess mit einer neuen `correlationId`. Lesen Sie [Fehler und Wiederholungen](/de/human-plugin/api-reference/errors-and-retries), bevor Sie eine Wiederholungslogik einbauen: Ein neuer Versuch braucht eine neue `correlationId`. ## Weiter [Prozess abrufen](/de/human-plugin/api-reference/get-process)