Wiederverwendbare Dokumente abrufen

Verwenden Sie diesen Endpunkt, um zu prüfen, ob ein Benutzer bereits ein Dokument zur Wiederverwendung hat, bevor Sie einen neuen Dokumentenerfassungsablauf starten. Wenn ein Dokument gefunden wird, kann dessen documentId direkt an POST /processes/v1 (Dokumenttyp) übergeben werden, um den Erfassungsschritt zu überspringen.

Endpunkt

Umgebung	URL
Produktion	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token> (siehe Authentifizierung)
APIKEY	Bereitgestellter API-Schlüssel mit aktivierter Dokumentenerfassung und Wiederverwendung.

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
code	string	ja	Benutzerkennung (CPF oder CURP, ohne Formatierung).
type	string	ja	Abzufragender Dokumenttyp. Akzeptierte Werte: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

Hinweis

Die oben genannten type-Werte sind spezifisch für diesen Endpunkt. Verwechseln Sie sie nicht mit:

• subject.duiType in POST-Anfragen -- verwendet das Präfix DUI_TYPE_* und identifiziert die Person, nicht den Dokumenttyp (z. B. DUI_TYPE_BR_CPF).
• documentType in der Antwort -- verwendet den vollständigen Registry-Pfad (z. B. unico.moja.dictionary.br.cnh.v2.Cnh).

Beispiel

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Antworten

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Feld	Typ	Beschreibung
items	array	Liste der wiederverwendbaren Dokumente, die für den Benutzer gefunden wurden. Leeres Array, wenn kein wiederverwendbares Dokument für den angegebenen code und type gefunden wurde.
items[].documentType	string	Dokumenttyp-Kennung. Mögliche Werte: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	Dokumentkennung. Übergeben Sie diesen Wert in document.documentId bei POST /processes/v1, um das Dokument wiederzuverwenden.

403 Forbidden

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

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.

Verwendung der documentId zur Wiederverwendung

Sobald Sie eine documentId haben, übergeben Sie sie in der Dokument-Prozessanfrage, um die Erfassung zu überspringen:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Feld	Beschreibung
document.purpose	Geschäftszweck für diesen Dokumentprozess. Akzeptierte Werte: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. Diese Werte sind spezifisch für die Dokument-API und unterscheiden sich vom purpose-Enum des biometrischen SDK.
document.authProcessId	ID des zuvor für diesen Benutzer erstellten biometrischen Prozesses (aus POST /processes/v1).
document.documentId	Dokument-ID, die von der Antwort dieses Endpunkts erhalten wurde. Wenn angegeben, kann document.files weggelassen werden -- die Plattform ruft das zuvor erfasste Dokument automatisch ab.

Für das vollständige Schema der Dokument-Prozessanfrage siehe Dokumentprozess erstellen.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
20507	O parâmetro subject.code é inválido.	Fehlerhafter oder nicht existierender Kennungswert (CPF oder CURP).
20002	O parâmetro APIKey não foi informado.	Fehlender APIKEY-Header.
20001	O parâmetro authtoken não foi informado.	Fehlender Authentifizierungstoken-Header.

403 Forbidden

Code	Nachricht	Beschreibung
30020	The provided authorization token does not have permission to perform this action.	Token hat keine Berechtigung, auf das Dokument-Selfie zuzugreifen.
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.	Abgelaufenes Access-Token.
10501	O token informado é inválido.	Ungültiges Authentifizierungstoken.
10201	O AppKey informado é inválido.	Fehlender oder nicht existierender APIKEY.

404 Not Found

Code	Nachricht	Beschreibung
99987	Attachment not found.	Der mit dem Dokument verknüpfte Anhang wurde nicht gefunden.
50001	The process is not found.	Kein Dokument für die angegebenen Parameter gefunden.

500 Internal Server Error

Code	Nachricht	Beschreibung
99999	Internal failure! Try again later.	Serverseitiger Verarbeitungsfehler.