Skip to main content
POST
Materializar relaciones

Descripción general

Materializa relaciones y entidades relacionadas para una persona o empresa existente usando la fila más reciente de normalized_enrichment. Casos típicos:
  • Brasil — empresa: crea o actualiza la cadena de accionistas (QSA) a partir de datos normalizados.
  • Brasil — persona: crea o actualiza empresas y personas relacionadas a partir de datos normalizados.
El endpoint puede volver a ejecutar enriquecimientos en el dossier raíz antes de materializar (runEnrichmentFirst): solo los proveedores que la estrategia del país exige para ese tipo de entidad a fin de refrescar socios/relaciones en el normalizado (no el listado completo del marketplace). Para ese paso siempre se piden datos frescos a los proveedores. Luego ejecuta el mismo tipo de pipeline que en la creación automática.
La entidad debe ser company o person. Otros tipos devuelven 400. El país del dossier debe tener estrategia de creación automática (hoy el flujo se usa principalmente en Brasil; en otros países puede devolverse 400 si faltan valores por defecto o la configuración de profundidad/proveedores no es válida).

Endpoint

Autenticación

Requiere una clave de API válida:

Parámetros de ruta

entityId
string
required
UUID de la entidad raíz (persona o empresa) cuyas relaciones querés materializar.

Cuerpo de la solicitud

runEnrichmentFirst
boolean
default:"false"
Si es true, la API vuelve a ejecutar en la raíz solo los enriquecimientos que la estrategia del país requiere para ese tipo de entidad a fin de poblar socios/relaciones en el normalizado (p. ej. Brasil empresa vs persona). No ejecuta todos los enriquecimientos del marketplace sobre la raíz.Si es false, debe existir ya una fila de normalized_enrichment; si no, la API responde 422 (NO_NORMALIZED_ENRICHMENT).
depth
integer
default:"1"
Niveles de socios o relacionados a procesar. Rango permitido 0–5 (por defecto en esquema 1).
autoExecuteIntegrationsShareholders
object
executeOnlyRootData
boolean
default:"false"
Con true, cada nuevo hijo se crea solo con datos del normalizado del dossier raíz (nombre + tax ID) y no se aplica el pipeline de hijos de autoExecuteIntegrationsShareholders. Aplica a empresa (QSA) y persona en Brasil. No puede combinarse con un autoExecuteIntegrationsShareholders con pipeline no vacío.
runInBackground
boolean
default:"true"
Con true (predeterminado), la API responde 202 al instante con data.status: "processing" y ejecuta en segundo plano enriquecimiento, materialización y matriz de riesgo opcional. El fin del proceso se notifica por Socket.IO (ver más abajo).Con false, el servidor espera a terminar todo el pipeline y responde 200 con contadores y flags en data.
riskMatrix
object
Opcional. Tras el pipeline, ejecuta reglas / matriz de riesgo solo sobre la entidad raíz.
  • execute (boolean, obligatorio si enviás el objeto): true para correr la matriz al finalizar la materialización.
  • riskMatrixId (UUID | null, opcional): null u omitido → usa la matriz asignada a la entidad; un UUID → ejecuta esa matriz solo en esta corrida (override; no modifica la entidad).
refreshEnrichShareholders
boolean
Con true, si una entidad hija (socio / relacionado) ya existía en tu organización (mismo tax ID), el pipeline vuelve a ejecutar los enriquecimientos configurados para esa hija en lugar de omitir el refresco.

Comportamiento asíncrono (predeterminado): HTTP 202 + Socket.IO

Con runInBackground: true, la respuesta es 202:
Usá la misma conexión Socket.IO que el dashboard. Eventos: Al recibir completed o failed, volvé a consultar entidad, relaciones y listados según tu integración (GET /entities/:id, etc.).

Respuesta síncrona (runInBackground: false): HTTP 200

Si el paso de materialización termina con advertencia de pipeline, success puede ser true y data.error traer un mensaje legible: revisá ambos.

Ejemplo: empresa BR, asíncrono + matriz de riesgo

Ejemplo: forzar una matriz concreta solo en esta ejecución

Errores (selección)

Ver también