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

Header

Header	Wert
`Authorization`	`Bearer <access_token>`

Pfadparameter

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

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": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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, zu der der Benutzer nach Abschluss der Journey weitergeleitet wird.
`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 gemäß Flow-Konfiguration.
`process.clientReference`	string	Optionale clientseitige Referenz für die Indizierung im Portal.
`process.useCase`	string	Mit dem Flow verknüpfte Use-Case-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 je 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	Referenzprozessinformationen — nur bei 1:1-Validierung und Intelligente-Revalidierungs-Flows vorhanden.
`process.services`	array	Signierte Umschläge, erfasste Dokumente und andere Service-Ausgaben. Siehe unten.

Werte für process.state

Wert	Bedeutung
`PROCESS_STATE_CREATED`	Prozess erstellt; der Benutzer hat die Journey noch nicht abgeschlossen.
`AWAITING_FOR_DOCUMENT`	Prozess ohne Ausweisnummer erstellt; wartet darauf, dass diese über Prozessdokument festlegen gesetzt wird. Nur vorhanden, wenn der Custom Flow ein optionales Dokument erlaubt.
`PROCESS_STATE_FINISHED`	Journey abgeschlossen. `result` und `authenticationInfo` prüfen.
`PROCESS_STATE_FAILED`	Verarbeitungsfehler.

Inkonsistenz bei der Benennung von Status

AWAITING_FOR_DOCUMENT folgt nicht der PROCESS_STATE_*-Präfixkonvention der anderen Status. Dies ist eine bekannte Benennungsinkonsistenz in der aktuellen API.

Werte für process.result

Wert	Bedeutung
`PROCESS_RESULT_OK`	Alle Fähigkeiten haben positive Ergebnisse zurückgegeben.
`PROCESS_RESULT_INVALID_IDENTITY`	Mindestens eine Fähigkeit hat ein definitiv negatives Ergebnis zurückgegeben (z. B. Liveness fehlgeschlagen, Identität nicht übereinstimmend).
`PROCESS_RESULT_ERROR`	Fehler bei der Ergebnisverarbeitung.
`PROCESS_RESULT_EXPIRED`	Der 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 zurückgegeben. Felder für im Flow nicht verwendete Fähigkeiten geben *_UNSPECIFIED zurück.

Abgekürzte Enum-Werte

Kurzschreibweisen (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 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`	Betrugsrisikoklassifizierung	`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 Betrugsrisikoklassifizierung aktiviert ist.
`serproResult.score`	Serpro-Ähnlichkeitsabgleich	`0`–`100` (Ähnlichkeit); `-1` (kein Gesicht für diese CPF hinterlegt); `-2` (Integrationsfehler).

Felder von process.services

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 die CPF auf dem Dokument mit der 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 aus einem früheren Prozess wiederverwendet wurde.
`documents[].signed_url`	string	Vorab signierte URL zum Herunterladen des Dokument-PDFs (gültig für 5 Minuten — erneut abrufen zum Verlängern).
`documents[].doc.version`	integer	OCR-Schemaversion.
`documents[].doc.code`	string	Dokumenttypcode (z. B. `CNH`, `RG`).
`documents[].doc.data`	object	Extrahierte OCR-Felder. Inhalt variiert je nach Dokumenttyp und verfügbaren Daten.

400 Bad Request

Der Pfadparameter processId 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.

Fehlercodes

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

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

Message	Beschreibung
Jwt header is an invalid JSON	Wenn das verwendete Zugriffstoken ungültige Zeichen enthält.
Jwt is expired	Wenn das verwendete Zugriffstoken abgelaufen ist.

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

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

Polling vs. Webhook

Sie können diesen Endpunkt abfragen, um den Fortschritt zu überprü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 Beweismittel-Prüfungspaket, siehe Beweismittelset abrufen.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Polling vs. Webhook​

Nächste Schritte​