> ## 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 relações
> Cria ou atualiza acionistas e entidades relacionadas a partir do enriquecimento normalizado (Brasil e países suportados) — no modelo universal de entidades gu1.
## Visão geral
Materializa **relações e entidades relacionadas** para uma **pessoa** ou **empresa** existente usando a linha mais recente de `normalized_enrichment`. Casos típicos:
* **Brasil — empresa**: cria ou atualiza a cadeia de acionistas (QSA) a partir dos dados normalizados.
* **Brasil — pessoa**: cria ou atualiza empresas e pessoas relacionadas a partir dos dados normalizados.
O endpoint pode **reexecutar enriquecimentos no dossiê raiz** antes de materializar (`runEnrichmentFirst`): apenas os provedores que a **estratégia do país** exige para aquele tipo de entidade a fim de atualizar sócios/relações no normalizado (não a lista completa do marketplace). Nesse passo sempre se pedem dados **novos** aos provedores. Em seguida executa o mesmo tipo de pipeline usado na [criação automática](/pt/api-reference/company/create-automatic).
A entidade deve ser **`company`** ou **`person`**. Outros tipos retornam **400**. O **país** do dossiê precisa ter estratégia de criação automática (hoje o fluxo é usado principalmente no **Brasil**; em outros países pode retornar **400** se faltarem padrões ou a configuração de profundidade/provedores for inválida).
## Endpoint
```
POST http://api.gu1.ai/entities/{entityId}/relationships/materialize
```
## Autenticação
Requer uma chave de API válida:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Parâmetros de rota
UUID da entidade raiz (pessoa ou empresa) cujas relações você quer materializar.
## Corpo da requisição
Se `true`, a API reexecuta na **raiz** apenas os enriquecimentos que a **estratégia do país** exige para aquele tipo de entidade a fim de preencher sócios/relações no normalizado (ex.: Brasil empresa vs pessoa). **Não** executa todos os enriquecimentos do marketplace na raiz.
Se `false`, já deve existir uma linha em **`normalized_enrichment`**; caso contrário a API retorna **422** (`NO_NORMALIZED_ENRICHMENT`).
Quantos níveis de sócios ou relacionados processar. Faixa **0–5** (padrão do esquema **1**).
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["br_bdc_shareholders_enrichment"],
"person": ["br_cpfcnpj_complete_person_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
```
Com `true`, cada **novo** filho é criado só com dados do **normalizado do dossier raiz** (nome + tax ID) e **não** roda o pipeline de filhos de `autoExecuteIntegrationsShareholders`. Vale para **empresa** (QSA) e **pessoa** no Brasil. Não pode ser combinado com um `autoExecuteIntegrationsShareholders` com pipeline não vazio.
Com **`true`** (padrão), a API responde **202** na hora com `data.status: "processing"` e executa em segundo plano enriquecimento, materialização e matriz de risco opcional. O término é sinalizado via **Socket.IO** (abaixo).
Com **`false`**, o servidor aguarda o pipeline completo e responde **200** com contadores e flags em `data`.
Opcional. Após o pipeline, executa **regras / matriz de risco** apenas na entidade **raiz**.
* **`execute`** (boolean, obrigatório se o objeto for enviado): `true` para rodar a matriz ao finalizar a materialização.
* **`riskMatrixId`** (UUID | null, opcional): **`null`** ou omitido → usa a matriz **atribuída à entidade**; UUID → executa essa matriz **somente nesta execução** (override; não altera a linha da entidade).
```json theme={null}
"riskMatrix": { "execute": true, "riskMatrixId": null }
```
Com `true`, se uma entidade filha (sócio / relacionado) **já existia** na organização (mesmo tax ID), o pipeline **reexecuta** os enriquecimentos configurados para essa filha em vez de pular o refresh.
## Assíncrono (padrão): HTTP 202 + Socket.IO
Com `runInBackground: true`, a resposta é **202**:
```json theme={null}
{
"success": true,
"data": {
"status": "processing",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"countryCode": "BR",
"entityType": "company"
}
}
```
Use a mesma conexão **Socket.IO** do painel. Eventos:
| Evento | Quando | Payload (resumo) |
| ------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity:relationship-materialize-started` | Pipeline enfileirado | `entityId`, `mainEntityName`, `mainEntityTaxId`, `mainEntityType`, `userId` |
| `entity:relationship-materialize-completed` | Fim com sucesso ou parcial | `entityId`, `success`, `entitiesCreated`, `relationshipsCreated`, `enrichmentExecuted`, `enrichmentProviders`, `riskMatrixExecuted`, opcional `error` (string) |
| `entity:relationship-materialize-failed` | Falha não tratada | `entityId`, `error: { code, message, details? }`, `userId` |
Após `completed` ou `failed`, busque novamente entidade, relações e listas conforme sua integração (`GET /entities/:id`, etc.).
## Resposta 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
}
}
```
Se a materialização terminar com **aviso** de pipeline, `success` pode ser `true` e `data.error` trazer mensagem legível — verifique ambos.
## Exemplo: empresa BR, assíncrono + matriz de risco
```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 }
}'
```
## Exemplo: forçar uma matriz específica só nesta execução
```json theme={null}
{
"runEnrichmentFirst": false,
"depth": 1,
"runInBackground": false,
"riskMatrix": {
"execute": true,
"riskMatrixId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
```
## Erros (seleção)
| HTTP | Código (típico) | Significado |
| ---- | ---------------------------------------- | -------------------------------------------------------------------------------- |
| 400 | `INVALID_ENTITY_TYPE` | Entidade não é `company` nem `person` |
| 400 | `COUNTRY_NOT_SUPPORTED` | Sem estratégia / país não suportado para este fluxo |
| 400 | `NO_DEFAULT_RELATIONSHIP_ENRICHMENTS` | A estratégia do país não define provedores de relação para este tipo de entidade |
| 404 | `ENTITY_NOT_FOUND` | `entityId` inexistente para a organização |
| 422 | `NO_NORMALIZED_ENRICHMENT` | `runEnrichmentFirst: false` sem linha normalizada |
| 422 | `INVALID_RELATIONSHIP_ENRICHMENT_CONFIG` | Configuração inválida de enrichments filhos / profundidade |
| 500 | `ENRICHMENT_FAILED` | Falha no enriquecimento com `runEnrichmentFirst: true` (detalhes no corpo) |
## Ver também
* [Analisar entidade](/en/api-reference/entities/analyze)
* [Criar pessoa](/pt/api-reference/person/create) / [Criar empresa](/pt/api-reference/company/create)
* [Criação automática (pessoa)](/pt/api-reference/person/create-automatic) / [Criação automática (empresa)](/pt/api-reference/company/create-automatic)
* [Códigos de provedores (pessoa)](/pt/api-reference/integrations/person-provider-codes) / [Códigos de provedores (empresa)](/pt/api-reference/integrations/company-provider-codes)
* [Formatos de documento fiscal](/pt/api-reference/entities/tax-id-formats)