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.

Timeout

A nossa API não retorna timeout. Caso seja necessário configurar um timeout na implantação, recomendamos utilizar 300 segundos.

Verifique o timeout padrão da sua implantação, pois ele pode ser menor do que o tempo de resposta da API.

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