Dokumentenprozess erstellen

Dieser Endpunkt verarbeitet zwei Dokumentenabläufe, die denselben Pfad verwenden, sich aber in den Body-Parametern unterscheiden:

Neue Erfassung — übermittelt Dokumentbild(er) in base64 zur Verarbeitung (document.files erforderlich).
Wiederverwendung — überspringt die Erfassung durch Verweis auf ein zuvor erfasstes Dokument (document.documentId erforderlich).

Der aktive Ablauf wird dadurch bestimmt, ob document.documentId im Anfrage-Body angegeben ist.

Verwenden Sie vor der Erstellung eines Dokumentenprozesses Wiederverwendbare Dokumente abrufen, um zu prüfen, ob der Benutzer bereits ein Dokument zur Wiederverwendung verfügbar hat.

Den vollständigen Integrationsablauf finden Sie in der API-Übersicht.

Endpunkt

Umgebung	URL
Produktion	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

Anfrage

Header

Header	Wert
`Authorization`	`Bearer <access_token>` (siehe Authentifizierung)
`APIKEY`	Bereitgestellter API-Schlüssel mit aktivierter Dokumentenerfassung und Wiederverwendung.
`Content-Type`	`application/json`

Body-Parameter

Neue Erfassung
Wiederverwendung

Feld	Typ	Erforderlich	Beschreibung
`subject.duiType`	string	ja	Kennungstyp. Mögliche Werte: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	ja	Benutzerkennung gemäß `subject.duiType`. Ohne Punkte oder Bindestriche.
`subject.name`	string	nein	Vollständiger Name.
`subject.gender`	string	nein	`M` oder `F`.
`subject.birthDate`	string (ISO 8601)	nein	Geburtsdatum (`YYYY-MM-DD`).
`subject.email`	string	nein	E-Mail-Adresse.
`subject.phone`	string	nein	Telefonnummer im E.164-Format.
`document.purpose`	string	ja	Geschäftszweck. Werte: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	ja	ID des biometrischen Prozesses, der mit dieser Dokumentenerfassung verknüpft ist.
`document.files`	array	ja	Dokumentbilder in base64 (Vorder- und/oder Rückseite).
`document.files[].data`	string	ja	Dokumentbild in base64 (PNG, JPEG oder WebP, max. 800 KB).
`subsidiaryId`	string	nein	Zweig-ID — nur erforderlich, wenn mehrere Zweige vorhanden sind.

Feld	Typ	Erforderlich	Beschreibung
`subject.duiType`	string	ja	Kennungstyp. Mögliche Werte: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	ja	Benutzerkennung gemäß `subject.duiType`. Ohne Punkte oder Bindestriche.
`subject.name`	string	nein	Vollständiger Name.
`subject.gender`	string	nein	`M` oder `F`.
`subject.birthDate`	string (ISO 8601)	nein	Geburtsdatum (`YYYY-MM-DD`).
`subject.email`	string	nein	E-Mail-Adresse.
`subject.phone`	string	nein	Telefonnummer im E.164-Format.
`document.purpose`	string	ja	Geschäftszweck. Werte: `creditprocess`, `carpurchase`, `paybypaycheck`, `onboarding`, `fgts`.
`document.authProcessId`	string	ja	ID des biometrischen Prozesses, der mit diesem Dokument verknüpft ist.
`document.documentId`	string	ja	ID eines zuvor erfassten Dokuments (abgerufen über Wiederverwendbare Dokumente abrufen). Wenn angegeben, kann `document.files` weggelassen werden.
`subsidiaryId`	string	nein	Zweig-ID — nur erforderlich, wenn mehrere Zweige vorhanden sind.

Beispiel

Neue Erfassung — cURL
Neue Erfassung — Node.js
Wiederverwendung — cURL
Wiederverwendung — Node.js

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

Antworten

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

Feld	Typ	Beschreibung
`id`	string (UUID)	Prozesskennung.
`status`	integer	`3` (erfolgreich abgeschlossen), `5` (mit Fehler abgeschlossen).
`document.id`	string	Kennung des erfassten Dokuments. Verwenden Sie diesen Wert in zukünftigen `document.documentId`-Anfragen zur Wiederverwendung.
`document.type`	string	Identifizierter Dokumenttyp. Mögliche Werte: `unico.moja.dictionary.br.rg.v2.Rg`, `unico.moja.dictionary.br.cnh.v2.Cnh`, `unico.moja.dictionary.br.cin.v1.Cin`, `unico.moja.dictionary.br.passaporte.v1.Passaporte`.
`document.cpfMatch`	boolean	`true`, wenn die aus dem Dokument extrahierte Kennung mit `subject.code` übereinstimmt.
`document.faceMatch`	boolean	`true`, wenn das Gesicht im Dokument mit dem biometrischen Selfie aus `document.authProcessId` übereinstimmt.
`document.content`	object	Per OCR extrahierte Felder. Struktur variiert je nach Dokumenttyp.
`document.fileUrls`	array	Temporäre URLs (10-minütige Gültigkeit) zum Herunterladen der Dokumentbilder.

