Bairros

Lista paginada, consulta, criação, alteração e exclusão de bairros de uma cidade, com faixa de CEP.

Bairro é o último nível: pertence a uma cidade e pode guardar a faixa de CEP que ele cobre. As zonas de áreas de frete e imposto podem apontar para bairros. O id é um UUID. Exige o privilégio manage_locations.

Listar bairros

GET/api/v1/admin/locations/districtsAdmin

Lista bairros com paginação

Ordenados pelo nome. Quando city_id é informado e a cidade ainda não tem bairros em uma loja migrada, a plataforma os copia do catálogo de referência antes de responder.

Parâmetros de consulta

city_iduuid

Somente bairros desta cidade. Valor que não é UUID retorna 400.

searchstring

Texto contido no nome do bairro, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. O máximo é 3000: valores maiores são reduzidos a 3000, valores menores que 1 voltam a 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/locations/districts?city_id=547ec948-c513-4936-b039-d2f673c91fa0&per_page=100" \
  -H "Authorization: Bearer $TOKEN"

200Bairros retornados

json

{
  "districts": [
    {
      "id": "8aa33183-c6a2-4554-8919-34957c718de6",
      "city_id": "547ec948-c513-4936-b039-d2f673c91fa0",
      "city_name": "Boa Vista",
      "name": "13 de Setembro",
      "cep_range_start": "69308000",
      "cep_range_end": "69308470"
    }
  ],
  "total": 74426,
  "page": 1,
  "per_page": 50,
  "total_pages": 1489
}

Campos da resposta

districts[].iduuid

Identificador do bairro.

districts[].city_iduuid

Cidade dona.

districts[].city_namestring

Nome da cidade.

districts[].namestring

Nome do bairro.

districts[].cep_range_startstring

Início da faixa de CEP, 8 dígitos sem hífen. Pode ser vazio.

districts[].cep_range_endstring

Fim da faixa de CEP. Pode ser vazio.

totalinteger

Total de bairros que atendem ao filtro.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar bairro

GET/api/v1/admin/locations/districts/{id}Admin

Consulta um bairro pelo id

Parâmetros de caminho

iduuidobrigatório

Id do bairro. Valor que não é UUID retorna 400.

A resposta 200 é um único objeto no formato de districts[].

Criar bairro

POST/api/v1/admin/locations/districtsAdmin

Cadastra um bairro

A faixa de CEP não é validada pelo cadastro: grave 8 dígitos sem hífen, como o catálogo.

Corpo da requisição

city_iduuidobrigatório

Cidade dona.

namestringobrigatório

Nome do bairro.

cep_range_startstring

Início da faixa de CEP.

cep_range_endstring

Fim da faixa de CEP.

201Bairro criado

json

{
  "id": "5f0e8b52-2f61-4a63-8c64-0c9a3d8d7b10",
  "city_id": "547ec948-c513-4936-b039-d2f673c91fa0",
  "city_name": "Boa Vista",
  "name": "Bairro Exemplo",
  "cep_range_start": "69300000",
  "cep_range_end": "69300999"
}

Alterar bairro

PUT/api/v1/admin/locations/districts/{id}Admin

Altera nome ou faixa de CEP de um bairro

Alteração parcial. A cidade do bairro não pode ser trocada.

Parâmetros de caminho

iduuidobrigatório

Id do bairro.

Corpo da requisição

namestring

Novo nome.

cep_range_startstring

Novo início da faixa de CEP.

cep_range_endstring

Novo fim da faixa de CEP.

A resposta 200 é o bairro atualizado.

Excluir bairro

DELETE/api/v1/admin/locations/districts/{id}Admin

Exclui um bairro

Parâmetros de caminho

iduuidobrigatório

Id do bairro.

200Bairro excluído

json

