Materializar relações
Referência API
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.
POST
Materializar relações
Visão geral
Materializa relações e entidades relacionadas para uma pessoa ou empresa existente usando a linha mais recente denormalized_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.
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
Autenticação
Requer uma chave de API válida: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).
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):truepara rodar a matriz ao finalizar a materialização.riskMatrixId(UUID | null, opcional):nullou omitido → usa a matriz atribuída à entidade; UUID → executa essa matriz somente nesta execução (override; não altera a linha da entidade).
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
ComrunInBackground: true, a resposta é 202:
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 pode ser true e data.error trazer mensagem legível — verifique ambos.