API de registre KYB: cerca i selecció d'empreses

Endpoints i facturació

Les cerques independents satisfactòries amb una font de dades d’empreses de pagament es cobren a $0.50 per sol·licitud, independentment del nombre de candidates. Els resultats buits, les cerques fallides i els resultats que només procedeixen d’altres fonts no es cobren. La recuperació posterior d’un perfil es factura per separat. La recuperació es ven en tres nivells de dades, cadascun amb el seu endpoint, i amb preus per país (preus per país):

Endpoint	Què obtens	Preu
`POST /v3/kyb/search/`	Empreses candidates: nom, número de registre, estat, tipus	$0.50 quan es retornen resultats de fonts de pagament
`POST /v3/kyb/select/`	Lite: el perfil de l’empresa (identificadors, estat, forma jurídica, data de constitució, adreça registrada, activitat, dades de contacte) i els administradors	Preu Lite: $2.00-$3.00 segons el país
`POST /v3/kyb/shareholders/`	Lite més els accionistes directes amb les seves franges de participació	Preu Shareholders: $5.00-$22.00 segons el país
`POST /v3/kyb/ubo/`	Shareholders més els titulars reals resolts a través de la cadena de titularitat	Preu UBO: $9.00-$96.00 segons el país

select és el nivell Lite: és el que factura un flux de treball KYB allotjat per a una comprovació de registre a nivell Lite, i manté el contracte que ha tingut sempre. Europa fa referència a l’EEE, al Regne Unit i a Suïssa. Una cerca Shareholders o UBO consulta la font de titularitat que dona servei al nivell. Quan aquesta font respon que no disposa de dades de l’empresa, la cerca també consulta les altres fonts de registre del país, de manera que una empresa que la font de titularitat no inclou se segueix oferint com a candidata en lloc d’acabar en una entrada manual. Les candidates trobades d’aquesta manera mantenen el nivell que vas sol·licitar: en recuperar-les es torna a comprovar la font de titularitat i, si l’empresa encara no hi consta, es lliura i es factura el perfil Lite, amb registry_ownership_status: "not_held".

Pagues pel nivell lliurat. Cada resposta inclou registry_tier_requested i registry_tier_delivered. Quan els registres del país no tenen dades de titularitat, o el registre no té cap registre de titularitat de l’empresa seleccionada, una sol·licitud de titularitat es lliura i es factura com el nivell més alt disponible (normalment Lite), i registry_ownership_status indica el motiu. Una sol·licitud UBO l’informe resolt de la qual no indica cap persona física com a titular real es lliura i es factura com a Shareholders.

Control de versions. Els endpoints Shareholders i UBO només existeixen a /v3/. La tarifa de cerca independent també s’aplica a /v2/kyb/search/; la recuperació del perfil es factura per separat.

Estat de la titularitat

registry_ownership_status indica què ha passat amb la part de titularitat d’una sol·licitud de Shareholders o UBO:

