Ir para o conteúdo

Documentação - Consultar.IO

API CEP - Consultar CEP e Buscar Endereço

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 /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"`

Erros

Código HTTP	Erro	Mensagem
`400`	`REQUISICAO_INVALIDA`
`403`	`PLANO_INATIVO`	`Plano inativo para realizar consultas.`
`403`	`CREDITOS_INSUFICIENTES`	`Sem créditos suficientes para consulta.`
`404`	`NAO_ENCONTRADO`	`Nenhum registro encontrado com os parâmetros informados.`

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 /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 HTTP	Erro	Mensagem
`400`	`REQUISICAO_INVALIDA`
`403`	`PLANO_INATIVO`	`Plano inativo para realizar consultas.`
`403`	`CREDITOS_INSUFICIENTES`	`Sem créditos suficientes para consulta.`
`404`	`NAO_ENCONTRADO`	`Nenhum registro encontrado com os parâmetros informados.`

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."
}

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
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