Guia: com integrar una API de KYC en 1 dia (pas a pas tècnic)

Key takeaways (TL; DR)
 

Amb Didit pots integrar una verificació d’identitat completa en qüestió d’hores i publicar avui mateix.

Pots començar amb un flux ràpid sense codi i, quan el projecte creixi, ampliar-ho amb l’API per guanyar flexibilitat.

El pla principal de KYC és gratuït i il·limitat, cosa que et permet escalar sense afegir costos des del primer dia.

La plataforma està pensada per no trencar l’experiència d’usuari i, alhora, complir amb els requisits de compliment normatiu.

Integrar una API de KYC sovint és més complicat del que hauria de ser. Massa cops, la documentació deixa buits en punts crítics, el sandbox no es comporta com producció o els webhooks fallen sense explicació. Si això et sona, aquesta guia és per a tu.

Amb l’API de KYC de Didit passaràs de zero a una verificació d’identitat completa en poques hores. Parlem d’un flux real de verificació de document i biometria, amb Face Match 1:1 i Liveness Passiu, a més de tot el necessari per controlar en temps real l’estat de les verificacions amb webhooks signats i un sandbox que es comporta com producció. Si vols anar encara més ràpid, pots orquestrar-ho tot amb un flux de verificació No-Code i sortir a producció en minuts.

I el millor de l’API de KYC de Didit? Que és totalment gratuïta. Podràs verificar identitats de forma gratuïta i il·limitada, per començar a escalar la teva plataforma.

Aquesta guia està escrita per i per a desenvolupadors: l’objectiu és que el teu flux funcioni bé, amb sessions que s’aproven en segons i estats comprensibles. Si buscaves “com integrar una API de KYC en un dia”, ets al lloc correcte.

Què és una integració de KYC i per què és essencial per a les empreses?

Integrar una solució de KYC permet a les empreses complir amb els requisits de verificació d’identitat mitjançant un proveïdor de verificació d’identitat. Aquestes integracions automatitzen la validació d’usuaris, clau per complir amb les normatives de prevenció del blanqueig de capitals.

Habitualment, les integracions de KYC es fan via API (més flexibilitat) o amb una URL de verificació allotjada (més velocitat). L’enfocament adequat depèn de les necessitats del teu negoci.

Per què és important el KYC per a les empreses?

1. Automatitza un procés abans manual. Els equips de compliance dedicaven hores a validar dades d’onboarding; ara es pot fer de manera segura en pocs segons.
2. Compliment de la normativa de KYC. La regulació evoluciona per combatre fraus cada cop més sofisticats. Una API de KYC ajuda a garantir el compliment i que totes les verificacions estiguin al dia.
3. Millor protecció contra el frau. Una API de KYC elimina passos manuals i possibles errors humans. Una capa antifrau bloqueja identitats sintètiques, deepfakes i documents alterats o generats amb IA.
4. Optimització dels processos. En reduir el treball manual, els equips poden centrar-se en el que importa: revisar riscos en temps real i detectar patrons o indicis de frau.
5. Escalabilitat sense límits. Les revisions manuals creaven colls d’ampolla. L’onboarding automatitzat els elimina i permet l’accés en segons sense renunciar a seguretat ni precisió.
6. Estalvis significatius. Integrar KYC redueix temps, recursos i costos. Amb Didit, els estalvis poden arribar fins al 70% respecte a proveïdors legacy.

Com integrar l’API de KYC de Didit (i sortir a producció avui mateix)

La integració estàndard amb Didit es basa en un workflow allotjat per Didit, una sessió de verificació per usuari, una URL de verificació per executar el flux i webhooks signats per sincronitzar estats en temps real. El circuit mínim és: crear la sessió amb el teu workflow_id, enviar l’usuari a la url de verificació, rebre el webhook amb la decisió i, si cal, consultar el resultat per API. Gràcies a la modularitat de Didit, pots afegir capes com AML Screening, Proof of Address o Age Estimation sense reescriure la base.

Consulta la documentació completa (API Full Flow) si tens qualsevol dubte.

Abans de començar: API Key, Webhook Secret i configuració del Webhook

Accedeix a la Business Console (registre gratuït) i ves a API & Webhooks (columna de l’esquerra). Allà obtindràs la teva API Key (per autenticar-te amb la capçalera X-Api-Key) i el Webhook Secret Key (per verificar la signatura dels webhooks).

En el mateix panell, configura la Webhook URL que Didit farà servir per notificar canvis d’estat.

Desa aquests valors com a variables d’entorn (.env); han de tenir aquest format:

API_KEY=<LaTevaApiKey>
WEBHOOK_SECRET_KEY=<ElTeuWebhookSecretKey>
WEBHOOK_URL=https://latevaapp.com/api/webhooks/didit

Crea la sessió de verificació

El pas següent és cridar el servei de verificació. Aquest és un exemple: substitueix (workflow_id, callback, API_KEY) per les teves dades reals.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
X-Api-Key: {LaTevaApiKey}

{
  "workflow_id": "11111111-2222-3333-4444-555555555555",  // Substitueix-ho pel teu workflow
  "callback": "<https://example.com/verification/callback>",
  "vendor_data": "usuari-123",  // El teu identificador d'usuari
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "contact_details": {
    "email": "joan.prats@example.com",
    "email_lang": "ca",
    "phone": "+34911223344"
  }
}

La resposta inclou, entre d’altres, el session_id, l’status inicial i la url per dirigir els usuaris al flux allotjat per Didit:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "usuari-123",
  "metadata": { "user_type": "premium", "account_id": "ABC123" },
  "status": "Not Started",
  "workflow_id": "example_workflow_id",
  "callback": "<https://example.com/verification/callback>",
  "url": "<https://verify.didit.me/session/abcdef123456>"
}

Trobaràs més informació i exemples de codi a la secció Crear Sessió de la documentació tècnica.

Executa la UI de verificació (redirigeix o fes embed)

Amb la url de verificació, pots redirigir l’usuari (l’opció més simple) o incrustar el flux en un <iframe> per mantenir el teu layout. Didit orquestra la captura de document, selfie i liveness segons el teu workflow.

En acabar cada pas, la sessió avança d’estat i s’enviarà un webhook.

Resultats de la sessió de verificació

Els resultats arriben de dues maneres: Webhooks (recomanat) o consulta per API sota demanda. Amb webhooks, el teu backend rep notificacions en temps real cada cop que canvia l’estat de la sessió: elimines polling i mantens una única font de veritat.

Per garantir l’autenticitat del webhook, valida sempre la signatura enviada a la capçalera X-Signature amb el teu WEBHOOK_SECRET_KEY. A més, comprova X-Timestamp i rebutja peticions fora d’una finestra curta (p. ex., 5 minuts) per prevenir replay o frau.

A la secció de Webhooks de la documentació tens tots els detalls i més exemples.

Si en algun moment necessites reconciliar estats (p. ex., si un webhook no ha arribat), pots consultar la decisió a demanda:

GET <https://verification.didit.me/v2/session/{sessionId}/decision/>
X-Api-Key: <LaTevaApiKey>

Mapeja els estats de manera consistent al teu sistema (per exemple: Not Started → In Progress → In Review → Approved / Declined / Abandoned) i reflecteix cada transició a la UI i a les mètriques. Evitaràs ambigüitats entre producte, suport i analítica.

Més control i flexibilitat amb les APIs independents de verificació

Busques més control sobre el teu flux? Les APIs independents de Didit t’hi ajudaran. A més de l’API de KYC (ID Verification, Face Match 1:1 i Liveness Passiu), pots construir processos a mida o enfocaments molt específics, afegint només les funcionalitats que necessitis.

Què pots fer amb les APIs independents de Didit?

• ID Verification: verifica un document d’identitat i extreu-ne les dades clau.
• Face Match 1:1: compara la imatge del document amb un selfie en temps real.
• Age Estimation: estima l’edat per a un onboarding sense friccions en productes restringits per edat.
• Proof of Address: verifica el domicili a partir de documents oficials i rebuts de serveis.
• AML Screening: contrasta identitats amb llistes de vigilància, sancions, PEPs i mitjans adversos.
• Face Search 1:N: comprova un rostre en una base de dades per evitar duplicats.
• Liveness Passiu: garanteix la presència real de l’usuari durant la verificació.
• Database Validation: valida una identitat contra bases de dades nacionals i globals (1x1 i 2x2).
• Phone Verification: verifica telèfons amb codis OTP.
• Email Verification: verifica emails amb codis OTP.

Quant costa utilitzar una API de KYC?

Didit ofereix l’únic pla gratuït i il·limitat de verificació d’identitat. Això vol dir que el cost d’utilitzar l’API de KYC és zero, tant si la fas servir un cop com centenars.

Sense lletra petita, contractes ni paquets tancats. Didit és una alternativa senzilla, oberta, flexible i econòmica, amb estalvis de fins al 70% respecte a alternatives consolidades. El model es basa en funcionalitats opcionals (AML Screening, Proof of Address, Phone/Email Verification, etc.) i en l’ús d’APIs independents.

Consulta els preus de les APIs independents.