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

> Atualizar atributos e dados de uma pessoa ou empresa existente — no modelo universal de entidades gu1 para KYC, KYB e análise de risco.

## Visão Geral

Atualiza os atributos e dados de uma entidade existente. Se a entidade tiver matriz atribuída com trigger **`entity_updated`**, o motor de regras pode executar após a atualização (respeitando `watchFields` opcionais na matriz e `skipRulesExecution`). Auditoria e eventos em tempo real são sempre registrados.

## Endpoint

```
PATCH http://api.gu1.ai/entities/{id}
```

## Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de Caminho

<ParamField path="id" type="string" required>
  O ID gu1 da entidade a ser atualizada
</ParamField>

## Corpo da Requisição

Todos os campos do schema de criação estão disponíveis, exceto `type` (o tipo de entidade não pode ser alterado). Todos os campos são opcionais - inclua apenas os campos que deseja atualizar.

<ParamField body="name" type="string">
  Atualizar o nome de exibição da entidade
</ParamField>

<Note>
  O **ID externo** não é atualizado neste endpoint. Use [Alterar ID externo](/pt/api-reference/person/change-external-id) (`POST /entities/change-external-id`) com `reason` obrigatório (mín. 5 caracteres). As rotas `PATCH` de atualização ignoram `externalId` no corpo.
</Note>

<ParamField body="taxId" type="string">
  Atualizar número de identificação fiscal
</ParamField>

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

<ParamField body="phone" type="string | null">
  Atualizar o telefone de contato na raiz da entidade. Omita o campo para não alterar; envie `null` para limpar.
