Prozess abrufen

Warnung

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

Im API-Vertrag ist die Antwort auf POST /processes/v1 bereits das Endergebnis. Dieser Endpunkt dient zur erneuten Abfrage — zum Beispiel, wenn Sie einen zuvor gespeicherten Prozess einsehen oder eine frühere Transaktion prüfen möchten. Beim API-Vertrag ist die Antwort von POST /processes/v1 bereits das Endergebnis. Dieser Endpunkt existiert für erneute Abfragen -- zum Beispiel, wenn Sie einen zuvor gespeicherten Prozess einsehen oder eine frühere Transaktion prüfen möchten.

Endpunkt

Umgebung	URL
Produktion	GET https://api.id.unico.app/processes/v1/{processId}
Sandbox	GET https://api.id.uat.unico.app/processes/v1/{processId}

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token>
APIKEY	Bereitgestellter API-Schlüssel.

Pfadparameter

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

Beispiel

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

Antworten

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Antwortfelder hängen von Ihrem APIKey ab

Das obige Beispiel zeigt alle möglichen Capability-Felder. Ihre tatsächliche Antwort enthält nur Felder für die in Ihrer APIKey-Konfiguration aktivierten Capabilities — Felder für deaktivierte Capabilities werden vollständig weggelassen. Wenden Sie sich an Ihren Unico-Projektmanager, um Capabilities zu aktivieren oder anzupassen.

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung.
status	integer	1 (in Bearbeitung), 2 (Abweichung), 3 (erfolgreich abgeschlossen), 4 (abgebrochen), 5 (Fehler).
unicoId.result	string	yes, no, inconclusive -- siehe Identitätsprüfung.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive -- siehe Betrugseinstufung nach Risiko.
idFace.result	string	FOUND, NOT_FOUND -- siehe Gesichts-Identifikator.
idFace.personId	string	Stabiler, opaker Bezeichner für das Gesicht. Nur vorhanden, wenn idFace.result = FOUND.
identityFraudsters.result	string	Veraltet. Verwenden Sie stattdessen riskLevel. Kunden mit laufenden Integrationen können es weiterhin verwenden, während sie die Migration mit dem verantwortlichen Projektteam koordinieren.
government.serpro	integer	Serpro-Ähnlichkeitswert (0--100, -1, -2). Nur in Brasilien verfügbar. Siehe Serpro-Ähnlichkeitsabgleich.
liveness	integer	1 (bestanden), 2 (nicht bestanden) -- siehe Lebenderkennung.
score	integer	Probabilistischer Risiko-Score. Vorhanden wenn unicoId.result = inconclusive und die Risiko-Score-Orchestrierung aktiv ist. Positive Werte deuten auf eine höhere Wahrscheinlichkeit hin, dass es sich um den Inhaber handelt; negative Werte deuten auf ein höheres Risiko hin. Nur in Brasilien verfügbar.

400 Bad Request

Der processId-Pfadparameter fehlt oder ist fehlerhaft. Siehe Fehlercodes unten.

403 Forbidden

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

404 Not Found

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

410 Gone

Der Prozess existiert, endete jedoch mit einem Fehler. Gibt nur id und status: 5 zurück.

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.

500 Internal Server Error

Unerwarteter Serverfehler.

Wann diesen Endpunkt verwenden

Der API-Vertrag gibt Ergebnisse synchron zurück, daher benötigen die meisten Integrationen diesen Endpunkt nicht. Verwenden Sie ihn, wenn:

• Sie nur die processId gespeichert haben und das vollständige Ergebnis später abrufen müssen (Audit, Support).
• Sie vermuten, dass die ursprüngliche Antwort beim Transport verloren ging (Netzwerkfehler, nachdem die Plattform die Verarbeitung abgeschlossen hat).
• Sie ein Back-Office-Tool erstellen, das historische Prozesse überprüft.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
20023	O parâmetro processId não foi informado.	Der processId-Parameter fehlt.
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.

404 Not Found

Code	Nachricht	Beschreibung
50001	O processo informado não foi encontrado.	Der Prozess existiert nicht in der Datenbank.

403 Forbidden

Code	Nachricht	Beschreibung
30017	User does not have permission to perform this action.	Fehlerhaftes JWT oder Benutzer ohne Berechtigung für diese Operation.
10502	O token informado está expirado.	Wenn das verwendete Access-Token abgelaufen ist.
10501	O token informado é inválido.	Das Authentifizierungstoken ist ungültig.
10201	O AppKey informado é inválido.	Der APIKEY-Parameter wurde nicht eingegeben oder existiert nicht.

410 Gone

Der Prozess existiert, endete jedoch mit einem Fehler. Gibt nur id und status: 5 zurück.

500 Internal Server Error

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