API do Demander - Cidades

Este artigo faz parte da documentação da API de Integração REST.

Documentação para consultar, inserir, atualizar e excluir cidades.

Consulta

Lista as cidades da empresa. Sem filtro, considera dataAlteracao dos últimos 6 meses.

Rota: {host}/public/v1/cidades?pagina={pagina}&limite={limite}&filtroDataAlteracao={data}&operadorFiltro={operador}
Método: GET

Cuidado

Paginação

• pagina — base 1 (padrão 1)
• limite — padrão 100, máximo 500

Filtros

• filtroDataAlteracao — formato Y-m-d
• operadorFiltro (opcional) — <, >, =, <=, >= (padrão >=)

Retorno:

{
  "cidades": [
    {
      "codigo": 54,
      "descricao": "LAJEADO",
      "uf": "RS",
      "codigoPais": "BR",
      "ativo": 1,
      "dataAlteracao": "2026-07-24 10:00:00",
      "codigoIbge": 4311403
    }
  ]
}

Inserir ou atualizar

POST upsert pela chave codigo.

Rota: {host}/public/v1/cidades
Método: POST
Body: json

Propriedade	Tipo	Tamanho	Obrigatório	Descrição
codigo	int		✓	Código da cidade. Identificador único usado para inserir ou atualizar (upsert).
descricao	string	100	✓	Nome da cidade.
uf	string	2	✓	UF do estado (ex.: RS).
codigoPais	string	2		Código ISO-2 do país. Padrão na inclusão: BR.
codigoIbge	int	11		Código do município na base do IBGE. A consulta de CEP e CNPJ usa primeiro este campo para localizar a cidade.
ativo	int			Valores: 0 ou 1. Padrão na inclusão: 1.

Cuidado

Inclusão

• É necessário enviar todos os atributos que são obrigatórios. Retorno 201.

Atualização

• Apenas o atributo codigo é obrigatório. Retorno 200.

Body:

{
  "codigo": 54,
  "descricao": "LAJEADO",
  "uf": "RS",
  "codigoPais": "BR",
  "ativo": 1,
  "codigoIbge": 4311403
}

Retorno:

{
  "codigo": 54,
  "descricao": "LAJEADO",
  "uf": "RS",
  "codigoPais": "BR",
  "ativo": 1,
  "dataAlteracao": "2026-07-24 10:00:00",
  "codigoIbge": 4311403
}

Excluir

Remove a cidade.

Rota: {host}/public/v1/cidades?codigo={codigo}
Método: DELETE

Retorno:

{
  "mensagem": "Registro excluído com sucesso."
}

Criar todas as cidades do IBGE

Copia as cidades do IBGE para a empresa, com codigoPais = BR. Cada cidade inserida recebe o código do município no codigo e no codigoIbge.

Rota: {host}/public/v1/cidades/criar-todas-cidades-do-ibge
Método: POST

Cuidado

Atenção

• Se a empresa já tiver 5000 ou mais cidades, a operação não é executada.

Retorno:

{
  "mensagem": "Cidades do IBGE criadas com sucesso.",
  "quantidadeInserida": 5570
}