Saltar al contingut principal
POST
curl

Visió general

Fes servir aquest endpoint quan importis usuaris d’un altre proveïdor i ja tinguis una imatge facial de confiança de cada persona. L’usuari continua identificat per vendor_data, però aquest endpoint d’adjunció de perfil utilitza didit_internal_id perquè l’usuari de destinació quedi identificat sense ambigüitat.
Això és diferent de Pujar cara a la llista. La pujada de perfil adjunta una cara a un usuari com a prova, per detectar duplicats i fer cerques facials. La pujada a la llista afegeix una cara a una llista de bloqueig de tipus facial perquè les sessions de verificació posteriors amb coincidència puguin ser rebutjades.

Endpoint

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Flux de migració

1

Crea o troba l'usuari

Crida POST /v3/users/create/ per a un perfil nou, o GET /v3/users/{vendor_data}/ per a un perfil existent.
2

Desa didit_internal_id

La resposta de l’usuari inclou didit_internal_id. Continua fent servir vendor_data a la teva base de dades; fes servir didit_internal_id només per als endpoints d’adjunció de perfil.
3

Puja la cara

Envia una imatge base64 en brut al camp image. El backend valida la decodificació de la imatge, la mida de la imatge i la detecció de cara abans de desar-la.

Exemple

Cos de la sol·licitud

Resposta

Validació i límits

  • Màxim 5 cares pujades manualment per usuari.
  • La mida màxima de la imatge decodificada és de 2 MB.
  • La imatge ha de ser base64 vàlid i decodificar-se com a imatge.
  • La imatge ha de contenir una cara detectable. Quan sigui possible, fes servir un retall frontal i ben il·luminat de la cara.
  • La cara pujada s’indexa per a la detecció de duplicats i la cerca facial posteriors.
  • La cara pujada no s’afegeix automàticament a la llista de bloqueig.

Llistar o eliminar cares pujades

Llistar les cares del perfil:
Eliminar una cara del perfil:

Permisos

Fes servir una clau d’API de la mateixa aplicació. La clau ha de pertànyer a una aplicació autoritzada a gestionar el perfil d’usuari de destinació.

Modes de fallada

  • 400: base64 no vàlid, imatge no vàlida, cap cara detectable, imatge de més de 2 MB, o l’usuari ja té 5 cares pujades.
  • 401: credencials absents o no vàlides.
  • 403: la clau d’API és vàlida però no té permís per gestionar aquest perfil d’usuari.
  • 404: no existeix cap usuari per a aquest didit_internal_id a l’aplicació.
  • 429: límit de freqüència superat; espera el temps que indiqui Retry-After.

Relacionats

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.

Paràmetres de ruta

organization_id
string<uuid>
requerit

UUID de l'organització propietària de l'aplicació.

application_id
string<uuid>
requerit

UUID de l'aplicació propietària del perfil d'usuari.

didit_internal_id
string<uuid>
requerit

UUID d'usuari intern de Didit, retornat com a didit_internal_id per GET /v3/users/{vendor_data}/ i POST /v3/users/create/.

Cos

application/json
image
string<byte>
requerit

Imatge facial en brut en format JPG o PNG codificada en base64. No incloguis el prefix data:image/...;base64,. Mida màxima un cop descodificada: 2 MB.

comment
string
predeterminat:""

Nota opcional visible per a l'operador sobre la cara carregada.

Resposta

Cara carregada i adjuntada al perfil d'usuari.

uuid
string<uuid>
requerit

UUID del registre facial d'usuari pujat.

image_url
string<uri> | null
requerit

URL signada per a la imatge facial pujada.

comment
string | null
requerit

Comentari proporcionat quan es va carregar la cara.

uploaded_by
string | null
requerit

Correu electrònic o identificador d'actor de qui ha pujat el fitxer, quan estigui disponible.

created_at
string<date-time>
requerit

Marca de temps de la pujada.

Darrera modificació el 7 de novembre del 2026