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	Szenario-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
Node.js

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..."
  }'

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.

Fehlercodes

400 Bad Request
403 Forbidden
409 Conflict
429 Too Many Requests
500 Internal Server Error

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.

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

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.

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

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

Nächste Schritte

Zum Abfragen eines bestehenden Prozesses siehe Prozess abrufen.

Endpunkt​

Anfrage​

Beispiel​

Antworten​

Fehlercodes​

Nächste Schritte​