Empresas (KYB) — Endpoints de la API de Belfort

Listar empresas

GET /v1/companies

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:read.

Página por cursor de las empresas bajo verificación KYB.

Parámetros

`claimStatus` query
`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.

Respuestas

200 Successful Response — ListEnvelope_CompanyResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`CompanyResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Dar de alta una empresa

POST /v1/companies

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:write.

Crea el expediente. Todavía no verifica nada: primero cargas miembros y documentos, después disparas el pipeline. Idempotency-Key obligatoria.

Parámetros

Idempotency-Key header

Cuerpo de la petición

application/json · schema CompanyCreate

Campo	Requerido	Tipo
`country`	no	`string`
`legalName`	sí	`string`
`rfc`	no	`string \| null`
`subjectKind`	no	`string`
`tradeName`	no	`string \| null`

Respuestas

201 Successful Response — CompanyResponse

Campo	Requerido	Tipo	Descripción
`activity`	sí	`string \| null`
`claimStatus`	sí	`string`
`country`	sí	`string`
`createdAt`	sí	`string (date-time)`
`id`	sí	`string`	Opaque company id.
`incorporationDate`	sí	`string (date) \| null`
`industryCode`	sí	`string \| null`
`legalForm`	sí	`string \| null`
`legalName`	sí	`string`
`networkCompanyId`	sí	`string \| null`
`registryAuthority`	sí	`string \| null`
`registryId`	sí	`string \| null`
`registryStatus`	sí	`string \| null`
`rfc`	sí	`string \| null`
`riskLevel`	sí	`string \| null`
`riskScore`	sí	`integer \| null`
`status`	sí	`string`
`subjectKind`	sí	`string`
`taxId`	sí	`string \| null`
`tenantId`	sí	`string`	Opaque tenant id.
`tradeName`	sí	`string \| null`
`updatedAt`	sí	`string (date-time)`
`verificationMethod`	sí	`string \| null`
`verifiedAt`	sí	`string (date-time) \| null`

Errores posibles (problem+json): 400 405 422 500

Consultar una empresa

GET /v1/companies/{company_id}

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:read.

El expediente completo: grafo de propiedad, miembros, comprobaciones, documentos y coincidencias AML.

Parámetros

company_id path · requerido string

Respuestas

200 Successful Response — CompanyDetail

Campo	Requerido	Tipo	Descripción
`activity`	sí	`string \| null`
`checks`	no	`CompanyCheckResponse[]`
`claimStatus`	sí	`string`
`country`	sí	`string`
`createdAt`	sí	`string (date-time)`
`documents`	no	`CompanyDocumentResponse[]`
`id`	sí	`string`	Opaque company id.
`incorporationDate`	sí	`string (date) \| null`
`industryCode`	sí	`string \| null`
`legalForm`	sí	`string \| null`
`legalName`	sí	`string`
`members`	no	`CompanyMemberResponse[]`
`networkCompanyId`	sí	`string \| null`
`registryAuthority`	sí	`string \| null`
`registryId`	sí	`string \| null`
`registryStatus`	sí	`string \| null`
`rfc`	sí	`string \| null`
`riskLevel`	sí	`string \| null`
`riskScore`	sí	`integer \| null`
`screeningHits`	no	`ScreeningHitResponse[]`
`status`	sí	`string`
`subjectKind`	sí	`string`
`taxId`	sí	`string \| null`
`tenantId`	sí	`string`	Opaque tenant id.
`tradeName`	sí	`string \| null`
`uboNodes`	no	`UboNodeResponse[]`
`updatedAt`	sí	`string (date-time)`
`verificationMethod`	sí	`string \| null`
`verifiedAt`	sí	`string (date-time) \| null`

Errores posibles (problem+json): 400 405 422 500

Estado de una empresa

GET /v1/companies/{company_id}/status

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:read.

La versión ligera del detalle: en qué punto está y con qué nivel de riesgo. Para pintar un semáforo sin traerte el expediente entero.

Parámetros

company_id path · requerido string

Respuestas

200 Successful Response — CompanyStatusResponse

