> ## 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 atributos da entidade

> Atualiza apenas atributos personalizados — modo merge aditivo ou substituição total. Dispara matrizes de risco entity_updated quando configurado.

## Visão geral

Atualiza **somente** `attributes` sem alterar outros campos do perfil. Dois modos:

| Modo                 | Comportamento                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| **`merge`** (padrão) | Merge superficial: chaves enviadas sobrescrevem ou criam valores; **chaves não enviadas são mantidas** |
| **`replace`**        | Substituição total: o objeto `attributes` do body vira o mapa completo (`{}` limpa tudo)               |

Os atributos são armazenados **exatamente como enviados** — objetos aninhados atuam como categorias e são retornados como enviados, igual a [Atualizar entidade](/pt/api-reference/entities/update):

```json theme={null}
{
  "mode": "merge",
  "attributes": {
    "contact": { "phone": "+54..." },
    "otro_grupo": { "branchCode": "AR-01" }
  }
}
```

<Note>O merge é raso no primeiro nível: enviar um objeto de categoria (ex.: `contact`) substitui toda essa categoria. Chaves internas não incluídas são descartadas. Use `replace` para reescrever tudo.</Note>

Se a matriz atribuída inclui trigger **`entity_updated`**, as regras rodam após o patch (respeita `skipRulesExecution` e `watchFields`). Webhook **`entity.updated`** é emitido com `changes.attributes`.

## Endpoint

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

## Autenticação

Requer `entities:edit` (fallback legacy: `entities:write`).

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

## Parâmetros de rota

<ParamField path="id" type="string" required>
  UUID da entidade.
</ParamField>

## Body

<ParamField body="attributes" type="object" required>
  Mapa de atributos. Armazenado exatamente como enviado: valores escalares/array na raiz ficam sem categoria; objetos aninhados atuam como categorias.
</ParamField>

<ParamField body="mode" type="string" default="merge">
  `merge` — patch aditivo (padrão). `replace` — substituição completa.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean">
  Com `true`, omite execução de matrizes de risco após a atualização.
</ParamField>

## Resposta

| Campo                        | Tipo   | Descrição                     |
| ---------------------------- | ------ | ----------------------------- |
| `data.entityId`              | string | UUID da entidade              |
| `data.mode`                  | string | `merge` ou `replace` aplicado |
| `data.attributes`            | object | Atributos finais              |
| `data.updatedAt`             | string | Timestamp ISO 8601            |
| `data.rulesExecutionSummary` | object | Resumo da execução de regras  |

## Exemplos

### Merge (padrão)

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/entities/{id}/attributes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "contact": { "phone": "+54115550000" }
    }
  }'
```

Chaves existentes não enviadas permanecem inalteradas.

### Substituição total

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/entities/{id}/attributes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "replace",
    "attributes": {
      "commercial": { "mcc": "5411" }
    }
  }'
```

Chaves que existiam e não estão em `attributes` são **removidas**.

## Erros

| HTTP | Código             | Quando                            |
| ---- | ------------------ | --------------------------------- |
| 404  | `ENTITY_NOT_FOUND` | Entidade inexistente ou outra org |
| 400  | validation         | Body inválido                     |