API de gestió v3: fluxos de treball i facturació

Autenticació

Tots els endpoints de l’API de gestió utilitzen la clau d’API de la teva aplicació. No cal incloure UUID d’organització ni d’aplicació a les URL, perquè l’aplicació s’identifica a partir de la teva clau.

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

Encara no tens una clau d’API? Registra’t de manera programàtica amb 2 crides d’API.

Fluxos de treball

Els fluxos de treball defineixen els passos de verificació que segueixen els teus usuaris (escaneig del document d’identitat, prova de vida, coincidència facial, cribratge AML, etc.). Cada flux de treball és una configuració reutilitzable que associes a les sessions.

GET

Llista tots els fluxos de treball de la teva aplicació. Retorna les funcionalitats de cada flux, els llindars i si és el flux per defecte.

POST

Crea un flux de treball nou. Defineix quines funcionalitats de verificació s’activen, estableix els llindars, configura els tipus de document acceptats i més.

GET

Obté els detalls complets d’un flux de treball concret, incloses totes les configuracions de funcionalitats i els llindars.

PATCH

Actualitza la configuració d’un flux de treball. Pots modificar qualsevol configuració de funcionalitat, llindar o document acceptat.

DELETE

Elimina un flux de treball. Les sessions que ja fan servir aquest flux no es veuen afectades.

Recomanem especialment utilitzar la Consola empresarial per crear i configurar els fluxos de treball. El constructor visual de fluxos ofereix plantilles, configuració de funcionalitats mitjançant arrossegar i deixar anar, configuració de documents, ajust de llindars i previsualització, tot sense escriure codi. Fes servir l’API només per a l’automatització o la gestió programàtica dels fluxos de treball.

Exemple ràpid: crear un flux de treball

El workflow_type determina el conjunt de funcionalitats base. Després, les funcionalitats individuals s’activen o desactiven amb les marques is_*_enabled.

curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'

Valors disponibles per a workflow_type: kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification. En els fluxos kyc, la verificació d’identitat s’inclou automàticament, de manera que no necessites una marca separada per a aquesta funcionalitat. Utilitza les marques is_*_enabled per afegir o eliminar funcionalitats opcionals com la coincidència facial, la prova de vida, l’AML, NFC, el telèfon, el correu electrònic, el comprovant de domicili, l’anàlisi de dispositiu i IP, i més. Després, utilitza el flux de treball en crear sessions:

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'

Qüestionaris

Formularis personalitzats que pots afegir als fluxos de verificació per recollir informació addicional dels usuaris.

GET

Llista tots els qüestionaris.

POST

Crea un qüestionari nou amb preguntes personalitzades, lògica de ramificació i traduccions.

GET

Obté els detalls del qüestionari, incloses totes les preguntes i l’estructura del formulari.

PATCH

Actualitza un qüestionari.

DELETE

Elimina un qüestionari.

Usuaris

Gestiona les persones verificades (usuaris) de la teva aplicació. Cada usuari s’identifica amb una cadena vendor_data que proporciones en crear les sessions.

GET

Llista tots els usuaris de la teva aplicació, inclòs el seu estat de verificació i l’historial de sessions.

GET

Obté els detalls d’un usuari a partir del teu identificador vendor_data.

PATCH

Actualitza les metadades de l’usuari.

POST

Elimina usuaris per lots. Cos: {"vendor_data_list": ["user-1", "user-2"]} o {"delete_all": true}. També purga totes les plantilles biomètriques conservades per a aquests usuaris.

Plantilles biomètriques

Plantilles biomètriques facials sense imatges que una aplicació que ha donat el seu consentiment conserva després d’eliminar sessions. Consulta Plantilles biomètriques.

GET

Llista paginada amb filtres (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to, ordering).

GET

Recompte amb els mateixos filtres.

GET

Una plantilla: l’usuari propietari, la referència d’origen, la caducitat, la instrucció i l’estat.

DELETE

Purga una plantilla. Retorna {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Purga per lots. Cos: {"template_uuids": [...]} o {"delete_all": true}, més filtres opcionals.

Operacions amb sessions

POST

Elimina sessions per lots. Requereix delete:sessions. Cos: {"session_numbers": ["1", "2", "3"]} o {"delete_all": true} (acota delete_all amb els filtres de la llista de sessions amb el prefix filter_, com filter_status), més les opcions retain_face_embeddings, face_retention_days, face_retention_deadline, deletion_instruction i instruction_id. Fins a 20 sessions coincidents retornen 200 amb un face_retention_outcome per sessió; si n’hi ha més, retornen 202 amb una tasca d’eliminació.

GET

Progrés i recomptes dels resultats d’una eliminació de sessions per lots que ha retornat 202.

GET

Llista les revisions i el registre d’activitat d’una sessió.

POST

Afegeix una nota de revisió o un canvi d’estat a una sessió.

Facturació

GET

Obtén el saldo de crèdit actual i la configuració de recàrrega automàtica.

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

Crea una sessió de pagament de Stripe per recarregar crèdits. Cada recàrrega va de $50 a $20,000 i s’afegeix pel valor nominal.

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

Llistes (llistes de bloqueig, llistes d’autorització i personalitzades)

Gestiona llistes tipificades per a bloqueig, autorització i condicions personalitzades de flux de treball. Consulta la documentació completa de l’API de llistes.

GET

Llista totes les llistes de l’aplicació (de bloqueig, d’autorització i personalitzades).

POST

Afegeix una entrada a una llista. Admet reference_session_id per extreure automàticament dades d’una sessió, i reference_object_uuid per a la traçabilitat cap a transaccions, usuaris o empreses.

DELETE

Elimina una entrada d’una llista.

POST

Puja una imatge facial a una llista de bloqueig facial (base64).

Configuració del webhook

GET

Obtén la configuració actual del webhook, inclosa la URL, la versió, la clau secreta per verificar les signatures dels webhooks, i la política de conservació de dades i de plantilles biomètriques de l’aplicació. La resposta també inclou allowed_domains, descrit a continuació, a PATCH /v3/webhook/.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}

