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

> Atualizar atributos e dados para uma empresa existente — para entidades de empresa na plataforma de risco e compliance gu1, com exemplos para update.

## Visão Geral

Atualiza os atributos e dados de uma empresa existente. Este endpoint aciona automaticamente uma reavaliação da pontuação de risco da empresa e emite eventos de atualização em tempo real.

## 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 do gu1 da empresa a atualizar
</ParamField>

## Corpo da Requisição

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 empresa
</ParamField>

<Note>
  O **ID externo** não é atualizado neste endpoint. Use [Alterar ID externo](/pt/api-reference/company/change-external-id) (`POST /entities/change-external-id`) com `reason` obrigatório (mín. 5 caracteres).
</Note>

<ParamField body="taxId" type="string">
  Atualizar número de identificação fiscal
</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 atributos existentes)
</ParamField>

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

<ParamField body="status" type="string">
  Atualizar status da empresa. Status disponíveis:

  * `pending` - Estado inicial, aguardando processamento
  * `under_review` - Sob revisão manual
  * `active` - Aprovado e ativo
  * `suspended` - Temporariamente suspenso (requer `reason`)
  * `blocked` - Permanentemente bloqueado (requer `reason`)
  * `rejected` - Rejeitado durante onboarding (requer `reason`)

  **Nota**: Mudanças de status para `suspended`, `blocked` ou `rejected` requerem um campo `reason` para fins de auditoria.
</ParamField>

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

<ParamField body="riskMatrixId" type="string">
  UUID da matriz de risco para associar a esta empresa. Atualiza quais regras são usadas para avaliação de risco.
</ParamField>

## Resposta

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

<ResponseField name="evaluation" type="object">
  Avaliação recém-criada acionada pela atualização

  * `id` - ID da avaliação
  * `entityId` - ID da entidade
  * `decision` - "PENDING" (aguardando processamento)
  * `evaluationType` - "SYSTEM"
  * `reasons` - Array com "Re-evaluation triggered by attribute change"
</ResponseField>

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

<Note>
  Este endpoint **não** retorna `rulesResult` nem `rulesExecutionSummary`. O motor de regras não é executado na atualização; esses campos são retornados apenas por endpoints que executam regras (criar, criar-automático, enriquecer, refrescar, analisar).
</Note>

## Comportamento

Quando você atualiza uma empresa, o sistema automaticamente:

1. **Registra a mudança** no log de eventos da entidade com um snapshot antes/depois
2. **Aciona reavaliação** para recalcular a pontuação de risco com base nos novos dados
3. **Emite evento em tempo real** para notificar clientes conectados sobre a atualização
4. **Mantém trilha de auditoria** para fins de conformidade e revisão

## Exemplos

### Atualizar Renda e Ocupação da Empresa

<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": {
        "company": {
          "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: {
          company: {
            income: 95000,
            occupation: 'Senior Software Engineer'
          }
        }
      })
    }
  );

  const result = await response.json();
  console.log('Updated company:', 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': {
              'company': {
                  'income': 95000,
                  'occupation': 'Senior Software Engineer'
              }
          }
      }
  )

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

### Atualizar Informações de Contato

<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": {
        "company": {
          "email": "new.email@example.com",
          "phone": "+54 11 9876-5432",
          "address": "Av. Libertador 2500, Buenos Aires"
        }
      }
    }'
  ```

  ```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: {
          company: {
            email: 'new.email@example.com',
            phone: '+54 11 9876-5432',
            address: 'Av. Libertador 2500, Buenos Aires'
          }
        }
      })
    }
  );

  const result = await response.json();
  console.log('Contact information updated');
  ```

  ```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': {
              'company': {
                  'email': 'new.email@example.com',
                  'phone': '+54 11 9876-5432',
                  'address': 'Av. Libertador 2500, Buenos Aires'
              }
          }
      }
  )

  result = response.json()
  print("Contact information updated")
  ```
</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 Empresa

<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 '{
      "status": "suspended",
      "reason": "Suspicious activity detected - pending investigation"
    }'
  ```

  ```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({
        status: 'suspended',
        reason: 'Suspicious activity detected - pending investigation'
      })
    }
  );

  const result = await response.json();
  console.log('Status updated to:', result.entity.status);
  ```

  ```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={
          'status': 'suspended',
          'reason': 'Suspicious activity detected - pending investigation'
      }
  )

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

## Exemplo de Resposta

```json theme={null}
{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "business_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "company",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "company": {
        "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": {
      "company": {
        "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"]
}
```

### 400 Bad Request - Motivo Ausente para Mudança de Status

```json theme={null}
{
  "error": "Changing status to 'suspended' requires a reason for audit purposes."
}
```

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

```javascript theme={null}
// Após completar a verificação KYB, atualize a empresa
const response = await fetch(`http://api.gu1.ai/entities/${companyId}`, {
  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}
# Enriqueça o perfil da empresa à medida que mais informações ficam disponíveis
def update_business_info(company_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{company_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'company': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()
```

## Melhores Práticas

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

## Próximos Passos

* [Obter Empresa](/pt/api-reference/company/get) - Visualizar detalhes da empresa atualizada
* [Listar Empresas](/pt/api-reference/company/list) - Consultar empresas com filtros
* [Upsert Empresa](/pt/api-reference/company/upsert) - Criar ou atualizar em uma operação