400 Bad Request

Der Payload ist fehlerhaft, das Bild ist ungültig oder erforderliche Felder fehlen. Siehe Fehlercodes unten.

403 Forbidden

Bearer-Token oder APIKEY fehlt, ist abgelaufen oder ungültig. Siehe Authentifizierung.

409 Conflict

Die angegebene processId existiert bereits für diesen Mandanten. Siehe Fehlercodes unten.

Fehlercodes

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Meldung	Beschreibung
`99989`	The document is invalid.	Das `document`-Objekt hat eine ungültige Struktur.
`99988`	The document is empty.	Das `document`-Objekt fehlt im Anfrage-Body.
`20900`	O base64 informado não é válido.	Der base64-Parameter ist ungültig. Mögliche Ursachen: kein Bild oder Injektionsversuch.
`20807`	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Die Auflösung des hochgeladenen Bildes ist zu niedrig.
`20509`	The subject.name field is invalid.	`subject.name` enthält ungültige Zeichen.
`20508`	The subject.gender field is invalid.	`subject.gender` muss `M` oder `F` sein.
`20507`	O parâmetro subject.code é inválido.	Nicht standardmäßiger oder nicht vorhandener Kennungswert.
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Bildgröße überschreitet 800 KB; mit JPEG92 komprimieren.
`20505`	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Das base64-Format ist ungültig oder nicht unterstützt.
`20068`	The document.documentId or document.files parameter must be present.	Weder `document.documentId` noch `document.files` wurden angegeben.
`20067`	The document.purpose parameter is invalid.	Unbekannter Wert in `document.purpose`.
`20066`	The document.authProcessId parameter is invalid.	Ungültiger Wert in `document.authProcessId`.
`20062`	The useCase field is invalid.	Unbekannter Wert im Feld `useCase`.
`20021`	The subject.phone field is invalid.	Format von `subject.phone` ist ungültig (IDD + Vorwahl + Nummer, 13 Zeichen).
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` entspricht nicht dem ISO-8601-Format (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	Der Dokumentbildparameter fehlt.
`20008`	The subject.email field is invalid.	Ungültiges E-Mail-Format in `subject.email`.
`20005`	O parâmetro subject.code não foi informado.	Der Parameter subject.code fehlt.
`20004`	O parâmetro subject não foi informado.	Der Parameter subject fehlt.
`20003`	The request body is missing or invalid.	Null oder ungültiger Payload.
`20002`	O parâmetro APIKey não foi informado.	Der APIKEY-Parameter fehlt im Anfrage-Header.
`20001`	O parâmetro authtoken não foi informado.	Der Integrationstoken-Parameter fehlt im Anfrage-Header.
`10508`	The JWT with the captured face has already been used.	Das JWT kann nur einmal verwendet werden.
`10507`	The JWT with the captured face is expired.	JWT abgelaufen; muss innerhalb von 10 Minuten gesendet werden.
`10506`	The imageBase64 field is not a valid JWT from SDK.	Das `imageBase64` ist kein gültiger JWT des SDK.

Code	Meldung	Beschreibung
`30017`	User does not have permission to perform this action.	Fehlerhafter JWT oder Benutzer ohne Berechtigung für diesen Vorgang.
`10502`	O token informado está expirado.	Der Access-Token ist abgelaufen.
`10501`	O token informado é inválido.	Das Authentifizierungstoken ist ungültig.
`10201`	O AppKey informado é inválido.	Der APIKEY ist ungültig oder existiert nicht.

Code	Meldung	Beschreibung
`20073`	The processID already exists.	Die angegebene `processId` existiert bereits für diesen Mandanten.

Code	Meldung	Beschreibung
`99999`	Internal failure! Try again later	Bei einem internen Fehler.

Nächste Schritte

Um zu prüfen, ob ein Dokument vor diesem Aufruf bereits verfügbar ist, siehe Wiederverwendbare Dokumente abrufen.
Zur Erstellung des biometrischen Prozesses (erforderlich für document.authProcessId) siehe Prozess erstellen.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Nächste Schritte​