Skip to main content
POST
/
entities
/
{entityId}
/
relationships
/
materialize
Materializar relações
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
}
'

​
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.
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: 
Authorization: Bearer YOUR_API_KEY

​
Parâmetros de rota

​
entityId
string
required
UUID da entidade raiz (pessoa ou empresa) cujas relações você quer materializar.

​
Corpo da requisição

​
runEnrichmentFirst
boolean
default:"false"
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).
​
depth
integer
default:"1"
Quantos níveis de sócios ou relacionados processar. Faixa 0–5 (padrão do 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"
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.
​
runInBackground
boolean
default:"true"
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.
​
riskMatrix
object
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).
"riskMatrix": { "execute": true, "riskMatrixId": null }
​
refreshEnrichShareholders
boolean
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: 
{
  "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:
EventoQuandoPayload (resumo)
entity:relationship-materialize-startedPipeline enfileiradoentityId, mainEntityName, mainEntityTaxId, mainEntityType, userId
entity:relationship-materialize-completedFim com sucesso ou parcialentityId, success, entitiesCreated, relationshipsCreated, enrichmentExecuted, enrichmentProviders, riskMatrixExecuted, opcional error (string)
entity:relationship-materialize-failedFalha não tratadaentityId, 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

{
  "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

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

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

​
Erros (seleção)

HTTPCódigo (típico)Significado
400INVALID_ENTITY_TYPEEntidade não é company nem person
400COUNTRY_NOT_SUPPORTEDSem estratégia / país não suportado para este fluxo
400NO_DEFAULT_RELATIONSHIP_ENRICHMENTSA estratégia do país não define provedores de relação para este tipo de entidade
404ENTITY_NOT_FOUNDentityId inexistente para a organização
422NO_NORMALIZED_ENRICHMENTrunEnrichmentFirst: false sem linha normalizada
422INVALID_RELATIONSHIP_ENRICHMENT_CONFIGConfiguração inválida de enrichments filhos / profundidade
500ENRICHMENT_FAILEDFalha no enriquecimento com runEnrichmentFirst: true (detalhes no corpo)

​
Ver também