Skip to main content
POST
/
entities
/
{entityId}
/
relationships
/
materialize
Materializar relaciones
curl --request POST \
  --url http://api.gu1.ai/entities/{entityId}/relationships/materialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runEnrichmentFirst": true,
  "rootIntegrationCodesBeforeMaterialize": [
    {}
  ],
  "runAllActiveIntegrationsOnRootFirst": true,
  "forceRefresh": true,
  "depth": 123,
  "shareholderEnrichments": {},
  "relationshipChildrenFromSourceOnly": true,
  "runInBackground": true,
  "riskMatrix": {},
  "allActiveIntegrationsForChildEntities": true,
  "reEnrichExistingChildEntities": true
}
'

​
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, con runAllActiveIntegrationsOnRootFirst, rootIntegrationCodesBeforeMaterialize o los defaults de la estrategia) y luego ejecutar 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

POST http://api.gu1.ai/entities/{entityId}/relationships/materialize

​
Autenticación

Requiere una clave de API válida: 
Authorization: Bearer YOUR_API_KEY

​
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 enriquecimientos sobre la entidad raíz del dossier antes de materializar. Qué proveedores corren lo definen runAllActiveIntegrationsOnRootFirst, rootIntegrationCodesBeforeMaterialize o, si ambos están en false/omitidos, los valores por defecto de la estrategia del país para descubrir relaciones (p. ej. Brasil: accionistas en empresas; empresas y personas relacionadas en personas).Si es false, debe existir ya una fila de normalized_enrichment; si no, la API responde 422 (NO_NORMALIZED_ENRICHMENT).
​
rootIntegrationCodesBeforeMaterialize
array
Lista explícita de códigos de proveedor a ejecutar en la entidad raíz cuando runEnrichmentFirst es true. Se ignora si runAllActiveIntegrationsOnRootFirst es true. Si se omite y runAllActiveIntegrationsOnRootFirst es false, se usan los defaults de la estrategia del país.
​
runAllActiveIntegrationsOnRootFirst
boolean
default:"false"
Con true (y runEnrichmentFirst: true), ejecuta todos los enriquecimientos activos del marketplace para el tipo y país de la entidad raíz antes de materializar. Tiene prioridad sobre rootIntegrationCodesBeforeMaterialize y sobre los defaults de estrategia en ese paso previo. Mayor costo/tiempo. Exige runEnrichmentFirst.
​
forceRefresh
boolean
default:"true"
Solo aplica con runEnrichmentFirst: true: pide datos frescos a los proveedores cuando la integración lo permite, en lugar de depender de caché.
​
depth
integer
default:"1"
Niveles de socios o relacionados a procesar. Rango permitido 0–5 (por defecto en esquema 1).
​
shareholderEnrichments
object
Integraciones por tipo de hijo (empresa vs persona) al crear o enriquecer cada entidad hija, igual que en creación automática:
{
  "company": ["br_bdc_shareholders_enrichment"],
  "person": ["br_cpfcnpj_complete_person_enrichment"]
}
Claves company y person: arrays de códigos de proveedor. Opcional.
​
relationshipChildrenFromSourceOnly
boolean
default:"false"
Con true, cada nuevo hijo se crea solo con nombre e identificador del normalizado, sin el paso previo obligatorio de “datos básicos” de la estrategia. Aplica a empresa y persona (Brasil): en empresas, socios del QSA; en personas, filas de normalized.relationships y empresas en normalized.shareholders donde la persona es titular. Si enviás shareholderEnrichments no vacíos, esos proveedores se ejecutan después en lote sobre la fila creada. Con false u omitido se mantiene el flujo por defecto de creación de hijos.
​
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).
"riskMatrix": { "execute": true, "riskMatrixId": null }
​
allActiveIntegrationsForChildEntities
boolean
Con true, cada entidad hija descubierta (socio / empresa relacionada / persona relacionada) se enriquece con todas las integraciones activas del marketplace para su tipo (company vs person), en lugar de las listas explícitas de shareholderEnrichments. Con false u omitido, se usa shareholderEnrichments (y depth) como siempre.
​
reEnrichExistingChildEntities
boolean
Con true, si una entidad relacionada ya existía en tu organización, el pipeline vuelve a ejecutar los enriquecimientos configurados para esa hija en lugar de omitir el refresco. Aplica al paso de materialización de socios/relacionados.

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

Con runInBackground: true, la respuesta es 202: 
{
  "success": true,
  "data": {
    "status": "processing",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "countryCode": "BR",
    "entityType": "company"
  }
}
Usá la misma conexión Socket.IO que el dashboard. Eventos:
EventoCuándoPayload (resumen)
entity:relationship-materialize-startedPipeline encoladoentityId, mainEntityName, mainEntityTaxId, mainEntityType, userId
entity:relationship-materialize-completedFin correcto o parcialentityId, success, entitiesCreated, relationshipsCreated, enrichmentExecuted, enrichmentProviders, riskMatrixExecuted, opcional error (string)
entity:relationship-materialize-failedFallo no controladoentityId, error: { code, message, details? }, userId
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

{
  "success": true,
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "countryCode": "BR",
    "entityType": "company",
    "entitiesCreated": 3,
    "relationshipsCreated": 5,
    "enrichmentExecuted": true,
    "enrichmentProviders": ["br_bdc_shareholders_enrichment"],
    "riskMatrixExecuted": true
  }
}
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

curl -X POST "http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/relationships/materialize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runEnrichmentFirst": true,
    "forceRefresh": false,
    "depth": 2,
    "shareholderEnrichments": {
      "company": ["br_bdc_shareholders_enrichment"],
      "person": ["br_cpfcnpj_complete_person_enrichment"]
    },
    "runInBackground": true,
    "riskMatrix": { "execute": true, "riskMatrixId": null }
  }'

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

{
  "runEnrichmentFirst": false,
  "depth": 1,
  "runInBackground": false,
  "riskMatrix": {
    "execute": true,
    "riskMatrixId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}

​
Errores (selección)

HTTPCódigo (típico)Significado
400INVALID_ENTITY_TYPELa entidad no es company ni person
400COUNTRY_NOT_SUPPORTEDSin estrategia / país no soportado para este flujo
400NO_ACTIVE_ENRICHMENTSrunAllActiveIntegrationsOnRootFirst sin proveedores activos
400NO_DEFAULT_RELATIONSHIP_ENRICHMENTSEl país no define códigos por defecto; enviá rootIntegrationCodesBeforeMaterialize o activá runAllActiveIntegrationsOnRootFirst
404ENTITY_NOT_FOUNDentityId inexistente para la organización
422NO_NORMALIZED_ENRICHMENTrunEnrichmentFirst: false sin fila normalizada
422INVALID_RELATIONSHIP_ENRICHMENT_CONFIGConfiguración inválida de shareholderEnrichments / profundidad
500ENRICHMENT_FAILEDFalló el enriquecimiento con runEnrichmentFirst: true (detalle en el cuerpo del error)

​
Ver también