Valor	Significat
`not_requested`	La crida era una recuperació Lite, de manera que no es va sol·licitar cap titularitat.
`delivered`	El registre ha servit les dades de titularitat, i el nivell de `registry_tier_delivered` és el que pagues.
`not_held`	El registre de titularitat ha respost i no inclou aquesta empresa, de manera que no té cap registre de titularitat per servir: l’ha trobat una altra font de registre del país. Es lliura i es factura en canvi el perfil Lite, amb `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Les dades de titularitat no s’han servit per cap altre motiu: el registre que conserva la font no indica cap propietari, o bé el registre no ha retornat la secció de titularitat, o bé no s’ha pogut consultar. `registry_data.ownership_error` indica quin és. Es lliura i es factura en canvi el perfil Lite.
`pending`	La secció de titularitat encara no s’ha recuperat del registre. No es factura res i `registry_tier_delivered` és `null` fins que es recuperi.

not_held i unavailable es lliuren i es facturen com a Lite, però no són el mateix resultat: not_held vol dir que la font de titularitat no cobreix l’empresa, és a dir, un buit de cobertura, mentre que unavailable vol dir que les dades no s’han servit, per una interrupció o per una secció que el registre ha deixat buida. registry_data.ownership_error indica el motiu. Les seleccions que abans informaven unavailable perquè el registre de titularitat no incloïa l’empresa ara informen not_held; si fas una bifurcació segons l’estat, tracta els dos com el mateix lliurament Lite. Dos dels seus valors signifiquen coses diferents i no s’han de llegir com el mateix resultat:

`ownership_error`	Significat
`no_owners_on_record`	El registre ha respost la secció de titularitat i no indica cap propietari. L’empresa no té un registre de participacions (taula de capitalització) en aquest registre.
`ownership_section_unavailable`	El registre no ha retornat la secció de titularitat, de manera que no s’ha lliurat res per a aquesta secció. La llista no hi és, no pas que estigui buida: no diu res sobre qui és propietari de l’empresa.

Una secció que el registre no ha retornat també queda registrada de manera estructurada, a registry_data.section_errors, indexada per secció (officers, shareholders, group_structure) amb l’estat amb què ha respost el registre:

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors descriu la resposta que tens en aquell moment, no l’historial que hi ha darrere. Una secció que no s’ha retornat en la primera sol·licitud i que es serveix en una passada posterior (consulta la recuperació asíncrona més avall) perd la seva entrada, de manera que registry_ownership_status, ownership_error i section_errors sempre són coherents: una secció delivered mai no té cap entrada, i no_owners_on_record mai no va acompanyat d’una entrada per a shareholders. Una secció tampoc no es lliura mai parcialment: si el registre serveix la primera pàgina d’una llista i després falla en servir-ne una de posterior, la recuperació no es completa en aquell intent. Una recuperació pending es reintenta a la següent passada, i una sol·licitud nova rep l’error de registre no disponible. Així, una llista officers o de accionistes lliurada és sempre la llista completa que té el registre. Tracta una secció que apareix a section_errors com a dades que mai no s’han lliurat, mai com un resultat buit: una llista officers o de accionistes buida al costat d’una entrada de section_errors per a aquesta secció no diu res sobre l’empresa.

Titularitat recuperada de manera asíncrona

Alguns registres es consulten sota demanda: la primera sol·licitud d’una empresa sobre la qual mai no s’havia fet cap consulta a la font no retorna cap secció de titularitat mentre aquesta es recupera, i les dades arriben en un parell de minuts. Informar d’això com a «sense titularitat registrada» faria subestimar la titularitat d’una empresa que sí que té accionistes, de manera que la sol·licitud retorna pending. Mentre una recuperació està pending, fetch_status també és pending i l’estat de la resposta és 202 Accepted. Didit reintenta la secció pel seu compte i completa la recuperació sense cap altra crida per part teva:

quan arribin les dades de titularitat, els accionistes i els titulars reals apareixen a la comprovació desada, registry_tier_delivered passa a ser el nivell que s’ha servit, i l’ús es cobra a aquest nivell;
si la secció continua buida quan es tanca la finestra de reintents, l’estat passa a ser unavailable i la sol·licitud es lliura i es factura com a Lite.

Guarda el request_id i consulta periòdicament GET /v3/session/{request_id}/decision/ fins que registry_checks[0].company.fetch_status sigui resolved. No repeteixis la sol·licitud de recuperació mentre està pending: cada POST nou és una sol·licitud independent i facturable per separat. Utilitza POST /v3/kyb/search/ per trobar empreses candidates. La cerca no crea cap comprovació desada. El paràmetre tier de la cerca tria la cadena que cerca: consulta cerca per nivell. Les cerques al registre poden trigar uns 90 segons. Envia webhook_url quan vulguis que Didit retorni immediatament i enviï una notificació a la teva URL quan els candidats estiguin llestos. El callback de cerca no està signat de manera intencionada, de manera que no cal configurar un secret compartit per a aquesta notificació lleugera. Utilitza POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ amb el kyb_response_id retornat per recuperar el perfil al nivell que necessitis. La recuperació és facturable i desa el resultat com a Manual Check a la Business Console.

Flux típic

Cerca per nom de l’empresa, número de registre i país, al tier que vols comprar (basic és la cadena Lite per defecte; shareholders i ubo cerquen la cadena d’aquell nivell).
Si search_resolved=false, espera el callback opcional de webhook_url en lloc de fer sondeig.
Mostra els candidats retornats al teu operador o client.
Recupera el kyb_response_id corresponent al nivell que necessitis (select per a Lite, shareholders o ubo).
Desa el request_id retornat i utilitza’l per recuperar el resultat de Verificació d’empreses (KYB) desat.

Callback de la cerca

Quan el proveïdor indica a Didit que la cerca s’ha resolt, Didit envia una única POST a la teva webhook_url:

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Tracta el callback com una notificació de lliurament. Utilitza el kyb_response_id retornat amb POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ per executar la recuperació del perfil del registre, que és facturable.

Darrera modificació el 7 de novembre del 2026

​Endpoints i facturació

​Estat de la titularitat

​Titularitat recuperada de manera asíncrona

​Flux típic

​Callback de la cerca

Endpoints i facturació

Estat de la titularitat

Titularitat recuperada de manera asíncrona

Flux típic

Callback de la cerca