> ## 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 activación de país por entidad

> Actualiza el estado de activación por país para un merchant. Idempotente si el estado no cambia; emite webhook entity.country_activation_changed al cambiar.

## Overview

Setea el estado operativo de activación para un país en una entidad merchant. **No** modifica el perfil de la entidad — usá [`GET /entities/{id}`](/es/api-reference/entities/get) para re-consultar el dossier tras activar.

Ante cada cambio real de estado, Gu1 emite el webhook [`entity.country_activation_changed`](/es/webhooks/events/entity-events) a endpoints suscriptos. Las transiciones entre estados son **libres** (cualquier estado puede pasar a cualquier otro).

Valores soportados de `countryCode`: **AR**, **BR**, **CL**, **CO**, **MX**, **US** (case-insensitive).

## Endpoint

```
PATCH http://api.gu1.ai/entities/{id}/country-activations/{countryCode}
```

## Autenticación

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

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

## Path Parameters

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

<ParamField path="countryCode" type="string" required>
  País ISO 3166-1 alpha-2 a actualizar (`AR`, `BR`, `CL`, `CO`, `MX`, `US`).
</ParamField>

## Request Body

<ParamField body="status" type="string" required>
  Uno de: `deactivated`, `activation_requested`, `activation_in_progress`, `activated`.
</ParamField>

## Respuesta

| Campo                 | Tipo           | Descripción                                                          |
| --------------------- | -------------- | -------------------------------------------------------------------- |
| `data.entityId`       | string         | UUID de la entidad                                                   |
| `data.countryCode`    | string         | Código de país normalizado                                           |
| `data.status`         | string         | Nuevo estado                                                         |
| `data.previousStatus` | string         | Estado antes de esta llamada                                         |
| `data.changed`        | boolean        | `false` si el estado ya era el solicitado (sin webhook)              |
| `data.activatedAt`    | string \| null | Timestamp de última vez en `activated`                               |
| `data.deactivatedAt`  | string \| null | Timestamp de última vez en `deactivated`                             |
| `data.updatedAt`      | string \| null | Timestamp del último cambio                                          |
| `data.countries`      | array          | Snapshot completo de los seis países del allowlist tras esta llamada |

## Ejemplo

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/country-activations/CO" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"activation_requested"}'
```

```json theme={null}
{
  "success": true,
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "countryCode": "CO",
    "status": "activation_requested",
    "previousStatus": "deactivated",
    "changed": true,
    "activatedAt": null,
    "deactivatedAt": null,
    "updatedAt": "2026-07-03T15:00:00.000Z",
    "countries": [
      { "countryCode": "AR", "status": "deactivated", "activatedAt": null, "deactivatedAt": null, "updatedAt": null },
      { "countryCode": "CO", "status": "activation_requested", "activatedAt": null, "deactivatedAt": null, "updatedAt": "2026-07-03T15:00:00.000Z" },
      { "countryCode": "MX", "status": "activated", "activatedAt": "2026-07-03T14:00:00.000Z", "deactivatedAt": null, "updatedAt": "2026-07-03T14:00:00.000Z" }
    ]
  }
}
```

## Payload del webhook (al cambiar)

Cuando `changed` es `true`, los suscriptores reciben:

```json theme={null}
{
  "event": "entity.country_activation_changed",
  "timestamp": "2026-07-03T15:00:00.000Z",
  "organizationId": "org-uuid",
  "payload": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "merchant_123",
      "name": "Acme Corp",
      "type": "company",
      "countryCode": "US"
    },
    "countryCode": "CO",
    "status": "activation_requested",
    "previousStatus": "deactivated",
    "activeCountryCodes": ["MX"],
    "countries": [
      { "countryCode": "AR", "status": "deactivated" },
      { "countryCode": "CO", "status": "activation_requested" },
      { "countryCode": "MX", "status": "activated" }
    ],
    "timeline": [
      {
        "previousStatus": "deactivated",
        "status": "activation_requested",
        "changedAt": "2026-07-03T15:00:00.000Z"
      }
    ],
    "changedAt": "2026-07-03T15:00:00.000Z"
  }
}
```

## Errores

| HTTP | Code                       | Cuándo                                         |
| ---- | -------------------------- | ---------------------------------------------- |
| 400  | `UNSUPPORTED_COUNTRY_CODE` | País fuera del allowlist v1                    |
| 404  | `ENTITY_NOT_FOUND`         | La entidad no existe en la organización actual |