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`	integer	ja	Dokumenttypkennung. Siehe `duiType`-Werte unten.
`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`	integer	ja	Dokumenttypkennung. Siehe `duiType`-Werte unten.
`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.

duiType-Werte

Land	Code	Beschreibung
BR	1	Brasilianische CPF
MX	2	Mexikanische CURP
US	4	US-amerikanische SSN
BR	5	Brasilianischer Reisepass
AR	6	Argentinischer Reisepass
AR	7	Argentinische DNI
NG	8	Nigerianische NIN
CL	9	Chilenische RUN
EC	10	Ecuadorianische NI
US	11	US-amerikanischer Reisepass
GT	12	Guatemaltekische CUI
UY	13	Uruguayische CI
BR	14	Brasilianische CNPJ
ZZ	15	E-Mail-Adresse
ID	16	Indonesische NIK
ZZ	17	Telefonnummer
US	18	US-amerikanischer Führerschein
NG	20	Nigerianische Bankverifizierungsnummer (BVN)
US	21	US-amerikanische Passkarte
US	22	US-amerikanischer Polycarbonat-Reisepass
US	23	US-amerikanische ID-Karte
TR	24	Türkische Identifikationsnummer (TCKN)
MX	25	Mexikanische RFC (Persona Física)
CO	26	Kolumbianische NIT
PE	27	Peruanische RUC
CA	28	Kanadische SIN
DK	29	Dänische CPR
GB	30	Britische Sozialversicherungsnummer (NINO)
PL	31	Polnische PESEL
SE	32	Schwedische Personennummer (PNR)
CH	33	Schweizer AHV/AVS-Nummer
AT	34	Österreichische Steuernummer (STNR)
FI	35	Finnische Personenkennung (HETU)
BE	36	Belgische Nationalnummer (NN)
IT	37	Italienischer Codice Fiscale (CF)
SE	38	Schwedische Koordinierungsnummer (Samordningsnummer)
NO	39	Norwegische nationale Identitätsnummer (Fødselsnummer)
PE	40	Peruanische DNI
DE	41	Deutsche Steuer-Identifikationsnummer (IdNr)
NL	42	Niederländische Bürgerservicenummer (BSN)
NG	43	Nigerianisches BVN-Token (gehasht)
NG	44	Nigerianisches NIN-Token (gehasht)
PT	45	Portugiesische Steueridentifikationsnummer (NIF)
FR	46	Französische Steuerreferenznummer (SPI)
IE	47	Irische Sozialversicherungsnummer (PPSN)
LU	48	Luxemburgische nationale Identifikationsnummer (Matricule)
AR	49	Argentinischer Führerschein (Licencia Nacional de Conducir)
ES	50	Spanische Ausländer-Identifikationsnummer (NIE)
ES	51	Spanischer Personalausweis (DNI)
CL	52	Chilenischer Reisepass
CO	53	Kolumbianischer Reisepass
PE	54	Peruanischer Reisepass
CO	55	Kolumbianischer Führerschein (Licencia de Conducción)
CO	56	Kolumbianischer Bürgerausweis (Cédula de Ciudadanía)
CL	57	Chilenischer Führerschein (Licencia de Conducir)
MX	58	Mexikanischer Führerschein (Licencia de Conducir)
—	0	Nicht angegeben
—	3	Interner Unico-Identifikator

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": 1,
      "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: 1,
      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": 1,
      "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: 1,
      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 als vollständig qualifizierter Wörterbuchname. Siehe `document.type`-Werte unten.
`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 — hier klicken für Felddetails.
`document.fileUrls`	array	Temporäre URLs (10-minütige Gültigkeit) zum Herunterladen der Dokumentbilder.

In document.content sind nur die erfolgreich extrahierten Felder enthalten; alles, was die OCR nicht lesen konnte, wird weggelassen und nicht leer zurückgegeben.

document.type-Werte

Einheitliches Schema

Alle Dokumenttypen, die das einheitliche Schema verwenden — unified_schema in der Feldreferenz — werden in document.type als unico.moja.dictionary.<country>.generic.v1.<DocumentType> zurückgegeben, wobei <country> der ISO 3166-1 alpha-2 Code in Kleinbuchstaben und <DocumentType> der identifizierte Typ ist. Zum Beispiel:

unico.moja.dictionary.ar.generic.v1.IdCard: Argentinischer Personalausweis
unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: US-Reisepass aus Polycarbonat

Spezifische Schemata

Dokumenttypen, die ihr eigenes Feldschema verwenden — aufgeführt unter specific_document_schemas in der Feldreferenz — sind in der folgenden Tabelle aufgelistet:

Land	Wert	Dokument
BR	`unico.moja.dictionary.br.rg.v2.Rg`	RG
BR	`unico.moja.dictionary.br.cnh.v2.Cnh`	CNH (Führerschein)
BR	`unico.moja.dictionary.br.cin.v1.Cin`	CIN
BR	`unico.moja.dictionary.br.passaporte.v1.Passaporte`	Reisepass
MX	`unico.moja.dictionary.mx.ine.v1.Ine`	INE-Wählerausweis
MX	`unico.moja.dictionary.mx.lpc.v1.Lpc`	Licencia para conducir (Führerschein)
MX	`unico.moja.dictionary.mx.pasaporte.v1.Pasaporte`	Reisepass
—	`unico.moja.dictionary.other.unknown.v1.Unknown`	Typ konnte nicht identifiziert werden — `document.content` ist leer

Es erfolgt keine OCR-Extraktion und es wird kein Feld zurückgegeben, wenn document.type unico.moja.dictionary.other.unknown.v1.Unknown ist.

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.

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

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​