Zum Hauptinhalt springen
Prozess abrufenGET

Rufen Sie einen vorhandenen Prozess anhand seiner Kennung ab. Gemäß dem API-Vertrag wird das Ergebnis bei der Prozesserstellung bereits synchron zurückgegeben — verwenden Sie diesen Endpunkt für erneute Abfragen, Audits und Support.

Markdown
Warnung

Bevor Sie den Prozess abrufen, prüfen Sie unsere Webhook-Konfiguration und Fallback-Strategien — hier klicken.

Endpunkt​

UmgebungURL
ProduktionGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Request​

Headers
HeaderWert
AuthorizationBearer <access_token>
Pfadparameter
ParameterTypErforderlichBeschreibung
processIdstring (UUID)jaProzesskennung, die von Prozess erstellen zurückgegeben wird.

Beispiel​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

Antworten​

200 OK
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
Prozessfelder
FeldBedeutung
idProzess-UUID; der Schlüssel zum Abfragen und Nachverfolgen des Flows.
flowArt der durchgeführten Journey (z. B. id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriCallback-URI, zu der die Client-App am Ende des Flows weitergeleitet wird.
userRedirectUrlVollständige URL der CbU-Seite, die der Nutzer öffnet, um die Journey auszuführen (enthält die id und Verhaltens-Flags).
stateLebenszyklusstatus des Prozesses (z. B. PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED).
resultEndgültiges Urteil der Auswertung. PROCESS_RESULT_*-Werte (z. B. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Nur aussagekräftig, wenn state = PROCESS_STATE_FINISHED.
createdAtZeitstempel der Prozesserstellung (UTC).
finishedAtZeitstempel des Prozessabschlusses (UTC).
personUnterobjekt mit den Daten der zu verifizierenden Person.
purposeZweck des Prozesses (z. B. personAuthentication, Personenregistrierung).
servicesListe zusätzlicher, dem Prozess zugeordneter Dienste; leer, wenn keine vorhanden sind.
authenticationInfo.​authenticationIdID des vom Flow erzeugten Identitätsauthentifizierungsereignisses.
capacitiesVerwendete Funktionen/Produkte. PROCESS_CAPACITY_*-Werte (z. B. IDCLOUDONE).
expiresAtAblaufzeitpunkt des Prozesses/Links (UTC).
tokenDem Prozess zugeordnetes Sitzungs-/Access-Token (kann leer sein).
companyDataUnterobjekt mit den Daten des Unternehmens/Mandanten, dem der Prozess gehört.
simulatedBoolean; ob es sich um einen Simulations-/Sandbox-Prozess (true) oder einen echten (false) handelt.
Person-Felder
FeldBedeutung
duiTypeTyp des eindeutigen Identifikationsdokuments. DUI_TYPE_*-Werte (z. B. BR_CPF).
duiValueDokumentwert (z. B. die CPF-Nummer).
friendlyNameAnzeigename/Spitzname der Person (Freitext, nicht validiert).
emailE-Mail-Adresse der Person; kann leer sein.
phoneTelefonnummer im E.164-Format (Landesvorwahl + Ortsvorwahl + Nummer).
notificationsListe der Benachrichtigungskanäle. Jeder Eintrag enthält notificationChannel mit NOTIFICATION_CHANNEL_*-Werten (z. B. WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3ISO-Alpha-3-Landescode der Telefonnummer (z. B. BRA); kann leer sein.
Felder der Unternehmensdaten
FeldBedeutung
branchIdKennung der Niederlassung des Mandanten; leer, wenn nicht nach Niederlassung segmentiert.
countryCodeLand des Unternehmens in ISO-Alpha-3 (z. B. BRA).
Dokumenttypen und OCR-Felder

process.services[].documents[].doc.code meldet den Dokumenttyp in einer von zwei Formen. Dokumente, die vom Dokumentmodul von Unico verarbeitet wurden, einschließlich wiederverwendeter Dokumente, enthalten einen kurzen Code in Großbuchstaben (CNH). Prozesse, die ausschließlich über die API erstellt wurden, enthalten in der Regel den vollständigen Dictionary-Typ (unico.moja.dictionary.br.cnh.v2.Cnh), können aber auch einen Kurzcode enthalten. Behandeln Sie beide Formen bei jedem Integrationsweg. Der Kurzcode enthält weder das Land noch die Schemaversion; die Version wird separat in doc.version zurückgegeben.

In der Kurzform werden Dokumenttypen, die das einheitliche Schema verwenden — unified_schema in der Feldreferenz — als der bei der Erfassung erkannte Typ in Großbuchstaben gemeldet. Die häufigsten Werte sind IDCARD, DRIVERLICENSE, PASSPORT und VOTERID, die Liste ist jedoch offen: Andere bei der Erfassung erkannte Typen werden unverändert in Großbuchstaben zurückgegeben. Behandeln Sie auch Werte außerhalb dieser Liste. US-Pässe behalten ihre Variante, anstatt in PASSPORT zusammengeführt zu werden: Auch POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT und REFUGEEPASSPORT werden zurückgegeben. Zum Beispiel werden unico.moja.dictionary.ar.generic.v1.IdCard und unico.moja.dictionary.us.generic.v1.PolycarbonatePassport als IDCARD und POLYCARBONATEPASSPORT gemeldet.

Spezifische Schemas

Dokumenttypen, die ihr eigenes Feldschema verwenden — aufgeführt unter specific_document_schemas in der Feldreferenz — werden in der Tabelle unten gezeigt. Verwenden Sie den Dictionary-Typ, um jedes Schema in dieser Datei nachzuschlagen.

Landdoc.codeDictionary-TypDokument
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH (Führerschein)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​PassaporteReisepass
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneINE-Wählerausweis
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir (Führerschein)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​PasaporteReisepass
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​UnknownTyp konnte nicht identifiziert werden oder ist ein brasilianischer bzw. mexikanischer Typ ohne eigenes Schema — doc.data ist leer

Brasilianische und mexikanische Dokumente verwenden ausschließlich die oben aufgeführten spezifischen Schemas. Ein brasilianisches oder mexikanisches Dokument eines anderen Typs — zum Beispiel eine mexikanische Aufenthaltskarte — wird als UNKNOWN gemeldet, nicht mit dem einheitlichen Schema.

PASSAPORTE und PASAPORTE sind unterschiedliche Dokumente

Der brasilianische Reisepass ist PASSAPORTE (doppeltes S) und der mexikanische PASAPORTE (einfaches S), jeweils entsprechend der Schreibweise im jeweiligen Dictionary. Dies ist kein Tippfehler — behandeln Sie die beiden Werte nicht als gleichbedeutend.

Es wird keine OCR-Extraktion durchgeführt und kein Feld in doc.data gemeldet, wenn doc.code gleich UNKNOWN ist.

BrazilKunden in Brasilien können die vollständige Prozess-Payload erhalten

Die Gesamtstruktur der Antwort bleibt gleich — das einzelne Ergebnis ist der Standard.

Integrationen in Brasilien können das vollständige Prozessobjekt unten erhalten, mit Ergebnissen pro Funktion in authenticationInfo.

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
Felder auf oberster Ebene
FeldTypBeschreibung
process.idstring (UUID)Prozesskennung.
process.flowstringBei der Erstellung übermittelte Flow-Kennung.
process.callbackUristringFür Prozessereignisse konfigurierte Callback-URL.
process.​userRedirectUrlstringURL, an die der Nutzer nach Abschluss der Journey weitergeleitet wird.
process.stateenumAktueller Prozessstatus. Siehe Werte unten.
process.resultenumVerifizierungsergebnis. Nur vorhanden, wenn state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)ISO-8601-Zeitstempel der Prozesserstellung.
process.finishedAtstring (datetime)ISO-8601-Zeitstempel des Prozessabschlusses. Nur vorhanden, wenn state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)ISO-8601-Zeitstempel des Prozessablaufs.
process.purposestringIm Flow konfigurierter Zweck des Prozesses.
process.​clientReferencestringOptionale clientseitige Referenz zur Indexierung im Portal.
process.useCasestringDem Flow zugeordnete Szenario-Kennung.
process.capacitiesarray of stringsListe der in diesem Prozess aktivierten Funktionen.
process.tokenstringSigniertes JWT für die SDK-Integration.
process.personobjectBei der Erstellung angegebene Identifikation.
process.​person.​notificationsarrayFür die Journey konfigurierte Benachrichtigungskanäle (z. B. email).
process.​authenticationInfoobjectErgebnisse pro Funktion. Siehe unten.
process.companyDataobjectUnternehmens- und Niederlassungskontext.
process.​companyData.​branchIdstringNiederlassungskennung.
process.​companyData.​countryCodestringISO-3166-1-Alpha-3-Landescode (z. B. BRA).
process.​bioTokenDataobjectReferenzprozess-Informationen — nur vorhanden bei 1:1-Validierung- und Smart-Revalidierung-Flows.
process.servicesarraySignierte Envelopes, erfasste Dokumente und andere Serviceausgaben. Siehe unten.
process.state-Werte
WertBedeutung
PROCESS_STATE_CREATEDProzess erstellt; Nutzer hat die Journey noch nicht abgeschlossen.
PROCESS_STATE_AWAITING_FOR_DOCUMENTProzess ohne Identifikationsdokument erstellt. Nur vorhanden, wenn der Custom Flow ein optionales Dokument erlaubt. Senden Sie das Dokument mit Prozessdokument festlegen.
PROCESS_STATE_FINISHEDJourney abgeschlossen. Prüfen Sie result und authenticationInfo.
PROCESS_STATE_FAILEDVerarbeitungsfehler.
process.result-Werte
WertBedeutung
PROCESS_RESULT_OKAlle Funktionen lieferten positive Ergebnisse.
PROCESS_RESULT_INVALID_IDENTITYMindestens eine Funktion lieferte ein definitives negatives Ergebnis (z. B. Lebenderkennung fehlgeschlagen, Identität nicht übereinstimmend).
PROCESS_RESULT_ERRORFehler bei der Ergebnisverarbeitung.
PROCESS_RESULT_EXPIREDProzess abgelaufen, bevor die Journey abgeschlossen wurde.
PROCESS_RESULT_UNSPECIFIEDProzess noch nicht abgeschlossen.
Funktionsergebnisse in authenticationInfo

Alle Felder werden unabhängig vom Flow immer zurückgegeben. Felder für im Flow nicht verwendete Funktionen geben *_UNSPECIFIED zurück.

Abgekürzte Enum-Werte

Kurzformwerte (z. B. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) entsprechen direkt den hier dokumentierten vollständigen Enum-Werten (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE usw.) — das Präfix wird aus Gründen der Kürze weggelassen.

FeldFunktionMögliche Werte
authenticationId—Eindeutige Kennung für diesen Authentifizierungsversuch.
livenessResultLivenessLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultIdentitätsprüfungAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultBetrugseinstufung nach RisikoTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1-ValidierungBIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultIntelligente RevalidierungSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultAltersverifizierungID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabledRisiko-ScoreSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​scoreRisiko-ScoreZahl von -100 bis +100. Vorhanden, wenn authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE und Risiko-Score aktiviert ist.
serproResult.scoreSerpro-Ähnlichkeitsabgleich0–100 (Ähnlichkeit); -1 (kein Gesicht für diese CPF hinterlegt); -2 (Integrationsfehler).
deviceMetadataGerätemetadatenObjekt mit status (found, not_found, unavailable) und den Gerätedaten. Fehlt, wenn die Fähigkeit im Ablauf nicht aktiviert ist.
process.services-Felder
Ein Element pro Modul

services enthält ein Element pro Modul, das im Prozess abgeschlossen wurde: die jeweils neueste abgeschlossene Ausführung jedes Moduls, und nur solange der Prozess PROCESS_STATE_FINISHED oder PROCESS_STATE_AWAITING_FOR_DOCUMENT ist. Prozesse, die ausschließlich über die API erstellt wurden, enthalten ihr Dokumentelement in jedem Zustand. Ein Element der Dokumentenerfassung enthält documents und consent_granted. Ein Element der elektronischen Signatur enthält envelope_id und document_ids. Die Elemente haben kein Typfeld, und ihre Reihenfolge ist nicht stabil: Identifizieren Sie jedes Element anhand seiner Schlüssel, nicht anhand seiner Position, und ignorieren Sie Elemente, die Sie nicht kennen. Die Schlüssel sind in snake_case, außer denen in doc.data, die dem Schema des Dokuments folgen (z. B. nomeCivil).

FeldTypBeschreibung
consent_grantedbooleanElement der Dokumentenerfassung. Ob der Nutzer zugestimmt hat, die Dokumente mit Ihrem Unternehmen zu teilen.
documentsarrayElement der Dokumentenerfassung. Erfasste Dokumente mit OCR-Daten und Validierungsergebnissen.
documents[].doc_idstringDokumentkennung.
documents[].​share_idstringKennung der Freigabe, die der Nutzer Ihrem Unternehmen für diesen Prozess erteilt hat.
documents[].​typifiedbooleanOb der Dokumenttyp identifiziert wurde.
documents[].​cpf_matchbooleanNur Brasilien. Ob die CPF auf dem Dokument mit der bei der Erstellung gesendeten CPF übereinstimmt. Für Unternehmen, deren Land auf Brasilien gesetzt ist, immer vorhanden; für andere Länder und für Unternehmen ohne festgelegtes Land ausgelassen.
documents[].​validate_docbooleanNur Brasilien. Ob das Dokument die Dokumentvalidierung von Unico bestanden hat. Für Unternehmen, deren Land auf Brasilien gesetzt ist, immer vorhanden (false, wenn die Validierung nicht ausgeführt wurde); für andere Länder und für Unternehmen ohne festgelegtes Land ausgelassen.
documents[].​face_matchboolean or nullOb das Selfie mit dem Foto auf dem Dokument übereinstimmt. null bedeutet, dass die Prüfung nicht ausgeführt wurde — es ist kein negatives Ergebnis.
documents[].​verifiedboolean or nullNur dann true, wenn der Dokumenttyp bekannt ist, das Dokument nicht gelöscht wurde, face_match gleich true ist und das Dokument die Qualitätsprüfungen bestanden hat. Andernfalls false, auch wenn face_match nicht ausgeführt wurde. null, wenn der Prozess das Dokumentmodul nicht durchlaufen hat.
documents[].​reused_docbooleanOb dieses Dokument aus einem vorherigen Prozess wiederverwendet wurde.
documents[].​signed_urlstringKurzlebige signierte URL zum Herunterladen des Dokumentbilds. Sie läuft ab: Speichern Sie sie nicht, verlassen Sie sich nicht auf eine feste Gültigkeitsdauer und rufen Sie diesen Endpunkt erneut auf, um eine neue zu erhalten.
documents[].​doc.​versionintegerVersion des Dictionarys des Dokumenttyps (z. B. 2 für unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringDokumenttyp, als Kurzcode (z. B. CNH) oder als vollständiger Dictionary-Typ (z. B. unico.moja.dictionary.br.cnh.v2.Cnh). Dokumente, die vom Dokumentmodul verarbeitet wurden, enthalten den Kurzcode. Behandeln Sie beide. Siehe Dokumenttypen und OCR-Felder für alle Werte und wie der Code abgeleitet wird.
documents[].​doc.​dataobjectExtrahierte OCR-Felder. Der Inhalt variiert je nach Dokumenttyp — siehe die vollständige Feldreferenz für den vollständigen Katalog. Die Feldnamen folgen dem Schema des Dokuments: Portugiesisch für brasilianische Dokumente (z. B. nomeCivil, dataNascimento), Spanisch für mexikanische Dokumente und Englisch für das einheitliche Schema.
envelope_idstring (UUID)Element der elektronischen Signatur. Kennung des signierten Envelopes.
document_idsarray of stringsElement der elektronischen Signatur. IDs der Dokumente im Envelope.
Prozesse, die ausschließlich über die API erstellt wurden

Bei einem Prozess, der ausschließlich über die API erstellt wurde, stammt das Dokumentelement aus dem API-Aufruf und nicht aus dem Dokumentmodul von Unico, und einige Werte weichen von der obigen Tabelle ab:

  • consent_granted ist immer false: Ihr Unternehmen holt die Einwilligung ein, und Unico erfasst sie nicht.
  • share_id und signed_url sind leer.
  • face_match ist immer true oder false, nie null.
  • verified ist immer null.
  • doc.version ist 0.
  • doc.code enthält in der Regel den vollständigen Dictionary-Typ (z. B. unico.moja.dictionary.br.cnh.v2.Cnh), kann aber auch einen Kurzcode enthalten.
  • doc.data ist null, wenn die OCR-Daten nicht gelesen werden konnten.

Fehlercodes​

CodeNachrichtBeschreibung
3process id is invalidWenn die Prozess-ID ungültig ist.

Polling vs. Webhook​

Sie können diesen Endpunkt abfragen, um den Fortschritt zu prüfen, aber das empfohlene Muster ist, einen Webhook zu abonnieren und diesen Endpunkt nur als Fallback aufzurufen. Siehe Webhooks und Events.

Nächste Schritte​