{ "message": "district deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; `city_id` ou `name` ausente; `city_id` ou `id` que não é UUID	`{"error":"city_id and name are required"}` ou `{"error":"invalid city_id","detail":"city_id must be a valid UUID"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Id inexistente (consultar, alterar)	`{"error":"district not found"}`
500	`city_id` inexistente na criação, id inválido em alterar/excluir, ou excluir id que não existe	`{"error":"failed to delete district","detail":"district ... not found"}`

Veja também

API atual/Referência completa/Locais

Bairros

Lista paginada, consulta, criação, alteração e exclusão de bairros de uma cidade, com faixa de CEP.

Listar bairros

GET/api/v1/admin/locations/districtsAdmin

Lista bairros com paginação

Ordenados pelo nome. Quando city_id é informado e a cidade ainda não tem bairros em uma loja migrada, a plataforma os copia do catálogo de referência antes de responder.

Parâmetros de consulta

city_iduuid

Somente bairros desta cidade. Valor que não é UUID retorna 400.

searchstring

Texto contido no nome do bairro, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. O máximo é 3000: valores maiores são reduzidos a 3000, valores menores que 1 voltam a 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/locations/districts?city_id=547ec948-c513-4936-b039-d2f673c91fa0&per_page=100" \
  -H "Authorization: Bearer $TOKEN"

200Bairros retornados

json

{
  "districts": [
    {
      "id": "8aa33183-c6a2-4554-8919-34957c718de6",
      "city_id": "547ec948-c513-4936-b039-d2f673c91fa0",
      "city_name": "Boa Vista",
      "name": "13 de Setembro",
      "cep_range_start": "69308000",
      "cep_range_end": "69308470"
    }
  ],
  "total": 74426,
  "page": 1,
  "per_page": 50,
  "total_pages": 1489
}

Campos da resposta

districts[].iduuid

Identificador do bairro.

districts[].city_iduuid

Cidade dona.

districts[].city_namestring

Nome da cidade.

districts[].namestring

Nome do bairro.

districts[].cep_range_startstring

Início da faixa de CEP, 8 dígitos sem hífen. Pode ser vazio.

districts[].cep_range_endstring

Fim da faixa de CEP. Pode ser vazio.

totalinteger

Total de bairros que atendem ao filtro.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar bairro

GET/api/v1/admin/locations/districts/{id}Admin

Consulta um bairro pelo id

Parâmetros de caminho

iduuidobrigatório

Id do bairro. Valor que não é UUID retorna 400.

A resposta 200 é um único objeto no formato de districts[].

Criar bairro

POST/api/v1/admin/locations/districtsAdmin

Cadastra um bairro

A faixa de CEP não é validada pelo cadastro: grave 8 dígitos sem hífen, como o catálogo.

Corpo da requisição

city_iduuidobrigatório

Cidade dona.

namestringobrigatório

Nome do bairro.

cep_range_startstring

Início da faixa de CEP.

cep_range_endstring

Fim da faixa de CEP.

201Bairro criado

json

{
  "id": "5f0e8b52-2f61-4a63-8c64-0c9a3d8d7b10",
  "city_id": "547ec948-c513-4936-b039-d2f673c91fa0",
  "city_name": "Boa Vista",
  "name": "Bairro Exemplo",
  "cep_range_start": "69300000",
  "cep_range_end": "69300999"
}

Alterar bairro

PUT/api/v1/admin/locations/districts/{id}Admin

Altera nome ou faixa de CEP de um bairro

Alteração parcial. A cidade do bairro não pode ser trocada.

Parâmetros de caminho

iduuidobrigatório

Id do bairro.

Corpo da requisição

namestring

Novo nome.

cep_range_startstring

Novo início da faixa de CEP.

cep_range_endstring

Novo fim da faixa de CEP.

A resposta 200 é o bairro atualizado.

Excluir bairro

DELETE/api/v1/admin/locations/districts/{id}Admin

Exclui um bairro

Parâmetros de caminho

iduuidobrigatório

Id do bairro.

200Bairro excluído

json

{ "message": "district deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; `city_id` ou `name` ausente; `city_id` ou `id` que não é UUID	`{"error":"city_id and name are required"}` ou `{"error":"invalid city_id","detail":"city_id must be a valid UUID"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Id inexistente (consultar, alterar)	`{"error":"district not found"}`
500	`city_id` inexistente na criação, id inválido em alterar/excluir, ou excluir id que não existe	`{"error":"failed to delete district","detail":"district ... not found"}`