> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Amb l'API de registre KYB de Didit, cerca empreses i recupera el nivell que necessites: Lite (select), Shareholders o UBOs, amb preu per país.

## 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](https://docs.didit.me/ca/getting-started/kyb-registry-pricing.md)):

| Endpoint | Què obtens | Preu |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/ca/standalone-apis/kyb-registry-search) | Empreses candidates: nom, número de registre, estat, tipus | \$0.50 quan es retornen resultats de fonts de pagament |
| [`POST /v3/kyb/select/`](https://docs.didit.me/ca/standalone-apis/kyb-registry-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/`](https://docs.didit.me/ca/standalone-apis/kyb-registry-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/`](https://docs.didit.me/ca/standalone-apis/kyb-registry-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"`.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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:

```json theme={null}
{
  "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](https://docs.didit.me/ca/standalone-apis/kyb-registry-search.md#nivell-de-cerca).

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

1. 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).
2. Si `search_resolved=false`, espera el callback opcional de `webhook_url` en lloc de fer sondeig.
3. Mostra els candidats retornats al teu operador o client.
4. Recupera el `kyb_response_id` corresponent al nivell que necessitis (select per a Lite, shareholders o ubo).
5. 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`:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.