Introdução
Documentação oficial da ZipFinder API
Bem-vindo à documentação oficial da ZipFinder API. Nossa API RESTful oferece validação de endereços, consulta de CNPJ e geocodificação com alta disponibilidade e latência reduzida, utilizando fontes atualizadas para consulta de dados no Brasil.
Autenticação
Todas as requisições para a ZipFinder API, exceto o health check, devem ser
autenticadas com sua API key.
Use o header HTTP x-api-key
para acessar os endpoints públicos. As chaves de produção seguem o padrão
zfp_....
Header Necessário
x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259
Health / Status
Verifique o status geral da API sem autenticação. Use este endpoint em rotinas de monitoramento e disponibilidade.
https://api.zipfinder.com.br/api/health
Exemplo curl
curl --request GET \ --url https://api.zipfinder.com.br/api/health
JSON response
{
"status": "ok",
"timestamp": "2026-05-20T17:45:52.392Z"
}
Consulta de CNPJ
Consulte os dados cadastrais e de endereçamento de uma empresa a partir de um CNPJ
brasileiro com 14 dígitos. O endpoint público usa o host
https://api.zipfinder.com.br/api.
https://api.zipfinder.com.br/api/v1/companies/22685030000111
Exemplo curl
curl --request GET \ --url https://api.zipfinder.com.br/api/v1/companies/22685030000111 \ --header "x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259"
JSON response
{
"Exists": true,
"Cnpj": "22685030000111",
"LegalName": "ZIPFINDER TECNOLOGIA LTDA",
"TradeName": "ZIPFINDER",
"Address": {
"Street": "Rua Exemplo",
"Number": "123",
"Complement": null,
"Neighborhood": "Centro",
"City": "Sao Paulo",
"State": "SP",
"ZipCode": "01001000",
"CountryCode": "BR"
},
"Phone": "1130000000",
"Email": "contato@zipfinder.com.br",
"Latitude": -23.55052,
"Longitude": -46.633308,
"GeoSource": "ibge",
"GeoConfidence": 0.98,
"GeoLastUpdated": "2026-05-21T00:00:00.000Z",
"Source": "provider",
"Stale": false,
"LastUpdated": "2026-05-21T00:00:00.000Z"
}
403 PLAN_NOT_ALLOWED.
Busca CEP
Consulte um CEP retornando país, logradouro, bairro, cidade, estado, código IBGE,
latitude, longitude, origem da informação e data de atualização.
Observação: a geolocalização retornada é aproximada, pois a consulta não
inclui o
número do endereço. Para coordenadas precisas (nível de ponto), utilize o endpoint
Detalhe por CEP + Número.
https://api.zipfinder.com.br/api/v1/postal-codes/04134020
Exemplo curl
curl --request GET \ --url https://api.zipfinder.com.br/api/v1/postal-codes/04134020 \ --header "x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259"
JSON response
{
"IsoAlpha2Country": "BR",
"IsoAlpha3Country": "BRA",
"ZipCode": "04134-020",
"Street": "Rua das Uvaias",
"TypeStreet": "Rua",
"NameStreet": "das Uvaias",
"Neighborhood": "Saúde",
"City": "São Paulo",
"State": "SP",
"IbgeCode": "3550308",
"Latitude": -23.615189,
"Longitude": -46.633281,
"Source": "Correios do Brasil",
"LastUpdated": "2026-04-22T19:10:42.000Z"
}
Detalhe por CEP + Número
Consulte o endereço detalhado a partir do CEP e do prefixo do número. A busca usa a base consolidada do IBGE, ordena por maior ocorrência e confiança e retorna apenas um resultado.
https://api.zipfinder.com.br/api/v1/postal-codes/69309630/details?number=503
number
deve receber o número do endereço para aumentar a precisão da geocodificação.
Exemplo curl
curl --request GET \ --url "https://api.zipfinder.com.br/api/v1/postal-codes/69309630/details?number=503" \ --header "x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259"
JSON response
{
"ZipCode": "69309-630",
"Number": "503",
"Street": "Rua Professor Agnelo Bitencourt",
"TypeStreet": "Rua",
"NameStreet": "Professor Agnelo Bitencourt",
"Neighborhood": "Centro",
"City": "Boa Vista",
"State": "RR",
"IbgeCode": "1400100",
"Latitude": 2.823509,
"Longitude": -60.675833,
"Confidence": 0.9821,
"Source": "IBGE",
"LastUpdated": "2026-04-22T19:10:42.000Z"
}
Estados API
Liste os estados disponíveis para um país usando o código ISO alpha-3, como
BRA.
https://api.zipfinder.com.br/api/v1/countries/BRA/states
Exemplo curl
curl --request GET \ --url https://api.zipfinder.com.br/api/v1/countries/BRA/states \ --header "x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259"
JSON response
{
"Country": {
"IsoAlpha2": "BR",
"IsoAlpha3": "BRA",
"Name": "Brasil"
},
"States": [
{ "Code": "SP", "Name": "Sao Paulo" },
{ "Code": "RJ", "Name": "Rio de Janeiro" }
]
}
Cidades API
Liste as cidades de um estado dentro de um país para compor formulários, filtros e fluxos de preenchimento assistido.
https://api.zipfinder.com.br/api/v1/countries/BRA/states/SP/cities
Exemplo curl
curl --request GET \ --url https://api.zipfinder.com.br/api/v1/countries/BRA/states/SP/cities \ --header "x-api-key: zfp_077bc31642bf65799e54c98365f365e4b22ce32e2b1ae8f31da28bb5d6e39259"
JSON response
{
"Country": {
"IsoAlpha2": "BR",
"IsoAlpha3": "BRA",
"Name": "Brasil"
},
"State": {
"Code": "SP",
"Name": "Sao Paulo"
},
"Cities": ["Campinas", "Sao Paulo"]
}
Uso e Limites
O plano Free inclui 3.000 requisições por mês. Quando o volume mensal do
plano é excedido, a API retorna 429 RATE_LIMIT_EXCEEDED.
Para volumes maiores, contrate um plano pago.
Para agentes de AI
Use os arquivos abaixo como fonte de verdade para gerar integrações, clients e exemplos de servidor. O contrato OpenAPI define rotas, parâmetros, schemas e erros; a versão Markdown traz exemplos prontos para leitura por agentes, incluindo CEP e CNPJ.
/openapi.json,
use ZIPFINDER_API_KEY
no servidor e envie o header x-api-key
em todos os endpoints autenticados. Para empresas, use o endpoint de CNPJ
documentado acima.