Campo	Requerido	Tipo	Descripción
`claimStatus`	sí	`string`
`id`	sí	`string`	Opaque company id.
`riskLevel`	sí	`string \| null`
`riskScore`	sí	`integer \| null`
`status`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Añadir un miembro

POST /v1/companies/{company_id}/members

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:write.

Representante legal, administrador o cualquier persona física ligada a la empresa.

Parámetros

company_id path · requerido string

Cuerpo de la petición

application/json · schema CompanyMemberCreate

Campo	Requerido	Tipo	Descripción
`name`	sí	`string`
`personId`	no	`string \| null`	Opaque person id.
`role`	no	`string \| null`

Respuestas

201 Successful Response — CompanyMemberResponse

Campo	Requerido	Tipo	Descripción
`companyId`	sí	`string`	Opaque company id.
`createdAt`	sí	`string (date-time)`
`id`	sí	`string`	Opaque company member id.
`name`	sí	`string \| null`
`personId`	sí	`string \| null`	Opaque person id.
`role`	sí	`string \| null`
`verificationStatus`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Añadir un documento corporativo

POST /v1/companies/{company_id}/documents

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:write.

Acta constitutiva, poderes, comprobante de domicilio. Se registra la referencia al archivo y sus metadatos.

Parámetros

company_id path · requerido string

Cuerpo de la petición

application/json · schema CompanyDocumentCreate

Campo	Requerido	Tipo
`kind`	no	`string \| null`
`sha256`	no	`string \| null`
`storageKey`	no	`string \| null`

Respuestas

201 Successful Response — CompanyDocumentResponse

Campo	Requerido	Tipo	Descripción
`companyId`	sí	`string`	Opaque company id.
`createdAt`	sí	`string (date-time)`
`id`	sí	`string`	Opaque company document id.
`kind`	sí	`string \| null`
`sha256`	sí	`string \| null`
`status`	sí	`string`
`storageKey`	sí	`string \| null`
`uploadedByUserId`	sí	`string \| null`	Opaque user id.

Errores posibles (problem+json): 400 405 422 500

Añadir un nodo de propiedad

POST /v1/companies/{company_id}/ubo

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:write.

Un nodo del grafo de beneficiarios finales. Se llama una vez por nodo; el grafo se arma con las llamadas sucesivas.

Parámetros

company_id path · requerido string

Cuerpo de la petición

application/json · schema UboNodeCreate

Campo	Requerido	Tipo	Descripción
`isControlPerson`	no	`boolean`
`name`	sí	`string`
`nodeType`	no	`string`
`ownershipPct`	no	`number \| string \| null`
`parentNodeId`	no	`string \| null`	Opaque UBO node id.
`personId`	no	`string \| null`	Opaque person id.
`role`	no	`string \| null`

Respuestas

201 Successful Response — UboNodeResponse

Campo	Requerido	Tipo	Descripción
`companyId`	sí	`string`	Opaque company id.
`createdAt`	sí	`string (date-time)`
`effectivePct`	sí	`string \| null`
`id`	sí	`string`	Opaque UBO node id.
`isControlPerson`	sí	`boolean`
`name`	sí	`string`
`nodeType`	sí	`string`
`ownershipPct`	sí	`string \| null`
`ownershipType`	sí	`string \| null`
`parentNodeId`	sí	`string \| null`	Opaque UBO node id.
`personId`	sí	`string \| null`	Opaque person id.
`relatedCompanyId`	sí	`string \| null`	Opaque company id.
`role`	sí	`string \| null`
`status`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Verificar la empresa

POST /v1/companies/{company_id}/verify

Requiere una API key secreta (belfort_{env}_sk_…) con scope kyb:write.

Dispara el pipeline completo: registro público, cadena de propiedad, screening AML y cálculo de riesgo.

Parámetros

company_id path · requerido string

Respuestas

200 Successful Response — CompanyVerifyResponse

Campo	Requerido	Tipo	Descripción
`claimStatus`	sí	`string`
`id`	sí	`string`	Opaque company id.
`riskLevel`	sí	`string \| null`
`riskScore`	sí	`integer \| null`
`status`	sí	`string`
`verifiedAt`	sí	`string (date-time) \| null`

Errores posibles (problem+json): 400 405 422 500