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,
  "rootIntegrationCodesBeforeMaterialize": [
    {}
  ],
  "runAllActiveIntegrationsOnRootFirst": true,
  "forceRefresh": true,
  "depth": 123,
  "shareholderEnrichments": {},
  "relationshipChildrenFromSourceOnly": true,
  "runInBackground": true,
  "riskMatrix": {},
  "allActiveIntegrationsForChildEntities": true,
  "reEnrichExistingChildEntities": 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, com runAllActiveIntegrationsOnRootFirst, rootIntegrationCodesBeforeMaterialize ou os padrões da estratégia) e em seguida executar 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 enriquecimentos na entidade raiz do dossiê antes de materializar. Quais provedores rodam é definido por runAllActiveIntegrationsOnRootFirst, rootIntegrationCodesBeforeMaterialize ou, se ambos estiverem desligados/omitidos, pelos padrões da estratégia do país para descobrir relações (ex.: Brasil: acionistas em empresas; empresas e pessoas relacionadas em pessoas).Se false, já deve existir uma linha em normalized_enrichment; caso contrário a API retorna 422 (NO_NORMALIZED_ENRICHMENT).
​
rootIntegrationCodesBeforeMaterialize
array
Lista explícita de códigos de provedor a executar na entidade raiz quando runEnrichmentFirst é true. Ignorada se runAllActiveIntegrationsOnRootFirst for true. Se omitida e runAllActiveIntegrationsOnRootFirst for false, usam-se os padrões da estratégia do país.
​
runAllActiveIntegrationsOnRootFirst
boolean
default:"false"
Com true (e runEnrichmentFirst: true), executa todos os enriquecimentos ativos do marketplace para o tipo e país da entidade raiz antes de materializar. Prevalece sobre rootIntegrationCodesBeforeMaterialize e sobre os padrões da estratégia nesse passo prévio. Maior custo/tempo. Exige runEnrichmentFirst.
​
forceRefresh
boolean
default:"true"
Só vale com runEnrichmentFirst: true: pede dados novos aos provedores quando a integração permite, em vez de depender de cache.
​
depth
integer
default:"1"
Quantos níveis de sócios ou relacionados processar. Faixa 0–5 (padrão do esquema 1).
​
shareholderEnrichments
object
Integrações por tipo de filho (empresa vs pessoa) ao criar ou enriquecer cada entidade filha, como na criação automática:
{
  "company": ["br_bdc_shareholders_enrichment"],
  "person": ["br_cpfcnpj_complete_person_enrichment"]
}
Chaves company e person: arrays de códigos de provedor. Opcional.
​
relationshipChildrenFromSourceOnly
boolean
default:"false"
Com true, cada novo filho é criado apenas com nome e identificador do normalizado, sem o passo prévio obrigatório de “dados básicos” da estratégia. Vale para empresa e pessoa (Brasil): em empresas, acionistas do QSA; em pessoas, entradas em normalized.relationships e empresas em normalized.shareholders em que a pessoa é titular. Se shareholderEnrichments não estiver vazio, esses provedores rodam depois em lote sobre a linha criada. Com false ou omitido mantém-se o fluxo padrão de criação dos filhos.
​
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 }
​
allActiveIntegrationsForChildEntities
boolean
Com true, cada entidade filha descoberta (acionista / empresa relacionada / pessoa relacionada) é enriquecida com todas as integrações ativas do marketplace para o seu tipo (company vs person), em vez das listas explícitas em shareholderEnrichments. Com false ou omitido, use shareholderEnrichments (e depth) como de costume.
​
reEnrichExistingChildEntities
boolean
Com true, se uma entidade relacionada já existia na organização, o pipeline reexecuta os enriquecimentos configurados para essa filha em vez de pular o refresh. Vale para a fase de materialização de sócios/relacionados.

​
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,
    "forceRefresh": false,
    "depth": 2,
    "shareholderEnrichments": {
      "company": ["br_bdc_shareholders_enrichment"],
      "person": ["br_cpfcnpj_complete_person_enrichment"]
    },
    "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_ACTIVE_ENRICHMENTSrunAllActiveIntegrationsOnRootFirst sem provedores ativos
400NO_DEFAULT_RELATIONSHIP_ENRICHMENTSPaís sem códigos padrão; envie rootIntegrationCodesBeforeMaterialize ou ative runAllActiveIntegrationsOnRootFirst
404ENTITY_NOT_FOUNDentityId inexistente para a organização
422NO_NORMALIZED_ENRICHMENTrunEnrichmentFirst: false sem linha normalizada
422INVALID_RELATIONSHIP_ENRICHMENT_CONFIGConfiguração inválida de shareholderEnrichments / profundidade
500ENRICHMENT_FAILEDFalha no enriquecimento com runEnrichmentFirst: true (detalhes no corpo)

​
Ver também