Skip to main content
PATCH
/
entities
/
{id}
/
country-activations
/
{countryCode}
Actualizar activación de país por entidad
curl --request PATCH \
  --url http://api.gu1.ai/entities/{id}/country-activations/{countryCode} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>"
}
'

​
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} para re-consultar el dossier tras activar. Ante cada cambio real de estado, Gu1 emite el webhook entity.country_activation_changed 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). 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
UUID de la entidad (merchant).
​
countryCode
string
required
País ISO 3166-1 alpha-2 a actualizar (AR, BR, CL, CO, MX, US).

​
Request Body

​
status
string
required
Uno de: deactivated, activation_requested, activation_in_progress, activated.

​
Respuesta

CampoTipoDescripción
data.entityIdstringUUID de la entidad
data.countryCodestringCódigo de país normalizado
data.statusstringNuevo estado
data.previousStatusstringEstado antes de esta llamada
data.changedbooleanfalse si el estado ya era el solicitado (sin webhook)
data.activatedAtstring | nullTimestamp de última vez en activated
data.deactivatedAtstring | nullTimestamp de última vez en deactivated
data.updatedAtstring | nullTimestamp del último cambio
data.countriesarraySnapshot completo de los seis países del allowlist tras esta llamada

​
Ejemplo

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

{
  "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: 
{
  "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

HTTPCodeCuándo
400UNSUPPORTED_COUNTRY_CODEPaís fuera del allowlist v1
404ENTITY_NOT_FOUNDLa entidad no existe en la organización actual