> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Materializar relaciones
> Crea o actualiza accionistas y entidades relacionadas a partir del enriquecimiento normalizado (Brasil y países soportados). Consulta el esquema del request.
## 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](/es/api-reference/company/create-automatic).
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:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Parámetros de ruta
UUID de la entidad raíz (persona o empresa) cuyas relaciones querés materializar.
## Cuerpo de la solicitud
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`).
Niveles de socios o relacionados a procesar. Rango permitido **0–5** (por defecto en esquema **1**).
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["br_bdc_shareholders_enrichment"],
"person": ["br_cpfcnpj_complete_person_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
```
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.
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`.
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).
```json theme={null}
"riskMatrix": { "execute": true, "riskMatrixId": null }
```
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**:
```json theme={null}
{
"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:
| Evento | Cuándo | Payload (resumen) |
| ------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity:relationship-materialize-started` | Pipeline encolado | `entityId`, `mainEntityName`, `mainEntityTaxId`, `mainEntityType`, `userId` |
| `entity:relationship-materialize-completed` | Fin correcto o parcial | `entityId`, `success`, `entitiesCreated`, `relationshipsCreated`, `enrichmentExecuted`, `enrichmentProviders`, `riskMatrixExecuted`, opcional `error` (string) |
| `entity:relationship-materialize-failed` | Fallo no controlado | `entityId`, `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
```json theme={null}
{
"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
```bash theme={null}
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
```json theme={null}
{
"runEnrichmentFirst": false,
"depth": 1,
"runInBackground": false,
"riskMatrix": {
"execute": true,
"riskMatrixId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
```
## Errores (selección)
| HTTP | Código (típico) | Significado |
| ---- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| 400 | `INVALID_ENTITY_TYPE` | La entidad no es `company` ni `person` |
| 400 | `COUNTRY_NOT_SUPPORTED` | Sin estrategia / país no soportado para este flujo |
| 400 | `NO_DEFAULT_RELATIONSHIP_ENRICHMENTS` | La estrategia del país no define proveedores de relación para este tipo de entidad |
| 404 | `ENTITY_NOT_FOUND` | `entityId` inexistente para la organización |
| 422 | `NO_NORMALIZED_ENRICHMENT` | `runEnrichmentFirst: false` sin fila normalizada |
| 422 | `INVALID_RELATIONSHIP_ENRICHMENT_CONFIG` | Configuración inválida de enriquecimientos hijos / profundidad |
| 500 | `ENRICHMENT_FAILED` | Falló el enriquecimiento con `runEnrichmentFirst: true` (detalle en el cuerpo del error) |
## Ver también
* [Analizar entidad](/en/api-reference/entities/analyze)
* [Crear persona](/es/api-reference/person/create) / [Crear empresa](/es/api-reference/company/create)
* [Creación automática (persona)](/es/api-reference/person/create-automatic) / [Creación automática (empresa)](/es/api-reference/company/create-automatic)
* [Códigos de proveedores (persona)](/es/api-reference/integrations/person-provider-codes) / [Códigos de proveedores (empresa)](/es/api-reference/integrations/company-provider-codes)
* [Formatos de identificación fiscal](/es/api-reference/entities/tax-id-formats)