Altersverifizierung

Den vollständigen Integrationsablauf finden Sie unter 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

Header

Header	Wert
Authorization	Bearer <access_token> (siehe Authentifizierung)
APIKEY	Bereitgestellter API-Schlüssel — muss über aktivierte Altersverifizierungsfunktionen verfügen.
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 Altersverifizierung-Funktion); für reine Altersverifizierungsabläufe nicht erforderlich.
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-Bezeichner des Vorgangs.
subsidiaryId	string	nein	Filial-ID — nur erforderlich, wenn mehrere Filialen vorhanden sind.
imageBase64	string	ja	Verschlüsselte SDK-Ausgabe oder Base64-Bild (PNG, JPEG, WebP).

Bildanforderungen

• Mindestauflösung: 640 × 480 (HD-Standard)
• Maximale Dateigröße: 800 KB (JPEG92-Komprimierung empfohlen)
• JWT-Token vom 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 Funktionen 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)	Prozess-Bezeichner. Verwenden Sie diesen mit Prozess abrufen für erneute Abfragen.
status	integer	3 (erfolgreich abgeschlossen), 5 (Fehler). Verwenden Sie für Geschäftsentscheidungen ausschließlich status = 3. Alle möglichen Werte finden Sie unter 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

Die Nutzlast 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 für diesen Mandanten bereits. Siehe Fehlercodes unten.

429 Too Many Requests

Ratenlimit erreicht. Wiederholen Sie den Versuch nach dem im Retry-After-Antwort-Header angegebenen Intervall. Siehe Ratenlimits.

500 Internal Server Error

Unerwarteter Serverfehler.

Fehlercodes

400 Bad Request

Code	Message	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 unterhalb des Mindestschwellenwerts.
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 vorhandener Bezeichnerwert. Wird nur ausgelöst, wenn Lebenderkennung oder Identitätsprüfung im Ablauf enthalten ist — für reine Altersverifizierungsabläufe nicht erforderlich.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Nutzlast überschreitet 800 KB; komprimieren Sie auf JPEG92.
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.	Unbekannter 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 entspricht nicht dem ISO 8601-Format (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 Parameter subject.code. Wird nur ausgelöst, wenn Lebenderkennung oder Identitätsprüfung im Ablauf enthalten ist — für reine Altersverifizierungsabläufe nicht erforderlich.
20004	O parâmetro subject não foi informado.	Fehlendes subject-Objekt.
20003	The request body is missing or invalid.	Null oder fehlerhafte Nutzlast.
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 JWT, das vom SDK generiert wurde.

403 Forbidden

Code	Message	Beschreibung
30017	User does not have permission to perform this action.	Fehlerhaftes JWT oder Benutzer ohne Berechtigung zur Durchführung dieser 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 vorhandener APIKEY.

409 Conflict

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

500 Internal Server Error

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

Nächste Schritte

• Informationen zum Abfragen eines vorhandenen Prozesses finden Sie unter Prozess abrufen.