Listar cidades do proxy

GET /proxy-regions/cities

Lista as cidades do proxy da Orkesio num país. Pública (sem token nem admintoken), com o mesmo limite (120 pedidos por minuto por IP) e o mesmo cache de 5 minutos de GET /proxy-regions/countries.

Para escolher a região em POST /inbox/create ou POST /inbox/connect:

  1. proxy.country: o país (br).
  2. proxy.city: o value da cidade escolhida.
  3. proxy.state: o state da cidade, quando ela tem; sem state, mande só país e cidade.

A api confere a combinação e responde 400 se faltar algo.

Autenticação

[]

{}

Parâmetros

[
  {
    "in": "query",
    "name": "country",
    "required": false,
    "schema": {
      "type": "string",
      "pattern": "^[a-z]{2}
quot;,
      "default": "br"
    },
    "description": "País, ISO alpha-2 minúsculo. Padrão `br`."
  },
  {
    "in": "query",
    "name": "state",
    "required": false,
    "schema": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,16}
quot;
    },
    "description": "Só as cidades deste estado, quando o país tem (`sp`, `rj`, `mg`...)."
  },
  {
    "in": "query",
    "name": "search",
    "required": false,
    "schema": {
      "type": "string"
    },
    "description": "Busca parcial pelo nome, sem diferenciar acento nem maiúsculas."
  }
]

Respostas

{
  "200": {
    "description": "Lista de cidades disponíveis",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "country": {
              "type": "string",
              "example": "br",
              "description": "O país consultado."
            },
            "state": {
              "type": "string",
              "description": "O estado do filtro; só quando `state` foi enviado.",
              "example": "sp"
            },
            "cities": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "string",
                    "description": "O valor a enviar em `proxy.city`.",
                    "example": "saopaulo"
                  },
                  "label": {
                    "type": "string",
                    "description": "Nome da cidade, para exibir.",
                    "example": "São Paulo"
                  },
                  "state": {
                    "type": "string",
                    "description": "Estado da cidade, quando há: o valor a enviar em `proxy.state`.",
                    "example": "sp"
                  },
                  "state_label": {
                    "type": "string",
                    "description": "Nome do estado, para exibir, quando há.",
                    "example": "São Paulo"
                  },
                  "raw_city": {
                    "type": "string",
                    "description": "Para diagnóstico. Não envie: use `value`.",
                    "example": "sao_paulo"
                  }
                }
              },
              "description": "As cidades, já filtradas por `state` e `search`."
            }
          }
        },
        "examples": {
          "brasil_enriquecido": {
            "summary": "Cidade brasileira enriquecida",
            "value": {
              "country": "br",
              "state": "sp",
              "cities": [
                {
                  "value": "campinas",
                  "label": "Campinas",
                  "state": "sp",
                  "state_label": "São Paulo",
                  "raw_city": "campinas"
                },
                {
                  "value": "saopaulo",
                  "label": "São Paulo",
                  "state": "sp",
                  "state_label": "São Paulo",
                  "raw_city": "sao_paulo"
                }
              ]
            }
          },
          "pais_sem_enriquecimento": {
            "summary": "Cidade fora do Brasil",
            "value": {
              "country": "us",
              "cities": [
                {
                  "value": "losangeles",
                  "label": "Los Angeles"
                }
              ]
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "`invalid_request`: `country` não é ISO alpha-2, ou `state` inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "country deve ser o código ISO de duas letras (br, us...)."
        }
      }
    }
  },
  "429": {
    "description": "`rate_limited`: muitas consultas deste IP; espere o tempo do header `Retry-After`.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "rate_limited",
          "message": "Muitas consultas; espere o tempo do Retry-After."
        }
      }
    }
  },
  "500": {
    "description": "`internal_error`: falha inesperada ao ler a lista.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "internal_error",
          "message": "Falha ao ler as cidades."
        }
      }
    }
  },
  "501": {
    "$ref": "#/components/responses/CloudUnsupported"
  },
  "503": {
    "description": "`unavailable`: a escolha de região não está disponível neste servidor, ou a lista de cidades está fora do ar agora; tente de novo depois.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unavailable",
          "message": "A lista de cidades está fora do ar agora; tente de novo depois."
        }
      }
    }
  }
}

Estado: Disponível

Formato: o mesmo da API v1 (caminho, campos e erros no padrão antigo).

Compatibilidade de canais

CanalCompatívelObservação
WhatsApp (Web)Sim
WhatsApp (API oficial)NãoSó no WhatsApp Web.
InstagramNão
MessengerNão
TelegramNão

Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em GET /events): o resultado vem só na resposta.

Antes e depois (uazapi → Orkesio)

Na uazapi: GET /proxy-managed/cities.

  • Sem mudança no formato: o da uazapi; só o caminho (/proxy-regions/cities).

#/components/schemas/OrkesioError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}

#/components/responses/CloudUnsupported

{
  "description": "`unsupported_for_channel`: o canal da inbox não atende esta rota (rota só do WhatsApp Web numa inbox oficial, ou rota da API oficial numa inbox do WhatsApp Web). O canal está em `Inbox.channel`.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "unsupported_for_channel",
        "message": "Esta rota não está disponível no canal da inbox."
      }
    }
  }
}

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi