Integració KYB amb Didit: arquitectura i patrons

Aquesta guia complementa la guia d’inici ràpid. Cobreix l’arquitectura, totes les decisions d’integració i els patrons operatius que fan que la KYB sigui fiable en producció.

Arquitectura

Autenticació

Totes les sol·licituds requereixen la capçalera x-api-key amb la clau d’API de la teva aplicació. Consulta autenticació de l’API per a la rotació de claus, la separació d’entorns i els àmbits.

Creació de sessió

Un únic endpoint: POST /v3/session/. El tipus de flux determina si la sessió és KYC o KYB, de manera que no cal cap marca explícita de «business». Camps recomanats en la creació:

Camp	Finalitat
`workflow_id`	Obligatori: fa referència al teu flux de KYB.
`vendor_data`	El teu identificador de l’empresa. Vincula la sessió a una entitat d’empresa.
`callback_url`	Opcional: on redirigir l’usuari en acabar.
`expected_details`	Opcional: `{ company_name, registry_country, registration_number }`. Precompleta la cerca al registre mercantil: el país de constitució es preselecciona i es bloqueja (`registry_country` com `XX`, o `XX-YY` per a registres a nivell d’estat, p. ex. `US-CA`), els camps de nom d’empresa i número de registre s’omplen prèviament, i la cerca amb aquestes dades s’executa automàticament, combinant els dos identificadors quan tots dos hi són presents. Només és un precompletat: les discrepàncies no generen advertències.
`metadata`	Opcional: JSON adjunt a la sessió.

Esquema complet: crear sessió.

Enviament de l’enllaç allotjat

La url de la resposta és un enllaç de verificació allotjat. Opcions per enviar-lo:

Enviar-lo per correu electrònic des de la teva pròpia plataforma.
Incrustar-lo a la teva interfície d’alta com a enllaç.
Obrir-lo en un webview integrat a l’app (iOS / Android / React Native).

Pots personalitzar l’experiència allotjada (logotip, color, domini, plantilles de correu electrònic) amb Marca blanca.

Polling vs webhooks

Els webhooks són el patró recomanat. Didit envia per POST els esdeveniments de finalització al teu endpoint subscrit tan bon punt acaba el processament. El polling és compatible per al desenvolupament o quan el teu endpoint de webhook no és accessible:

Fes polling a GET /v3/session/{id}/decision/ amb backoff exponencial (cada 10 s inicialment, fins a 60 s).
Atura el polling quan status sigui un de "Approved", "Declined" o "In Review".

El polling a alta freqüència pot superar els límits de freqüència. En producció, prioritza sempre els webhooks.

Gestió de webhooks

Subscriu-te als esdeveniments que t’interessen: els mateixos esdeveniments cobreixen KYC i KYB, amb session_kind: "business" dins del payload per identificar els esdeveniments de sessions d’empresa:

status.updated: l’estat de la sessió ha canviat. Filtra per session_kind === "business" per a les sessions KYB.
data.updated: un revisor ha editat les dades del registre o les persones clau a la consola, o el registre ha informat d’un canvi. No s’envia quan el sol·licitant puja un document o envia les persones clau: en aquest cas, segueix status.updated. S’aplica el mateix filtre de session_kind.
business.status.updated / business.data.updated: l’entitat d’empresa vinculada ha canviat.

Catàleg complet d’esdeveniments: webhooks de KYB. Verificació de la signatura i semàntica de reintents: referència de webhooks.

Gestió de decisions

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Consulta estats de KYB per a la màquina d’estats completa, i advertències de KYB per a les etiquetes que expliquen una decisió.

Flux de resubmissió

Quan una sessió de Verificació d’empreses (KYB) passa a Resubmitted (o una funcionalitat es marca per a reenviament), l’empresa ha de pujar dades corregides o addicionals. Pots:

Tornar a enviar la mateixa url: el flux allotjat continua des del punt on cal el reenviament.
Reemetre un enllaç invalidat de persona clau: una persona clau la sessió KYC filla de la qual s’ha eliminat o ha caducat abans que la persona l’iniciés rep una sessió nova amb Regenerar sessió KYC de persones clau.
Obrir un cas a la Business Console per fer el seguiment de l’intercanvi intern.

Executa els passos des de la teva pròpia interfície d’usuari

Els passos de documents i persones clau també es poden executar des del teu servidor amb la teva clau d’API, de manera que tu conserves la interfície d’usuari i Didit manté la verificació i la decisió. Cada crida està associada a la sessió KYB i necessita el permís write:businesses (per llegir les parts extretes també s’accepta read:businesses o read:sessions), i executa les mateixes comprovacions, facturació i avançament del pas que la pàgina allotjada.

Puja els documents corporatius mentre la sessió es troba al pas de documents KYB.
Llegeix les parts que figuren als documents, incloent-hi els accionistes i els percentatges de titularitat, i mostra-les al sol·licitant.
Crea, edita i elimina esborranys de parts. Un esborrany no es declara i no té cost.
Envia els esborranys. Didit decideix quines parts s’han de verificar, crea una sessió KYC per a cadascuna i retorna el seu kyc_session_url perquè l’enviïs o l’incrustis.
Llegeix la decisió consolidada de la sessió, igual que en el flux allotjat.

Una crida feta mentre la sessió és en un altre pas respon 409 kyb_step_mismatch amb el pas en què es troba, i una sessió finalitzada respon 409 kyb_session_not_writable.

Agregació de perfils d’empresa

Si passes vendor_data en crear la sessió, Didit agrega totes les sessions d’aquesta empresa en una única entitat d’empresa. Fes servir el mapa features de l’entitat per respondre «aquesta empresa està completament verificada ara mateix?» sense iterar sessions. Beneficis:

Els fluxos periòdics de re-KYB s’afegeixen al mateix perfil.
Les transaccions monitoritzades amb el mateix vendor_data incorporen el context de risc de l’empresa.
Els UBO i els administradors vinculats a entitats d’usuari omplen les relacions entre entitats.

Bones pràctiques

Pràctica	Motiu
Passa sempre `vendor_data`	Sense ell, la sessió queda òrfena i no es pot agregar.
Fes servir webhooks, no sondeig	Menys latència, sense pressió sobre el límit de freqüència.
Verifica les signatures dels webhooks	Evita esdeveniments suplantats.
Emmagatzema el `session_id` al teu sistema	Necessari per recuperar la decisió i generar PDFs.
Etiqueta les sessions amb `metadata`	Simplifica els informes i la depuració.
Configura un flux de treball de prova	Fes servir un flux de treball de sandbox per a les proves d’integració abans de producció.

Gestió d’errors

Escenari	Resposta
`workflow_id` no vàlid	`400 Bad Request`
Sessió duplicada amb el mateix `vendor_data`	Crea una sessió nova; és el comportament previst, ja que s’espera una reverificació.
El país de l’empresa està fora dels països permesos del flux de treball	La comprovació del registre genera l’advertència `KYB_COUNTRY_RESTRICTED`.
Caiguda del proveïdor de registres durant la cerca d’empreses	`POST /v3/kyb/search/` retorna `502` amb `code: "kyb_registry_provider_unavailable"`. No es cobra. Torna a intentar-ho o, segons `code`, ofereix la introducció manual de l’empresa. Al flux allotjat de Didit, l’empresa passa automàticament a la introducció manual en lloc d’un error que només permet reintentar. Consulta KYB Registry Search.
Límit de freqüència	`429 Too Many Requests` amb la capçalera `Retry-After`.

Referència completa de límit de freqüència.

Propers passos

Webhooks

Tots els esdeveniments i payloads de KYB.

Estats

Referència de la màquina d’estats.

Esquema de resposta

Com interpretar la decisió de KYB.

Primers passos

Funcionalitats

Perfils d'empresa

Referència

Consola

Integració KYB amb Didit: arquitectura i patrons

Arquitectura

Autenticació

Creació de sessió

Enviament de l’enllaç allotjat

Polling vs webhooks

Gestió de webhooks

Gestió de decisions

Flux de resubmissió

Executa els passos des de la teva pròpia interfície d’usuari

Agregació de perfils d’empresa

Bones pràctiques

Gestió d’errors

Propers passos

Webhooks

Estats

Esquema de resposta

​Arquitectura

​Autenticació

​Creació de sessió

​Enviament de l’enllaç allotjat

​Polling vs webhooks

​Gestió de webhooks

​Gestió de decisions

​Flux de resubmissió

​Executa els passos des de la teva pròpia interfície d’usuari

​Agregació de perfils d’empresa

​Bones pràctiques

​Gestió d’errors

​Propers passos

Webhooks

Estats

Esquema de resposta

Arquitectura

Autenticació

Creació de sessió

Enviament de l’enllaç allotjat

Polling vs webhooks

Gestió de webhooks

Gestió de decisions

Flux de resubmissió

Executa els passos des de la teva pròpia interfície d’usuari

Agregació de perfils d’empresa

Bones pràctiques

Gestió d’errors

Propers passos