Dokumentenprozess erstellen

Markdown ChatGPT Claude

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