PATCH

Actualitza la URL del webhook, la versió o renova la clau secreta. Defineix rotate_secret_key: true per generar un nou secret de webhook (l’anterior queda invalidat immediatament). També defineix la política de conservació de l’aplicació: data_retention_months i face_retention_policy (delete_with_session per defecte, o retain_until_user_deleted), juntament amb face_retention_days obligatori i finit (1-3650) quan la conservació està habilitada. Consulta Conservació de plantilles biomètriques. També registra allowed_return_hosts: fins a 20 noms d’amfitrió simples (per exemple app.example.com, sense esquema, port, camí ni comodí) als quals una verificació de Digital ID wallet API pot retornar la persona per HTTPS. Una llista nova substitueix la registrada, i el domini de marca blanca de la teva aplicació sempre està permès.També defineix allowed_domains: fins a 50 orígens web (per exemple https://app.example.com) on es pot incrustar el flux de verificació allotjat i als quals pot retornar l’usuari amb un callback de sessió. Cada entrada és un esquema, un host i un port opcional, sense camí, consulta ni comodí. Utilitza https; http només s’accepta per a localhost, 127.0.0.1 i ::1. Didit emmagatzema cada origen en minúscules i sense port per defecte, i retorna la llista a allowed_domains. Una entrada no vàlida retorna un error 400 a allowed_domains. Una llista nova substitueix la registrada, i una llista buida elimina la restricció. Mentre la llista no estigui buida, POST /v3/session/ rebutja amb un 400 qualsevol callback web que no hi sigui, i el flux allotjat no redirigeix l’usuari a un callback emmagatzemat o per defecte del flux de treball que no hi sigui. Els esquemes d’URL personalitzats (enllaços profunds d’aplicacions) i les crides API de servidor a servidor no es veuen afectats.Si envies endpoints, cada destinació del webhook que la llista no inclogui s’elimina de manera permanent, juntament amb el seu secret de signatura i tot el seu registre de lliuraments, exactament igual que DELETE /v3/webhook/destinations/{destination_uuid}/. Això no es pot desfer. Per gestionar les destinacions d’una en una, utilitza en lloc d’això els endpoints de destinació del webhook.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}

Resum complet dels endpoints de l’API

Endpoint	Mètode	Descripció
`/v3/session/`	POST	Crea una sessió de verificació
`/v3/sessions/`	GET	Llista totes les sessions
`/v3/session/{id}/decision/`	GET	Obté el resultat de verificació de la sessió
`/v3/session/{id}/update-status/`	PATCH	Aprova o rebutja una sessió
`/v3/session/{id}/delete/`	DELETE	Elimina una única sessió
`/v3/sessions/delete/`	POST	Elimina sessions per lots
`/v3/sessions/delete/{job_id}/`	GET	Estat del treball d’eliminació de sessions per lots
`/v3/sessions/{id}/reviews/`	GET, POST	Activitat i revisions de la sessió
`/v3/workflows/`	GET, POST	Llista i crea fluxos de treball
`/v3/workflows/{id}/`	GET, PATCH, DELETE	Detall, actualització i eliminació del flux de treball
`/v3/questionnaires/`	GET, POST	Llista i crea qüestionaris
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	Detall del qüestionari
`/v3/users/`	GET	Llista usuaris verificats
`/v3/users/{vendor_data}/`	GET, PATCH	Detall i actualització d’usuari
`/v3/users/delete/`	POST	Elimina usuaris per lots (també purga les seves plantilles biomètriques conservades)
`/v3/biometric-templates/`	GET	Llista les plantilles biomètriques conservades
`/v3/biometric-templates/count/`	GET	Compta les plantilles biomètriques conservades
`/v3/biometric-templates/{id}/`	GET, DELETE	Detall de la plantilla / purga
`/v3/biometric-templates/delete/`	POST	Purga massiva de plantilles
`/v3/lists/`	GET, POST	Llista totes les llistes / crea una llista
`/v3/lists/{id}/`	GET, PATCH, DELETE	Detall / actualització / eliminació de la llista
`/v3/lists/{id}/entries/`	GET, POST	Llista entrades / afegeix una entrada
`/v3/lists/{id}/entries/{eid}/`	DELETE	Elimina una entrada
`/v3/lists/{id}/entries/face-upload/`	POST	Puja una cara a la llista de bloqueig
`/v3/webhook/`	GET, PATCH	Configuració del webhook (URL, secret, versió), política de conservació i noms d’amfitrió de retorn de la cartera
`/v3/billing/balance/`	GET	Consulta el saldo de crèdit
`/v3/billing/top-up/`	POST	Recarrega crèdits

Darrera modificació el 7 de novembre del 2026

​Autenticació

​Fluxos de treball

​Exemple ràpid: crear un flux de treball

​Qüestionaris

​Usuaris

​Plantilles biomètriques

​Operacions amb sessions

​Facturació

​Llistes (llistes de bloqueig, llistes d’autorització i personalitzades)

​Configuració del webhook

​Resum complet dels endpoints de l’API

Autenticació

Fluxos de treball

Exemple ràpid: crear un flux de treball

Qüestionaris

Usuaris

Plantilles biomètriques

Operacions amb sessions

Facturació

Llistes (llistes de bloqueig, llistes d’autorització i personalitzades)

Configuració del webhook

Resum complet dels endpoints de l’API