Locais

Todo endereço da plataforma aponta para uma hierarquia geográfica: país > estado > cidade > bairro. Essa hierarquia é um cadastro do próprio tenant (a loja), editável pelo administrador. Ela alimenta os seletores de endereço do checkout, as zonas de áreas de frete e imposto e a ligação fiscal por código IBGE. Uma loja nova já nasce com o Brasil completo (27 estados, municípios e cerca de 74 mil bairros), então na maioria das vezes você só lê esses dados.

Como funciona

Os níveis dependem uns dos outros. Para cadastrar um bairro novo, a cidade precisa existir; para cadastrar a cidade, o estado; e assim por diante.

Um fluxo típico de integração, por exemplo para atender uma loja que opera em outro país:

1. Cadastre o país
   POST /api/v1/admin/locations/countries com o código ISO de 2 ou 3 letras.
2. Cadastre os estados
   POST /api/v1/admin/locations/states informando country_code.
3. Cadastre as cidades
   POST /api/v1/admin/locations/cities informando o state_id (UUID devolvido no passo anterior).
4. Cadastre os bairros (opcional)
   POST /api/v1/admin/locations/districts informando o city_id e, se quiser, a faixa de CEP do bairro.

Conceitos-chave

Identificadores

Código IBGE

O código IBGE de 7 dígitos liga a cidade ao cálculo de ISS e às integrações fiscais. Ele é opcional, mas quando informado precisa ter exatamente 7 dígitos e ser único na loja.

Status do país

O país tem o campo status, que aceita a letra (A ativo, D desativado) ou a palavra longa (active, disabled): a API normaliza para a letra antes de gravar. Estado, cidade e bairro não têm status.

Bairros preenchidos sob demanda

Em lojas migradas que receberam estados e cidades mas nenhum bairro, a primeira listagem de bairros filtrada por city_id copia automaticamente os bairros daquela cidade do catálogo de referência da plataforma. Se a cópia falhar, a lista volta vazia em vez de erro.

Endpoints

Erros comuns

• Apagar de cima para baixo. Excluir um país com estados, um estado com cidades ou uma cidade com bairros retorna 409. Apague os filhos primeiro.
• Enviar UUID malformado. Na listagem de bairros e em GET /districts/{id} o erro é um 400 limpo; nos demais caminhos de cidade e estado ele vira 500 com a descrição no campo detail. Valide os ids antes de enviar.
• Código IBGE com menos de 7 dígitos. Retorna 400 ibge_code must be a 7-digit number.
• Esperar 404 ao excluir algo que não existe. DELETE de id inexistente retorna 500 (detail diz que o registro não foi encontrado), não 404.
• Pedir per_page maior que o teto. Cidades limitam em 1000 e bairros em 3000; acima disso a API usa o teto, sem erro.
• Esquecer que o PUT é parcial. Só os campos enviados mudam; campos omitidos são mantidos.

Próximos passos