Cidades

Consulte as cidades de um estado específico.

informação

Para obter o ID do estado necessário para consultar as cidades, utilize o endpoint /catalog/state que retorna a lista de estados com seus respectivos IDs.

Endpoint

GET /catalog/city/{state_id}
GET /catalog/city/{state_id}/{id}

Método

GET

Parâmetros de URL

Parâmetro	Tipo	Descrição
state_id	integer	ID do estado (obtido através do endpoint /catalog/state)
id	integer	ID da cidade (opcional, para detalhe)

Autenticação

Este endpoint requer autenticação via JWT. Inclua o token no header:

Authorization: Bearer {access_token}

Exemplo de Resposta

Lista de Cidades

Status Code: 200 OK

[
  {
    "id": 1,
    "name": "São Paulo",
    "state_id": 1,
    "state_abbreviation": "SP",
    "is_capital": true
  },
  {
    "id": 2,
    "name": "Campinas",
    "state_id": 1,
    "state_abbreviation": "SP",
    "is_capital": false
  },
  {
    "id": 3,
    "name": "Santos",
    "state_id": 1,
    "state_abbreviation": "SP",
    "is_capital": false
  },
  {
    "id": 4,
    "name": "Ribeirão Preto",
    "state_id": 1,
    "state_abbreviation": "SP",
    "is_capital": false
  }
]

Detalhe de uma Cidade

Status Code: 200 OK

{
  "id": 1,
  "name": "São Paulo",
  "state_id": 1,
  "state_abbreviation": "SP",
  "is_capital": true
}

Estrutura de Dados

A resposta é um array de objetos (lista) ou um objeto único (detalhe), onde cada objeto contém:

Campo	Tipo	Descrição
id	integer	Identificador único da cidade
name	string	Nome da cidade
state_id	integer	ID do estado ao qual a cidade pertence
state_abbreviation	string	Sigla do estado (UF)
is_capital	boolean	Indica se a cidade é capital do estado

Exemplo de Uso

Passo 1: Obter o ID do estado

Primeiro, consulte o endpoint de estados para obter o ID:

GET /catalog/state

Resposta:

[
  {
    "id": 1,
    "name": "São Paulo",
    "abbreviation": "SP"
  }
]

Passo 2: Consultar cidades do estado

Com o ID do estado (exemplo: 1), consulte as cidades:

GET /catalog/city/1

Comportamento

• Se o state_id fornecido não existir, a resposta será uma lista vazia []
• Se o state_id não for um número válido, a resposta será uma lista vazia []
• Todas as cidades retornadas pertencem ao estado especificado no state_id

Possíveis Retornos de Erro

401 Unauthorized

Retornado quando o token de autenticação não foi fornecido ou é inválido.

{
  "detail": "As credenciais de autenticação não foram fornecidas."
}

ou

{
  "detail": "Token inválido ou expirado."
}

403 Forbidden

Retornado quando o usuário autenticado não tem permissão para acessar este recurso.

{
  "detail": "Você não tem permissão para executar essa ação."
}

404 Not Found

Retornado quando uma cidade específica não é encontrada (ao acessar /catalog/city/{state_id}/{id}).

{
  "detail": "Não encontrado."
}

405 Method Not Allowed

Retornado quando um método HTTP não permitido é utilizado (ex: DELETE, POST, PUT, PATCH).

{
  "detail": "Método \"DELETE\" não é permitido."
}