API CEP (Versão 2)

Introdução

Esta API permite consultar os dados de um endereço a partir de um CEP.

API Consultar CEP (Consultar pelo CEP)

Consulta detalhes de um CEP específico.

Endpoint

GET https://consultar.io/api/v2/cep/consultar

Requisição

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
cep	Texto	Sim	CEP do endereço (8 dígitos)	12345678

Resposta

Campo	Tipo	Descrição	Exemplo
cep	Texto	CEP do endereço sem formatação	"12345678"
cep_formatado	Texto	CEP do endereço com formatação	"12345-678"
tipo	Texto	Tipo de endereço	"Logradouro"
caixa_postal	Booleano	Indicador para caixa postal	false
nome	Texto	Nome do endereço (se aplicável)	null
nome_abreviado	Texto	Nome abreviado do endereço (se aplicável)	null
tipo_logradouro	Texto	Tipo de logradouro (se aplicável)	"Rua"
nome_logradouro	Texto	Nome do logradouro (se aplicável)	"Exemplo"
logradouro	Texto	Logradouro do endereço (se aplicável)	"Rua Exemplo"
complemento	Texto	Complemento do endereço (se aplicável)	null
bairro	Texto	Bairro, distrito ou povoado do endereço (se aplicável)	"Exemplo"
bairro_abreviado	Texto	Bairro abreviado do endereço (se aplicável)	"Exemplo"
localidade	Texto	Município, distrito ou povoado do endereço	"São Paulo"
uf	Texto	Unidade Federativa do endereço	"SP"

Exemplos

Exemplo de Requisição (cURL)

curl -X GET 'https://consultar.io/api/v2/cep/consultar?cep=12345678' -H 'Authorization: Token <seu-token>'

Exemplo de Resposta de Sucesso (200)

{
  "cep": "12345678",
  "cep_formatado": "12345-678",
  "tipo": "Logradouro",
  "caixa_postal": false,
  "nome": null,
  "nome_abreviado": null,
  "tipo_logradouro": "Rua",
  "nome_logradouro": "Exemplo",
  "logradouro": "Rua Exemplo",
  "complemento": null,
  "bairro": "Exemplo",
  "bairro_abreviado": "Exemplo",
  "localidade": "São Paulo",
  "uf": "SP"
}

Exemplo de Resposta de Erro (404)

{
  "error": "NAO_ENCONTRADO",
  "message": "Nenhum registro foi encontrado para os parâmetros informados."
}

Observações

• O CEP pode ser informado com ou sem hífen

API Buscar CEP (Buscar pelo Endereço)

Consulta detalhes de um CEP específico.

Endpoint

GET https://consultar.io/api/v2/cep/buscar

Requisição

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
logradouro	Texto	Não	Logradouro do endereço	"Rua Exemplo"
localidade	Texto	Sim	Município do endereço	"São Paulo"
uf	Texto	Sim	Unidade Federativa do endereço	"SP"

Resposta

Campo	Tipo	Descrição	Exemplo
cep	Texto	CEP do endereço sem formatação	"12345678"
cep_formatado	Texto	CEP do endereço com formatação	"12345-678"
tipo	Texto	Tipo de endereço	"Logradouro"
caixa_postal	Booleano	Indicador se é caixa postal	false
nome	Texto	Nome do endereço (se aplicável)	null
nome_abreviado	Texto	Nome abreviado do endereço (se aplicável)	null
tipo_logradouro	Texto	Tipo de logradouro (se aplicável)	"Rua"
nome_logradouro	Texto	Nome do logradouro (se aplicável)	"Exemplo"
logradouro	Texto	Logradouro do endereço (se aplicável)	"Rua Exemplo"
complemento	Texto	Complemento do endereço (se aplicável)	null
bairro	Texto	Bairro, distrito ou povoado do endereço (se aplicável)	"Exemplo"
bairro_abreviado	Texto	Bairro abreviado do endereço (se aplicável)	"Exemplo"
localidade	Texto	Município, distrito ou povoado do endereço	"São Paulo"
uf	Texto	Unidade Federativa do endereço	"SP"

Erros

Código	Erro
400	REQUISICAO_INVALIDA
403	PLANO_INATIVO
403	CREDITOS_INSUFICIENTES
404	NAO_ENCONTRADO
500	ERRO
500	ERRO_INTERNO
503	SERVICO_INDISPONIVEL

Exemplos

Exemplo de Requisição (cURL)

curl -X GET 'https://consultar.io/api/v2/cep/buscar?logradouro=Rua%20Exemplo&localidade=S%C3%A3o%20Paulo&uf=SP' -H 'Authorization: Token <seu-token>'

Exemplo de Resposta de Sucesso (200)

[
  {
    "cep": "12345678",
    "cep_formatado": "12345-678",
    "tipo": "Logradouro",
    "caixa_postal": false,
    "nome": null,
    "nome_abreviado": null,
    "tipo_logradouro": "Rua",
    "nome_logradouro": "Exemplo",
    "logradouro": "Rua Exemplo",
    "complemento": null,
    "bairro": "Exemplo",
    "bairro_abreviado": "Exemplo",
    "localidade": "São Paulo",
    "uf": "SP"
  }
]

Exemplo de Resposta de Erro (404)

{
  "error": "NAO_ENCONTRADO",
  "message": "Nenhum registro foi encontrado para os parâmetros informados."
}

Códigos de Status HTTP

Código	Erro (error)	Descrição
400	REQUISICAO_INVALIDA	Veja a mensagem de erro (message) para mais detalhes.
403	PLANO_INATIVO	Plano inativo. Faça uma Recarga.
403	CREDITOS_INSUFICIENTES	Créditos insuficientes. Faça uma Recarga.
404	NAO_ENCONTRADO	Registro não encontrado.
500	ERRO	Veja a mensagem de erro (message) para mais detalhes.
500	ERRO_INTERNO	Ocorreu um erro inesperado no nosso sistema.
503	SERVICO_INDISPONIVEL	Veja a mensagem de erro (message) para mais detalhes.

Limites e Considerações

• As requisições "Consultar CEP" não consomem créditos (por tempo indeterminado)
• Cada requisição "Buscar CEP" consome R$ 0,05 dos créditos
• Somente as respostas com os códigos de status 200 e 404 consomem créditos
• Limite máximo de 1.000 resultados na requisição "Buscar CEP"
• Todas as requisições são registradas no histórico de transações
• O token de autenticação deve ser mantido em segurança
• Em caso de comprometimento do token, entre em contato com o Suporte