> ## 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 uma entidade por ID externo

> Atualiza uma entidade do gu1 usando seu identificador externo em vez do UUID interno, cobrindo empresas, pessoas e transações em uma única chamada.

## Visão Geral

Este endpoint permite atualizar uma entidade usando seu próprio identificador externo em vez de nosso UUID interno. É útil quando você não armazena nossos UUIDs em seu sistema e apenas rastreia seus próprios IDs externos.

A funcionalidade é idêntica a `PATCH /entities/:id`, mas usa `externalId` como identificador.

## Parâmetros de Rota

<ParamField path="externalId" type="string" required>
  Seu identificador externo único para a entidade
</ParamField>

## Corpo da Solicitação

<ParamField body="name" type="string">
  Nome da entidade (nome completo da pessoa ou nome da empresa)
</ParamField>

<ParamField body="taxId" type="string">
  Número de identificação fiscal (SSN, EIN, VAT, CPF, CNPJ, etc.)
</ParamField>

<ParamField body="email" type="string | null">
  E-mail de contato na raiz da entidade. Omita para não alterar; `null` limpa.
</ParamField>

<ParamField body="phone" type="string | null">
  Telefone de contato na raiz da entidade. Omita para não alterar; `null` limpa.
</ParamField>

<ParamField body="nationality" type="string | null">
  Nacionalidade na raiz (ISO 3166-1 alpha-2 ao persistir). Omita para não alterar; `null` remove. Se atualizar `nationality` dentro de `entityData` no mesmo request, a raiz pode ser recalculada.
</ParamField>

<ParamField body="status" type="string">
  Status da entidade. Valores possíveis:

  * `active`: Entidade está ativa e operacional
  * `inactive`: Entidade está inativa
  * `blocked`: Entidade está bloqueada (requer `reason`)
  * `suspended`: Entidade está suspensa (requer `reason`)
  * `rejected`: Entidade foi rejeitada durante o onboarding (requer `reason`)

  **Nota**: Mudar para `blocked`, `suspended` ou `rejected` requer fornecer um `reason` para auditoria.
</ParamField>

<ParamField body="reason" type="string">
  Obrigatório ao mudar o status para `blocked`, `suspended` ou `rejected`. Fornece trilha de auditoria para a mudança de status.
</ParamField>

<ParamField body="changeStatusManual" type="boolean" default="false">
  Mesma semântica de [Atualizar entidade por ID](/pt/api-reference/entities/update#param-change-status-manual). Com `true`, regras de matriz e automações não alteram `status`.
</ParamField>

<ParamField body="riskMatrixId" type="string | string[] | null">
  Legacy: um UUID, um array de UUIDs ou `null` para remover todas as matrizes. Se `riskMatrixIds` vier não vazio, tem precedência. Ver [Atualizar entidade — Matrizes de risco](/pt/api-reference/entities/update#matrizes-de-risco).
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Forma preferida para **várias** matrizes: lista ordenada de UUIDs da sua organização. Envie `[]` para desatribuir todas.
</ParamField>

<ParamField body="entityData" type="object">
  Estrutura de dados específica da entidade. Para entidades de pessoa, use `entityData.person`. Para entidades de empresa, use `entityData.company`.

  **Campos de pessoa**:

  * `firstName`: Primeiro nome
  * `lastName`: Sobrenome
  * `middleName`: Nome do meio
  * `dateOfBirth`: Data de nascimento (YYYY-MM-DD)
  * `nationality`: Nacionalidade (ISO 3166-1 alpha-2)
  * `email`: Endereço de e-mail
  * `phone`: Número de telefone
  * `address`: Objeto de endereço (street, city, state, country, postalCode)

  **Campos de empresa**:

  * `legalName`: Nome legal da empresa
  * `tradingNames`: Array de nomes comerciais
  * `registrationNumber`: Número de registro da empresa
  * `incorporationDate`: Data de constituição (YYYY-MM-DD)
  * `industry`: Indústria/setor
  * `employees`: Número de funcionários
  * `website`: Site da empresa
  * `address`: Objeto de endereço
</ParamField>

<ParamField body="attributes" type="object">
  Atributos personalizados chave-valor para armazenamento flexível de dados
</ParamField>

<ParamField body="metadata" type="object">
  Metadados do sistema (geralmente definidos pelo sistema, mas podem ser atualizados)
</ParamField>

## Campos Imutáveis

Os seguintes campos **não podem** ser alterados após a criação da entidade:

* `type`: Tipo de entidade (person ou company)
* `countryCode`: Código do país da entidade (ISO 3166-1 alpha-2)

## Resposta

Retorna o objeto de entidade atualizado.

<ResponseField name="entity" type="object">
  O objeto de entidade atualizado com todos os valores atuais
</ResponseField>

<ResponseField name="evaluation" type="object | null">
  Objeto de avaliação (atualmente null - recurso de reavaliação temporariamente desabilitado)
</ResponseField>

<ResponseField name="previousEntity" type="object">
  O estado da entidade antes da atualização (para auditoria)
</ResponseField>

## Exemplo de Solicitação

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Miguel Silva",
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "João",
        "middleName": "Miguel",
        "lastName": "Silva",
        "email": "joao.silva@exemplo.com",
        "phone": "+55-11-98765-4321"
      }
    },
    "riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"]
  }'