</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` em `entityData` de pessoa/empresa, a raiz pode ser recalculada quando vier no mesmo request.
</ParamField>

<ParamField body="countryCode" type="string">
  Atualizar código de país ISO 3166-1 alpha-2
</ParamField>

<ParamField body="attributes" type="object">
  Atualizar atributos personalizados (mescla com as chaves de primeiro nível existentes).

  Os atributos são armazenados **exatamente como enviados**: a forma que você envia é a forma que recebe na leitura.

  **Sem categoria (plano):** valores escalares ou arrays no primeiro nível.

  ```json theme={null}
  { "phone": "+54...", "mcc": "5411" }
  ```

  **Categorizado (aninhado):** um objeto de primeiro nível agrupa suas chaves internas sob essa categoria. A chave do objeto *é* a categoria — use chaves seguras como identificador (ex.: `contact`, `category_billing`) para funcionarem em caminhos de regra.

  ```json theme={null}
  {
    "contact": { "phone": "+54..." },
    "commercial": { "mcc": "5411" }
  }
  ```

  Regras e webhooks leem a forma armazenada: chaves planas como `attributes.phone`, aninhadas como `attributes.contact.phone`.
</ParamField>

<ParamField body="status" type="string">
  Status do ciclo de vida (`active`, `inactive`, `blocked`, `under_review`, `suspended`, `pending_verification`, `expired`, `rejected`, `deleted`).

  **Obrigatório com `reason`**: qualquer mudança de status deve incluir `reason` para auditoria.
</ParamField>

<ParamField body="reason" type="string">
  Motivo da atualização (especialmente ao mudar o status para `blocked` ou `rejected`).

  **Obrigatório quando**: mudança de status para blocked, rejected ou suspended.
</ParamField>

<ParamField body="changeStatusManual" type="boolean" default="false">
  Com `true`, atualizações **automáticas** de `status` são desativadas: regras de matriz de risco e automações como `set_entity_status` não alteram o status. Atualizações manuais por este endpoint (ou UI) continuam válidas.

  * Padrão: `false`.
  * Enviar `false` explicitamente remove o bloqueio.
  * Não desativa cálculo de risco nem outros efeitos de regras; apenas gravações de **status** por regras/automações.

  **Obrigatório com `reason`**: se `changeStatusManual` mudar (ativar ou desativar), enviar `reason` no mesmo PATCH para auditoria.
</ParamField>

### Matrizes de risco

Atribuir ou substituir as matrizes de risco da entidade. Mesma semântica de [Criar entidade](/pt/api-reference/entities/create) (`riskMatrixId` / `riskMatrixIds`).

<ParamField body="riskMatrixId" type="string | string[] | null">
  Legacy: um UUID, um array de UUIDs ou `null` para remover todas as matrizes atribuídas. Se `riskMatrixIds` vier não vazio, tem precedência sobre este campo.
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Forma preferida para **várias** matrizes: lista ordenada de UUIDs da sua organização. Envie `[]` (ou `riskMatrixId: null`) para desatribuir todas. Cada UUID deve existir na org; caso contrário a API retorna `400` com código `INVALID_RISK_MATRIX`.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean" default="false">
  Com `true`, pula a avaliação automática de matrizes na atualização mesmo que existam matrizes com trigger `entity_updated`.
</ParamField>

<Note>
  Atualizar matrizes **apenas persiste a atribuição**; a atribuição sozinha não executa regras.

  **Regras na atualização:** se a entidade tiver ao menos uma matriz com trigger `entity_updated` e `skipRulesExecution` não for `true`, a API executa o motor após mudança de campos. Matrizes podem restringir com **`watchFields`** (somente quando paths listados mudam, ex. `email`, `attributes.clientTypes`). O webhook `entity.updated` inclui `rulesExecutionSummary` quando regras rodaram ou foram omitidas com motivo.

  Os mesmos campos se aplicam em [Atualizar por ID externo](/pt/api-reference/entities/update-by-external-id) e `PATCH /entities/by-tax-id/{taxId}`.
</Note>

<ParamField body="entityData" type="object">
  Atualizar dados específicos do tipo (mescla com entityData existente)
</ParamField>

## Resposta

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

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

<Note>
  O corpo HTTP **não** inclui `rulesExecutionSummary`. Quando regras rodam (ou são omitidas), o resumo vai no webhook **`entity.updated`**.
</Note>

## Comportamento

Quando você atualiza uma entidade, o sistema:

1. **Registra a alteração** na auditoria com valores antes/depois
2. **Executa matrizes de risco** quando há matrizes atribuídas com `entity_updated`, `skipRulesExecution` não é `true`, e `watchFields` opcionais coincidem com campos alterados
3. **Emite evento em tempo real** para clientes conectados
4. **Dispara webhook `entity.updated`** com `changes` e opcional `rulesExecutionSummary`
5. **Mantém trilha de auditoria** para fins de conformidade e revisão

## Exemplos

### Atualizar Renda de Pessoa

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "person": {
          "income": 95000,
          "occupation": "Senior Software Engineer"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          person: {
            income: 95000,
            occupation: 'Senior Software Engineer'
          }
        }
      })
    }
  );

  const result = await response.json();
  console.log('Updated entity:', result.entity);
  console.log('Re-evaluation triggered:', result.evaluation.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityData': {
              'person': {
                  'income': 95000,
                  'occupation': 'Senior Software Engineer'
              }
          }
      }
  )

  result = response.json()
  print(f"Updated entity: {result['entity']['name']}")
  print(f"Re-evaluation ID: {result['evaluation']['id']}")
  ```
</CodeGroup>

### Atualizar Informações da Empresa

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "company": {
          "employeeCount": 75,
          "revenue": 7500000
        }
      },
      "attributes": {
        "partnershipTier": "platinum",
        "monthlyVolume": 500000
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          company: {
            employeeCount: 75,
            revenue: 7500000
          }
        },
        attributes: {
          partnershipTier: 'platinum',
          monthlyVolume: 500000
        }
      })
    }
  );

  const result = await response.json();
  console.log('Company updated:', result.entity.name);
  console.log('New revenue:', result.entity.entityData.company.revenue);
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityData': {
              'company': {
                  'employeeCount': 75,
                  'revenue': 7500000
              }
          },
          'attributes': {
              'partnershipTier': 'platinum',
              'monthlyVolume': 500000
          }
      }
  )

  result = response.json()
  print(f"Company updated: {result['entity']['name']}")
  print(f"New revenue: ${result['entity']['entityData']['company']['revenue']:,}")
  ```
</CodeGroup>

### Atualizar Apenas Atributos Personalizados

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "attributes": {
        "accountTier": "premium",
        "loyaltyPoints": 15000,
        "lastLoginDate": "2024-10-03T14:00:00Z"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        attributes: {
          accountTier: 'premium',
          loyaltyPoints: 15000,
          lastLoginDate: '2024-10-03T14:00:00Z'
        }
      })
    }
  );

  const result = await response.json();
  console.log('Attributes updated:', result.entity.attributes);
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'attributes': {
              'accountTier': 'premium',
              'loyaltyPoints': 15000,
              'lastLoginDate': '2024-10-03T14:00:00Z'
          }
      }
  )

  result = response.json()
  print(f"Attributes updated: {result['entity']['attributes']}")
  ```
