Skip to main content
POST
/
entities
/
{entityId}
/
refresh
Atualizar entidade (refresh)
curl --request POST \
  --url http://api.gu1.ai/entities/{entityId}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "forceRefresh": true,
  "skipRulesEngine": true,
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "refreshScope": "<string>",
  "providerCodes": [
    {}
  ],
  "preserveName": true,
  "preserveEntityData": true
}
'

​
Visão geral

Reexecuta enrichments do marketplace para pessoa ou empresa existente, opcionalmente:
  • Atualiza nome e/ou entityData (somente se indicado pelos novos flags)
  • Cria ou re-enriquece sócios (empresas, depth > 0)
  • Executa o motor de regras ao concluir
Equivalente programático ao refresh completo do painel (Risk Matrix) ou ao refresh somente dados básicos do Entity Builder.
Retrocompatibilidade: Omitindo refreshScope, preserveName e preserveEntityData, o comportamento permanece o anterior: provedores via autoExecuteIntegrations e nome sincronizado de fullName normalizado quando muda. entityData não é alterado exceto com refreshScope: "basic_data" e preserveEntityData.

​
Endpoint

POST http://api.gu1.ai/entities/{entityId}/refresh

​
Autenticação

Exige permissão para executar enrichments (igual a POST /entities/{entityId}/enrich).

​
Parâmetros de path

​
entityId
string
required
UUID da entidade a atualizar.

​
Corpo

​
forceRefresh
boolean
default:"true"
Se true, ignora cache e chama os provedores novamente.
​
skipRulesEngine
boolean
default:"false"
Se true, não executa regras após o enrichment.
​
depth
integer
default:"1"
Profundidade de sócios (0–5). Ignorado com refreshScope: "basic_data" (sempre 0).
​
autoExecuteIntegrations
object
Seleção legacy de provedores (quando refreshScope é omitido). Mesmo formato de POST /entities/automatic.
​
autoExecuteIntegrationsShareholders
object
Pipeline de sócios (empresas, depth > 0).
​
refreshScope
string
Escopo unificado opcional. Quando definido, substitui autoExecuteIntegrations na raiz:
ValorComportamento
basic_dataUm provedor de dados básicos do país (chamada fresh). Sem sócios.
all_activeTodos os enrichments ativos para tipo e país.
selectedLista explícita em providerCodes (obrigatório, não vazio).
​
providerCodes
array
Obrigatório quando refreshScope é selected.
​
preserveName
boolean
  • true: manter nome atual.
  • false: sincronizar do mapeamento (basic_data) ou fullName normalizado.
  • Omitido (legacy): sincronizar nome se fullName mudou.
​
preserveEntityData
boolean
Apenas com refreshScope: "basic_data" e enrichment bem-sucedido:
  • Omitido: não alterar entityData.
  • true: preencher apenas campos vazios (gap-fill).
  • false: substituir entityData pelos dados básicos.
Sem efeito em all_active, selected ou bodies legacy sem basic_data.

​
Exemplos

​
Refresh legacy (comportamento inalterado)

curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skipRulesEngine": false,
    "depth": 1,
    "forceRefresh": true,
    "autoExecuteIntegrations": { "executeAllActiveEnrichments": true },
    "autoExecuteIntegrationsShareholders": { "executeAllActiveEnrichments": true }
  }'

​
Somente dados básicos (seguro)

curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshScope": "basic_data",
    "preserveName": true,
    "skipRulesEngine": true,
    "forceRefresh": true
  }'

​
Resposta

Inclui data.entity, data.enrichmentResult, contadores de sócios e errors. Com skipRulesEngine: false, também rulesExecutionSummary na raiz (como Analyze).

​
Eventos Socket.IO

entity:refresh-started, entity:refreshed, entity:refresh-failed.

​
Endpoints relacionados

Analyze

Motor de regras (enrichment opcional).

Materializar relações

Cadeia de sócios a partir do normalized.