> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar entidade (refresh)

> Reexecutar enrichments em entidade existente com recursão opcional de sócios e motor de regras — escopo unificado e flags preserve para nome e ficha.

## 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.

<Note>
  **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`.
</Note>

## 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

<ParamField path="entityId" type="string" required>
  UUID da entidade a atualizar.
</ParamField>

## Corpo

<ParamField body="forceRefresh" type="boolean" default="true">
  Se `true`, ignora cache e chama os provedores novamente.
</ParamField>

<ParamField body="skipRulesEngine" type="boolean" default="false">
  Se `true`, não executa regras após o enrichment.
</ParamField>

<ParamField body="depth" type="integer" default="1">
  Profundidade de sócios (**0–5**). Ignorado com `refreshScope: "basic_data"` (sempre **0**).
</ParamField>

<ParamField body="autoExecuteIntegrations" type="object">
  Seleção **legacy** de provedores (quando `refreshScope` é omitido). Mesmo formato de [`POST /entities/automatic`](/pt/api-reference/entities/create-automatic).
</ParamField>

<ParamField body="autoExecuteIntegrationsShareholders" type="object">
  Pipeline de sócios (empresas, `depth` > 0).
</ParamField>

<ParamField body="refreshScope" type="string">
  Escopo unificado opcional. Quando definido, **substitui** `autoExecuteIntegrations` na raiz:

  | Valor            | Comportamento                                                     |
  | ---------------- | ----------------------------------------------------------------- |
  | **`basic_data`** | Um provedor de dados básicos do país (chamada fresh). Sem sócios. |
  | **`all_active`** | Todos os enrichments ativos para tipo e país.                     |
  | **`selected`**   | Lista explícita em `providerCodes` (obrigatório, não vazio).      |
</ParamField>

<ParamField body="providerCodes" type="array">
  Obrigatório quando `refreshScope` é **`selected`**.
</ParamField>

<ParamField body="preserveName" type="boolean">
  * **`true`**: manter nome atual.
  * **`false`**: sincronizar do mapeamento (`basic_data`) ou `fullName` normalizado.
  * **Omitido (legacy)**: sincronizar nome se `fullName` mudou.
</ParamField>

<ParamField body="preserveEntityData" type="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`.
</ParamField>

## Exemplos

### Refresh legacy (comportamento inalterado)

```bash theme={null}
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)

```bash theme={null}
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](/pt/api-reference/entities/analyze)).

## Eventos Socket.IO

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

## Endpoints relacionados

<CardGroup cols={2}>
  <Card title="Analyze" icon="chart-line" href="/pt/api-reference/entities/analyze">
    Motor de regras (enrichment opcional).
  </Card>

  <Card title="Materializar relações" icon="sitemap" href="/pt/api-reference/entities/materialize-relationships">
    Cadeia de sócios a partir do normalized.
  </Card>
</CardGroup>