</CodeGroup>

### Atualizar Status da Transação

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "transaction": {
          "status": "reviewed",
          "flagged": false
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          transaction: {
            status: 'reviewed',
            flagged: false
          }
        }
      })
    }
  );

  const result = await response.json();
  console.log('Transaction status updated');
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityData': {
              'transaction': {
                  'status': 'reviewed',
                  'flagged': False
              }
          }
      }
  )

  result = response.json()
  print("Transaction status updated")
  ```
</CodeGroup>

## Exemplo de Resposta

```json theme={null}
{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "person",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Senior Software Engineer",
        "income": 95000
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "accountTier": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T16:45:00.000Z",
    "deletedAt": null
  },
  "evaluation": {
    "id": "eval_new_123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "decision": "PENDING",
    "evaluationType": "SYSTEM",
    "reasons": ["Re-evaluation triggered by attribute change"],
    "rules": [],
    "entitySnapshot": {...}
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "person": {
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "updatedAt": "2024-10-03T14:35:00.000Z"
  }
}
```

## Respostas de Erro

### 404 Not Found

```json theme={null}
{
  "error": "Entity not found"
}
```

### 400 Bad Request - Dados Inválidos

```json theme={null}
{
  "error": "Validation failed",
  "details": ["Invalid country code format"]
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to update entity"
}
```

## Casos de Uso

### Atualizar Após Verificação KYC

```javascript theme={null}
// Após concluir a verificação KYC, atualizar a entidade
const response = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      kycVerified: true,
      kycVerificationDate: new Date().toISOString(),
      kycProvider: 'manual_review'
    }
  })
});
```

### Enriquecimento Progressivo de Perfil

```python theme={null}
# Enriquecer perfil do cliente conforme mais informações ficam disponíveis
def update_customer_info(entity_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{entity_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'person': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()
```

### Resolução de Transação

```javascript theme={null}
// Marcar uma transação sinalizada como resolvida após investigação
async function resolveTransaction(txnId, resolution) {
  const response = await fetch(`http://api.gu1.ai/entities/${txnId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        transaction: {
          status: 'resolved',
          flagged: false
        }
      },
      attributes: {
        resolutionDate: new Date().toISOString(),
        resolutionNotes: resolution,
        reviewedBy: 'compliance_team'
      }
    })
  });

  return response.json();
}
```

## Melhores Práticas

1. **Atualizações Parciais**: Envie apenas os campos que deseja alterar - não é necessário enviar a entidade inteira
2. **Monitorar Reavaliações**: Verifique o ID da avaliação retornado para acompanhar o recálculo da pontuação de risco
3. **Trilha de Auditoria**: Use o `previousEntity` na resposta para manter o histórico de alterações
4. **Sincronização em Tempo Real**: Atualizações emitem eventos WebSocket para sincronização de UI em tempo real
5. **Idempotência**: Seguro para tentar novamente - atualizações com os mesmos dados não criarão eventos duplicados

## Próximos Passos

* [Obter Entidade](/api-reference/entities/get) - Visualizar detalhes da entidade atualizada
* [Listar Entidades](/api-reference/entities/list) - Consultar entidades com filtros
* [Upsert Entidade](/api-reference/entities/upsert) - Criar ou atualizar em uma operação
* [Solicitar Análise de IA](/en/api-reference/entities/analyze) - Obter avaliação de risco atualizada