Prozess abrufen

Warnung

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

Endpunkt

Umgebung	URL
Produktion	`GET https://api.idcloud.unico.app/client/v1/process/{processId}`
Sandbox	`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}`

Anfrage

Headers

Header	Wert
`Authorization`	`Bearer <access_token>`

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
`processId`	string (UUID)	ja	Prozesskennung, die von Prozess erstellen zurückgegeben wurde.

Beispiel

cURL
Node.js

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

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

Antworten

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "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 der obersten Ebene

Feld	Typ	Beschreibung
`process.id`	string (UUID)	Prozesskennung.
`process.flow`	string	Bei der Erstellung gesendete Flow-Kennung.
`process.callbackUri`	string	Für Prozessereignisse konfigurierte Callback-URL.
`process.userRedirectUrl`	string	URL zur Weiterleitung des Benutzers nach Abschluss der Journey.
`process.state`	enum	Aktueller Prozessstatus. Siehe Werte unten.
`process.result`	enum	Verifizierungsergebnis. Nur vorhanden, wenn `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	ISO-8601-Zeitstempel der Prozesserstellung.
`process.finishedAt`	string (datetime)	ISO-8601-Zeitstempel des Prozessabschlusses. Nur vorhanden, wenn `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	ISO-8601-Zeitstempel des Prozessablaufs.
`process.purpose`	string	Zweck des Prozesses, wie im Flow konfiguriert.
`process.clientReference`	string	Optionale clientseitige Referenz zur Indexierung im Portal.
`process.useCase`	string	Dem Flow zugeordnete Anwendungsfall-Kennung.
`process.capacities`	array of strings	Liste der in diesem Prozess aktivierten Fähigkeiten.
`process.token`	string	Signiertes JWT für die SDK-Integration.
`process.person`	object	Bei der Erstellung angegebene Identifikation.
`process.person.notifications`	array	Für die Journey konfigurierte Benachrichtigungskanäle (z. B. `email`).
`process.authenticationInfo`	object	Ergebnisse pro Fähigkeit. Siehe unten.
`process.companyData`	object	Unternehmens- und Filialkontext.
`process.companyData.branchId`	string	Filialkennung.
`process.companyData.countryCode`	string	ISO-3166-1-Alpha-2-Ländercode.
`process.bioTokenData`	object	Referenzprozess-Info -- nur in 1:1-Validierungs- und Intelligente-Revalidierungs-Abläufen vorhanden.
`process.services`	array	Signierte Umschläge, erfasste Dokumente und andere Service-Ausgaben. Siehe unten.

process.state-Werte

Wert	Bedeutung
`PROCESS_STATE_CREATED`	Prozess erstellt; Benutzer hat die Journey noch nicht abgeschlossen.
`AWAITING_FOR_DOCUMENT`	Prozess ohne Ausweisdokument erstellt; wartet darauf, dass es über Prozessdokument setzen gesetzt wird. Nur vorhanden, wenn der Custom Flow optionale Dokumente erlaubt.
`PROCESS_STATE_FINISHED`	Journey abgeschlossen. Prüfen Sie `result` und `authenticationInfo`.
`PROCESS_STATE_FAILED`	Verarbeitungsfehler.

Inkonsistenz bei der State-Benennung

AWAITING_FOR_DOCUMENT folgt nicht der PROCESS_STATE_*-Präfixkonvention, die von den anderen States verwendet wird. Dies ist eine bekannte Inkonsistenz bei der Benennung in der aktuellen API.

process.result-Werte

Wert	Bedeutung
`PROCESS_RESULT_OK`	Alle Fähigkeiten haben positive Ergebnisse zurückgegeben.
`PROCESS_RESULT_INVALID_IDENTITY`	Mindestens eine Fähigkeit hat ein eindeutig negatives Ergebnis zurückgegeben (z. B. Lebenderkennung fehlgeschlagen, Identität nicht übereinstimmend).
`PROCESS_RESULT_ERROR`	Fehler bei der Ergebnisverarbeitung.
`PROCESS_RESULT_EXPIRED`	Prozess ist abgelaufen, bevor die Journey abgeschlossen wurde.
`PROCESS_RESULT_UNSPECIFIED`	Prozess noch nicht abgeschlossen.

Fähigkeitsergebnisse in authenticationInfo

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

Abgekürzte Enum-Werte

Kurzwerte (z. B. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) entsprechen direkt den hier dokumentierten vollständigen Enum-Werten (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) -- das Präfix wird der Kürze halber weggelassen.

Feld	Fähigkeit	Mögliche Werte
`authenticationId`	--	Eindeutige Kennung für diesen Authentifizierungsversuch.
`livenessResult`	Lebenderkennung	`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED`
`authenticationResult`	Identitätsprüfung	`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED`
`identityFraudstersResult`	Betrugseinstufung nach Risiko	`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED`
`bioTokenEngineResult`	1:1-Validierung	`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED`
`smartRevalidationResult`	Intelligente Revalidierung	`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED`
`idAgeResult`	Altersverifizierung	`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED`
`scoreEngineResult.scoreEnabled`	Risiko-Score	`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED`
`scoreEngineResult.score`	Risiko-Score	Zahl von -100 bis +100. Vorhanden, wenn `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` und Risiko-Score aktiviert ist.
`serproResult.score`	Serpro-Ähnlichkeitsabgleich	`0`--`100` (Ähnlichkeit); `-1` (kein Gesicht für diesen CPF hinterlegt); `-2` (Integrationsfehler).

