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,
  "depth": 123,
  "autoExecuteIntegrationsShareholders": {},
  "executeOnlyRootData": true,
  "runInBackground": true,
  "riskMatrix": {},
  "refreshEnrichShareholders": 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): 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

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 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
{
  "executeAllActiveEnrichments": false,
  "enrichments": {
    "company": ["br_bdc_shareholders_enrichment"],
    "person": ["br_cpfcnpj_complete_person_enrichment"]
  },
  "enrichmentGroupRefs": ["child_entities_group_slug"]
}
​
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).
"riskMatrix": { "execute": true, "riskMatrixId": null }
​
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: 
{
  "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,
    "depth": 2,
    "autoExecuteIntegrationsShareholders": {
      "executeAllActiveEnrichments": false,
      "enrichments": {
        "company": ["br_bdc_shareholders_enrichment"],
        "person": ["br_cpfcnpj_complete_person_enrichment"]
      },
      "enrichmentGroupRefs": ["child_entities_group_slug"]
    },
    "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_DEFAULT_RELATIONSHIP_ENRICHMENTSLa estrategia del país no define proveedores de relación para este tipo de entidad
404ENTITY_NOT_FOUNDentityId inexistente para la organización
422NO_NORMALIZED_ENRICHMENTrunEnrichmentFirst: false sin fila normalizada
422INVALID_RELATIONSHIP_ENRICHMENT_CONFIGConfiguración inválida de enriquecimientos hijos / profundidad
500ENRICHMENT_FAILEDFalló el enriquecimiento con runEnrichmentFirst: true (detalle en el cuerpo del error)

​
Ver también