Saltar al contingut principal
POST
cURL

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

multipart/form-data
user_image
file
requerit

Imatge facial en viu o candidata a verificar (p. ex., una selfie). Envia una única fotografia frontal amb la cara del subjecte ben visible i ben il·luminada. Extensions permeses: tiff, jpg, jpeg, png, webp. Mida màxima de pujada: 5 MB (els fitxers més grans es rebutgen amb 400). Les imatges es comprimeixen automàticament a ~0.5 MB abans de processar-les, per la qual cosa les resolucions molt altes no milloren la precisió.

ref_image
file
requerit

Imatge facial de referència amb la qual comparar (p. ex., la foto d'un document d'identitat o una foto registrada prèviament). Els mateixos límits de format i mida que user_image.

face_match_score_decline_threshold
number<float>
predeterminat:30

Llindar de similitud (0–100) que determina el valor de status a la resposta. Una puntuació calculada igual o inferior a aquest valor estableix status com a Declined i afegeix una advertència LOW_FACE_MATCH_SIMILARITY; una puntuació estrictament superior retorna Approved. El valor per defecte 30 és permissiu —augmenta'l (p. ex., 50–60) per a una verificació més estricta. Els valors fora de 0–100 retornen 400.

Rang requerit: 0 <= x <= 100
Exemple:

50

rotate_image
boolean
predeterminat:false

Quan és true, el servei prova les imatges d'entrada en increments de 90 graus (0, 90, 180, 270) i utilitza l'orientació que ofereix la millor detecció facial — útil per a captures mòbils a les quals falta l'orientació EXIF. Afegeix latència, de manera que activa'l només si no pots garantir imatges orientades correctament.

Exemple:

false

save_api_request
boolean
predeterminat:true

Quan és true (per defecte), manté la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant GET /v3/session/{sessionId}/decision/ utilitzant el request_id retornat i anunciada a través d'un webhook status.updated. Quan és false, no s'emmagatzema res i request_id és un UUID transitori només per a la correlació de la resposta.

Exemple:

true

vendor_data
string

Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant.

Exemple:

"user-123"

metadata
object

Objecte JSON opcional emmagatzemat amb la sessió (quan save_api_request=true) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., metadata={"flow":"login"}); s'analitza com un objecte.

Exemple:

Resposta

Coincidència facial calculada. face_match.score és un nombre flotant de 0 a 100 (dos decimals); status és Approved quan la puntuació està estrictament per sobre de face_match_score_decline_threshold, altrament Declined amb una advertència explicativa. Una similitud baixa o una parella no avaluable encara retorna 200 — inspecciona face_match.status i face_match.warnings, no només el codi HTTP. Quan save_api_request=true, request_id és l'identificador de sessió persistit.

request_id
string<uuid>

ID de sessió persistida quan save_api_request=true (utilitzable amb GET /v3/session/{sessionId}/decision/); en cas contrari, un UUID de correlació transitori.

face_match
object
vendor_data
string | null

Ressò de les vendor_data que has enviat, o null.

metadata
object | null

Ressò de l'objecte metadata que has enviat, o null.

created_at
string<date-time>

Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta, p. ex. 2026-06-12T01:04:42.763237+00:00.

Darrera modificació el 7 de novembre del 2026