Skip to main content
POST
Materializar relações

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

Autenticação

Requer uma chave de API válida:

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
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).
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:
Use a mesma conexão Socket.IO do painel. Eventos: 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

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

Exemplo: forçar uma matriz específica só nesta execução

Erros (seleção)

Ver também