Skip to main content
PATCH
/
entities
/
{id}
/
country-activations
/
{countryCode}
Atualizar ativação de país por entidade
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

Define o status operacional de ativação para um país em uma entidade merchant. Não altera o perfil da entidade — use GET /entities/{id} para reconsultar o dossiê após ativar. Em cada mudança real de status, a Gu1 emite o webhook entity.country_activation_changed para endpoints inscritos. Transições entre status são livres (qualquer status pode ir para qualquer outro). Valores suportados de countryCode: AR, BR, CL, CO, MX, US (case-insensitive).

​
Endpoint

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

​
Autenticação

Requer entities:edit (fallback legacy: entities:write). 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
UUID da entidade (merchant).
​
countryCode
string
required
País ISO 3166-1 alpha-2 a atualizar (AR, BR, CL, CO, MX, US).

​
Request Body

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

​
Resposta

CampoTipoDescrição
data.entityIdstringUUID da entidade
data.countryCodestringCódigo de país normalizado
data.statusstringNovo status
data.previousStatusstringStatus antes desta chamada
data.changedbooleanfalse se o status já era o solicitado (sem webhook)
data.activatedAtstring | nullTimestamp da última vez em activated
data.deactivatedAtstring | nullTimestamp da última vez em deactivated
data.updatedAtstring | nullTimestamp da última alteração
data.countriesarraySnapshot completo dos seis países do allowlist após esta chamada

​
Exemplo

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 do webhook (ao alterar)

Quando changed é true, inscritos recebem: 
{
  "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"
  }
}

​
Erros

HTTPCodeQuando
400UNSUPPORTED_COUNTRY_CODEPaís fora do allowlist v1
404ENTITY_NOT_FOUNDA entidade não existe na organização atual