```

## Exemplo de Resposta

```json theme={null}
{
  "entity": {
    "id": "uuid-entidade",
    "organizationId": "uuid-org",
    "externalId": "cliente-12345",
    "type": "person",
    "name": "João Miguel Silva",
    "taxId": "123.456.789-00",
    "countryCode": "BR",
    "nationality": "BR",
    "status": "active",
    "riskScore": "35.00",
    "riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"],
    "entityData": {
      "person": {
        "firstName": "João",
        "middleName": "Miguel",
        "lastName": "Silva",
        "email": "joao.silva@exemplo.com",
        "phone": "+55-11-98765-4321"
      }
    },
    "createdAt": "2025-12-20T10:00:00Z",
    "updatedAt": "2025-12-24T15:30:00Z"
  },
  "evaluation": null,
  "previousEntity": {
    "id": "uuid-entidade",
    "name": "João Silva",
    "status": "pending",
    ...
  }
}
```

## Mudança de Status com Motivo

Ao mudar o status para `blocked`, `suspended` ou `rejected`, você **deve** fornecer um motivo:

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked",
    "reason": "Falhou na triagem de sanções - correspondência detectada na lista OFAC"
  }'
```

## Casos de Uso

### 1. Atualizar Informações do Cliente

Atualizar dados do cliente do seu CRM ou sistema de gerenciamento de usuários:

```json theme={null}
{
  "name": "Maria Santos Oliveira",
  "entityData": {
    "person": {
      "lastName": "Santos Oliveira",
      "email": "maria.santosoliveira@exemplo.com",
      "address": {
        "street": "Av. Paulista, 1000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postalCode": "01310-100"
      }
    }
  }
}
```

### 2. Atribuir Matriz de Risco

Atribuir ou alterar a matriz de risco para uma entidade:

```json theme={null}
{
  "riskMatrixIds": ["uuid-matriz-alto-risco"]
}
```

Após atualizar a matriz de risco, você deve acionar uma reanálise usando `POST /entities/:entityId/analyze` para reavaliar a entidade com as novas regras.

### 3. Bloquear Entidade Após Investigação

Bloquear uma entidade após investigação de conformidade:

```json theme={null}
{
  "status": "blocked",
  "reason": "Investigação revelou conexões com entidades sancionadas"
}
```

### 4. Sincronizar Dados da Empresa

Atualizar informações da empresa do registro empresarial:

```json theme={null}
{
  "entityData": {
    "company": {
      "employees": 250,
      "revenue": 50000000,
      "website": "https://empresa-novo-dominio.com.br"
    }
  }
}
```

## Eventos e Webhooks

### Eventos em Tempo Real

Após uma atualização bem-sucedida, o seguinte evento em tempo real é emitido via WebSocket:

```json theme={null}
{
  "event": "entity.updated",
  "entityId": "uuid-entidade",
  "externalId": "cliente-12345",
  "updatedFields": ["name", "entityData"],
  "previousValues": {...},
  "newValues": {...}
}
```

### Gatilhos de Webhook

Se você mudar **apenas** o campo `status` (sem outras mudanças de campo), um webhook é acionado:

**Evento**: `entity.status_changed`

```json theme={null}
{
  "event": "entity.status_changed",
  "entityId": "uuid-entidade",
  "externalId": "cliente-12345",
  "oldStatus": "active",
  "newStatus": "blocked",
  "reason": "Falhou na triagem de sanções",
  "changedBy": "uuid-usuario",
  "timestamp": "2025-12-24T15:30:00Z"
}
```

**Nota**: Se você atualizar o status **junto com outros campos**, o webhook NÃO é acionado (assume edição em massa da entidade em vez de mudança de status independente).

## Trilha de Auditoria

Cada atualização de entidade cria um evento `ATTRIBUTE_CHANGED` no registro de eventos da entidade com:

* Estado anterior (todos os campos alterados)
* Estado posterior (todos os campos alterados)
* Usuário que fez a mudança
* Timestamp
* Fonte (API, dashboard, etc.)

Consultar trilha de auditoria:

```bash theme={null}
GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED
```

## Respostas de Erro

<ResponseField name="404 Not Found" type="error">
  Entidade com o `externalId` especificado não encontrada em sua organização

  ```json theme={null}
  {
    "error": "Entity not found"
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Dados de solicitação inválidos ou erro de validação

  ```json theme={null}
  {
    "error": "Changing status to 'blocked' requires a reason for audit purposes."
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Tentando alterar campos imutáveis

  ```json theme={null}
  {
    "error": "Field 'type' cannot be changed after entity creation"
  }
  ```
</ResponseField>

## Melhores Práticas

1. **Sempre Defina ID Externo na Criação**: Defina `externalId` ao criar entidades via `POST /entities` para habilitar atualizações por ID externo.

2. **Use para Integração de Sistemas**: Este endpoint é ideal para integrações onde você sincroniza dados de sistemas externos (CRM, ERP, etc.) usando seus próprios IDs.

3. **Forneça Motivos para Mudanças de Status**: Sempre inclua motivos significativos ao bloquear, suspender ou rejeitar entidades para a trilha de auditoria de conformidade.

4. **Reanalise Após Mudança de Matriz de Risco**: Após atribuir uma nova matriz de risco, acione `POST /entities/:entityId/analyze` para reavaliar com as novas regras.

5. **Trate 404 com Cuidado**: Se a entidade não for encontrada por ID externo, você pode precisar criá-la primeiro usando `POST /entities`.

6. **Atualizações em Lote**: Para atualizar múltiplas entidades, chame este endpoint concorrentemente com diferentes IDs externos para melhor desempenho.

## Endpoints Relacionados

* [Criar Entidade](/pt/api-reference/entities/create) - Criar nova entidade
* [Atualizar Entidade por UUID](/pt/api-reference/entities/update) - Atualizar usando UUID interno
* [Obter Entidade](/pt/api-reference/entities/get) - Recuperar detalhes da entidade
* [Analisar Entidade](/en/api-reference/entities/analyze) - Acionar análise de risco