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

# Actualizar atributos de entidad

> Actualiza solo los atributos personalizados de una entidad — modo merge aditivo o reemplazo total. Dispara matrices de riesgo entity_updated cuando corresponde.

## Resumen

Actualiza **solo** `attributes` sin modificar el resto del perfil. Dos modos:

| Modo                  | Comportamiento                                                                                 |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| **`merge`** (default) | Merge superficial: las claves enviadas pisan o crean valores; **las no enviadas se conservan** |
| **`replace`**         | Reemplazo total: el objeto `attributes` del body es el mapa completo (`{}` borra todo)         |

Los atributos se almacenan **tal cual** — los objetos anidados actúan como categorías y se devuelven como se enviaron, igual que [Actualizar entidad](/es/api-reference/entities/update):

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

<Note>El merge es superficial en el primer nivel: enviar un objeto de categoría (p. ej. `contact`) reemplaza toda esa categoría. Las claves internas no incluidas se pierden. Usá `replace` para reescribir todo.</Note>

Si la matriz asignada incluye trigger **`entity_updated`**, corren reglas tras el patch (respeta `skipRulesExecution` y `watchFields`). Se emite webhook **`entity.updated`** con `changes.attributes`.

## Endpoint

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

## Autenticación

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

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

## Parámetros de ruta

<ParamField path="id" type="string" required>
  UUID de la entidad.
</ParamField>

## Body

<ParamField body="attributes" type="object" required>
  Mapa de atributos. Se almacena tal cual: valores escalares/array en la raíz quedan sin categoría; los objetos anidados actúan como categorías.
</ParamField>

<ParamField body="mode" type="string" default="merge">
  `merge` — patch aditivo (default). `replace` — reemplazo completo.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean">
  Con `true`, omite ejecución de matrices de riesgo tras la actualización.
</ParamField>

## Respuesta

| Campo                        | Tipo   | Descripción                    |
| ---------------------------- | ------ | ------------------------------ |
| `data.entityId`              | string | UUID de la entidad             |
| `data.mode`                  | string | `merge` o `replace` aplicado   |
| `data.attributes`            | object | Atributos finales              |
| `data.updatedAt`             | string | Timestamp ISO 8601             |
| `data.rulesExecutionSummary` | object | Resumen de ejecución de reglas |

## Ejemplos

### Merge (default)

```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" }
    }
  }'
```

Las claves existentes que no envíes no cambian.

### Reemplazo 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" }
    }
  }'
```

Las claves que no estén en `attributes` se **eliminan**.

## Errores

| HTTP | Código             | Cuándo                         |
| ---- | ------------------ | ------------------------------ |
| 404  | `ENTITY_NOT_FOUND` | Entidad inexistente u otra org |
| 400  | validation         | Body inválido                  |