process.services-Felder

Gemischte Namenskonventionen in services

Das Array services verwendet camelCase für Umschlag-Ebenen-Felder (envelopeId, documentIds) und snake_case für Dokument-Ebenen-Felder (doc_id, consent_granted, face_match usw.). Dies spiegelt die tatsächliche API-Antwort wider — beide Konventionen sind absichtlich und kein Dokumentationsfehler.

Feld	Typ	Beschreibung
`envelopeId`	string (UUID)	Kennung des signierten Umschlags.
`documentIds`	array of strings	IDs der in diesem Service erfassten Dokumente.
`consent_granted`	boolean	Ob der Benutzer der Datenweitergabe zugestimmt hat.
`documents`	array	Erfasste Dokumente mit OCR-Daten und Validierungsergebnissen.
`documents[].doc_id`	string	Dokumentkennung.
`documents[].typified`	boolean	Ob der Dokumenttyp erfolgreich identifiziert wurde.
`documents[].cpf_match`	boolean	Ob der CPF auf dem Dokument mit dem angegebenen CPF übereinstimmt.
`documents[].face_match`	boolean	Ob das Selfie mit dem Foto auf dem Dokument übereinstimmt.
`documents[].validate_doc`	boolean	Ob das Dokument die Authentizitätsprüfung bestanden hat.
`documents[].reused_doc`	boolean	Ob dieses Dokument von einem früheren Prozess wiederverwendet wurde.
`documents[].signed_url`	string	Vorsignierte URL zum Herunterladen des Dokument-PDFs (5 Minuten gültig -- erneut abrufen zum Erneuern).
`documents[].doc.version`	integer	OCR-Schema-Version.
`documents[].doc.code`	string	Dokumenttyp-Code (z. B. `CNH`, `RG`).
`documents[].doc.data`	object	Extrahierte OCR-Felder. Inhalt variiert je nach Dokumenttyp und verfügbaren Daten. Die Feldnamen in `doc.data` (z. B. `nomeCivil`, `dataNascimento`) werden auf Portugiesisch zurückgegeben — das sind die tatsächlichen Werte der OCR-Engine.

400 Bad Request

Der processId-Pfadparameter fehlt oder ist fehlerhaft.

401 Unauthorized

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

404 Not Found

Die processId existiert nicht oder gehört nicht zum authentifizierten Mandanten.

429 Too Many Requests

Rate-Limit erreicht. Wenn Ihr System einen HTTP-429-Fehler empfängt, müssen Sie Mechanismen implementieren, um Kaskadenausfälle zu verhindern und eine Verschärfung der Einschränkung zu vermeiden.

Best Practices:

Abkühlphase (Backoff): Stoppen oder drosseln Sie nachfolgende Anfragen aus Ihrem System sofort. Wiederholen Sie fehlgeschlagene Anfragen nicht in einer engen Schleife.
Warteschlange & Drosselung: Puffern oder reihen Sie ausgehende Anfragen auf Ihrer Seite ein, um den Datenverkehr zu kontrollieren, bevor Sie sie erneut senden.
Exponentielles Backoff mit Jitter: Erhöhen Sie beim Wiederholen die Wartezeit zwischen den Versuchen exponentiell (z. B. 1 s, 2 s, 4 s, 8 s) und fügen Sie eine kleine zufällige Verzögerung ("Jitter") hinzu, um einen Herdeneffekt zu vermeiden, bei dem alle wartenden Anfragen exakt zur gleichen Millisekunde erneut gesendet werden.

Warnung

Das kontinuierliche Ansteuern eines rate-limitierten Endpunkts ohne Backoff kann die Einschränkungsdauer verlängern und den operativen Durchsatz Ihres Systems erheblich beeinträchtigen. Ordnungsgemäßes Drosseln der Anfragen auf Ihrer Seite gewährleistet eine reibungslosere und widerstandsfähigere Integration.

Für Standardlimits, Erhöhungsanfragen und weitere Details siehe Rate-Limits.

Fehlercodes

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

Code	Nachricht	Beschreibung
`3`	process id is invalid	Wenn die Prozess-ID ungültig ist.

Code	Nachricht	Beschreibung
—	Jwt header is an invalid JSON	Wenn das verwendete Access-Token falsche Zeichen enthält.
—	Jwt is expired	Wenn das verwendete Access-Token abgelaufen ist.

Code	Nachricht	Beschreibung
`5`	error getting process: rpc error: code = NotFound desc = process not found	Wenn die Prozess-ID nicht gefunden wurde.

Code	Nachricht	Beschreibung
`99999`	Internal failure! Try again later	Wenn ein interner Fehler auftritt.

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 Ereignisse.

Nächste Schritte

Für das erfasste Selfie siehe Selfie abrufen.
Für das Audit-Beweisbundle siehe Beweissatz abrufen.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Polling vs. Webhook​

Nächste Schritte​