Altersverifizierung

Für den vollständigen Integrationsablauf siehe API-Übersicht.

Endpunkt

Umgebung	URL
Produktion	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token> (siehe Authentifizierung)
APIKEY	Bereitgestellter API-Schlüssel -- muss die Fähigkeiten zur Altersverifizierung aktiviert haben.
Content-Type	application/json

Body-Parameter

Feld	Typ	Erforderlich	Beschreibung
subject	object	ja	Container für Benutzerinformationen.
subject.code	string	bedingt	CPF (BR) oder CURP (MX), ohne Formatierung. Erforderlich, wenn der Ablauf Lebenderkennung oder Identitätsprüfung umfasst (siehe Fähigkeit Altersverifizierung); nicht erforderlich für reine Altersverifizierungs-Abläufe.
subject.name	string	nein	Vollständiger Name des Benutzers.
subject.gender	string	nein	M für männlich oder F für weiblich.
subject.birthDate	string (ISO 8601)	nein	Geburtsdatum (YYYY-MM-DD).
subject.email	string	nein	E-Mail-Adresse des Benutzers.
subject.phone	string	nein	Telefonnummer: Ländervorwahl + Vorwahl + Nummer, ohne Trennzeichen (z. B. 5519725570707).
useCase	string	nein	Anwendungsfall-Kennung der Operation.
subsidiaryId	string	nein	Filial-ID -- nur erforderlich, wenn mehrere Filialen existieren.
imageBase64	string	ja	Verschlüsselte SDK-Ausgabe oder Base64-Bild (PNG, JPEG, WebP).

Bildanforderungen

• Mindestauflösung: 640 x 480 (HD-Standard)
• Maximale Dateigröße: 800 KB (JPEG92-Komprimierung empfohlen)
• JWT-Tokens des SDK laufen nach 10 Minuten ab und können nur einmal verwendet werden

Beispiel

cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      code: '12345678909',
      name: 'Luke Skywalker',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Antworten

200 OK

Die zurückgegebenen Antwortfelder hängen davon ab, welche Fähigkeiten für Ihren APIKEY aktiviert sind.

Nur Altersverifizierung (keine Lebenderkennung, keine Identitätsprüfung):

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idAge": { "result": "yes" }
}

Altersverifizierung + Lebenderkennung + Identitätsprüfung:

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "idAge": { "result": "yes" },
  "liveness": 1
}

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung. Verwenden Sie sie mit Prozess abrufen für erneute Abfragen.
status	integer	3 (erfolgreich abgeschlossen), 5 (Fehler). Verwenden Sie nur status = 3 für Geschäftsentscheidungen. Für alle möglichen Werte siehe Prozess abrufen.
idAge.result	string	yes, no, inconclusive -- Ergebnis der Altersverifizierung. In allen Antworten vorhanden.
unicoId.result	string	yes, no, inconclusive -- nur vorhanden, wenn Identitätsprüfung aktiviert ist.
liveness	integer	1 (bestanden), 2 (nicht bestanden) -- nur vorhanden, wenn Lebenderkennung aktiviert ist.

400 Bad Request

Der Payload ist fehlerhaft, das Bild ist ungültig oder erforderliche Felder fehlen.

403 Forbidden

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

409 Conflict

Die angegebene processId existiert bereits für diesen Mandanten. Siehe Fehlercodes unten.

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.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
20900	O base64 informado não é válido.	Ungültiger base64-Parameter; mögliches Bild- oder Injektionsproblem.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Bildauflösung unter dem Mindestschwellenwert.
20509	The subject.name field is invalid.	subject.name enthält ungültige Zeichen.
20508	The subject.gender field is invalid.	subject.gender muss M oder F sein.
20507	O parâmetro subject.code é inválido.	Fehlerhafter oder nicht existierender Kennungswert. Wird nur ausgelöst, wenn Lebenderkennung oder Identitätsprüfung im Ablauf enthalten ist -- nicht erforderlich für reine Altersverifizierungs-Abläufe.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Payload überschreitet 800 KB; auf JPEG92 komprimieren.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Nicht unterstütztes Format oder ungültiges Base64-Präfix.
20062	The useCase field is invalid.	Nicht erkannter Wert im Feld useCase.
20021	The subject.phone field is invalid.	Format von subject.phone ist ungültig (IDD + Vorwahl + Nummer, 13 Zeichen).
20019	The subject.birthDate field is invalid.	subject.birthDate liegt außerhalb des ISO-8601-Formats (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Fehlender Selfie-Bildparameter.
20008	The subject.email field is invalid.	Ungültiges E-Mail-Format in subject.email.
20005	O parâmetro subject.code não foi informado.	Fehlender subject.code-Parameter. Wird nur ausgelöst, wenn Lebenderkennung oder Identitätsprüfung im Ablauf enthalten ist -- nicht erforderlich für reine Altersverifizierungs-Abläufe.
20004	O parâmetro subject não foi informado.	Fehlendes subject-Objekt.
20003	The request body is missing or invalid.	Null oder fehlerhafter Payload.
20002	O parâmetro APIKey não foi informado.	Fehlender APIKEY-Header.
20001	O parâmetro authtoken não foi informado.	Fehlender Authentifizierungstoken-Header.
10508	The JWT with the captured face has already been used.	JWT kann nur einmal verwendet werden.
10507	The JWT with the captured face is expired.	JWT überschreitet das 10-Minuten-Gültigkeitsfenster.
10506	The imageBase64 field is not a valid JWT from SDK.	Das imageBase64 ist kein gültiges vom SDK generiertes JWT.

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.
30017	Jwt header is an invalid JSON.	Das Access-Token enthält ungültige Zeichen.
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.

409 Conflict

Code	Nachricht	Beschreibung
20073	The processID already exists.	Die angegebene processId existiert bereits für diesen Mandanten.

500 Internal Server Error

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

Nächste Schritte

• Zum Abfragen eines bestehenden Prozesses siehe Prozess abrufen.