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.

Consulta por CEP, CEP + número e CNPJ
Estados, cidades e status da API
Autenticação por API key
Controle de uso por plano
A

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
Crie sua conta pelo site, gere a chave no painel e envie-a em todas as requisições autenticadas. Em integrações de produção, guarde a chave em variáveis de ambiente no servidor e não a exponha em frontends públicos. O endpoint de CNPJ está disponível em todos os planos, do Free ao Enterprise.
H

Health / Status

Verifique o status geral da API sem autenticação. Use este endpoint em rotinas de monitoramento e disponibilidade.

GET 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"
}
C

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.

GET 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": "SALA 4",
    "Neighborhood": "CENTRO",
    "City": "SAO PAULO",
    "State": "SP",
    "ZipCode": "01001-000",
    "CountryCode": "BR"
  },
  "Phone": "(11) 30000000",
  "Email": "contato@zipfinder.com.br",
  "Latitude": -23.55052,
  "Longitude": -46.633308,
  "GeoSource": "ibge",
  "GeoConfidence": 0.98,
  "GeoLastUpdated": "2026-05-21T00:00:00.000Z",
  "Source": "rf_base",
  "Stale": false,
  "LastUpdated": null,
  "MatrizFilial": "MATRIZ",
  "RegistrationStatus": "ATIVA",
  "RegistrationStatusDate": "2015-06-22",
  "RegistrationStatusReason": null,
  "SpecialStatus": null,
  "SpecialStatusDate": null,
  "OpeningDate": "2015-06-22",
  "LegalNatureCode": "2062",
  "LegalNature": "Sociedade Empresaria Limitada",
  "CompanySize": "MICRO EMPRESA",
  "CapitalSocial": 10000,
  "FederativeEntity": null,
  "MainActivity": {
    "Code": "6201-5/01",
    "Text": "Desenvolvimento de programas de computador sob encomenda"
  },
  "SecondaryActivities": [
    {
      "Code": "6202-3/00",
      "Text": "Desenvolvimento e licenciamento de programas de computador customizaveis"
    }
  ],
  "Partners": [
    {
      "IdentifierType": "2",
      "Name": "FULANO DE TAL",
      "Document": "***456789**",
      "QualificationCode": "49",
      "Qualification": "Socio-Administrador",
      "EntryDate": "2015-06-22",
      "AgeRange": "41 a 50 anos"
    }
  ],
  "Simples": { "Optante": true, "OptionDate": "2015-07-01", "ExclusionDate": null },
  "Mei": { "Optante": false, "OptionDate": null, "ExclusionDate": null }
}

Fonte dos dados e campos estendidos

Os dados da empresa vêm primariamente da base de dados abertos da Receita Federal. O campo Source indica a origem da resposta:

  • rf_base — base da Receita Federal (fonte primária). Retorna o conjunto completo de campos cadastrais estendidos.
  • cache — resultado previamente enriquecido servido de cache.
  • provider — provedor externo, usado como fallback quando o CNPJ não está na base da Receita.

Os campos cadastrais estendidos abaixo são garantidos quando Source é rf_base. No fallback cache/provider podem vir nulos ou ausentes.

Campo Tipo Descrição
MatrizFilialstringMATRIZ ou FILIAL.
RegistrationStatusstringSituação cadastral: ATIVA, BAIXADA, SUSPENSA, INAPTA, NULA.
RegistrationStatusDatestringData da situação cadastral (YYYY-MM-DD).
RegistrationStatusReasonstringMotivo da situação cadastral, quando aplicável.
SpecialStatus / SpecialStatusDatestringSituação especial e sua data, quando aplicável.
OpeningDatestringData de início de atividade (YYYY-MM-DD).
LegalNatureCode / LegalNaturestringCódigo e descrição da natureza jurídica.
CompanySizestringPorte: MICRO EMPRESA, EMPRESA DE PEQUENO PORTE, DEMAIS.
CapitalSocialnumberCapital social em BRL.
FederativeEntitystringEnte federativo responsável (órgãos públicos).
MainActivityobjectCNAE principal { Code, Text }, com Code no formato 9999-9/99.
SecondaryActivitiesarrayCNAEs secundárias, cada uma { Code, Text }.
PartnersarrayQuadro societário (QSA): IdentifierType (1=PJ, 2=PF, 3=Estrangeiro), Name, Document (mascarado), QualificationCode, Qualification, EntryDate, AgeRange.
SimplesobjectSimples Nacional: { Optante, OptionDate, ExclusionDate }.
MeiobjectSituação como MEI: { Optante, OptionDate, ExclusionDate }.
O endpoint de CNPJ está disponível em todos os planos. O erro 403 PLAN_NOT_ALLOWED só ocorre se o recurso estiver desabilitado na sua conta.
C

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.

GET 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"
}
D

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.

GET https://api.zipfinder.com.br/api/v1/postal-codes/69309630/details?number=503
O parâmetro 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"
}
E

Estados API

Liste os estados disponíveis para um país usando o código ISO alpha-3, como BRA.

GET 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" }
  ]
}
L

Cidades API

Liste as cidades de um estado dentro de um país para compor formulários, filtros e fluxos de preenchimento assistido.

GET 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"]
}
U

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.

Ver Planos
AI

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.

Contrato

/openapi.json

Markdown

/documentacao.md

Agentes

/llms.txt
Para construir uma aplicação, leia primeiro /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.
!

Erros comuns

Status
Código
Descrição
400
INVALID_FORMAT
Formato inválido de CEP, país ou estado.
401
MISSING_API_KEY
Chave de API ausente ou inválida.
403
PLAN_NOT_ALLOWED
Recurso de consulta de CNPJ não habilitado na conta.
404
NOT_FOUND
Recurso não localizado.
422
UNPROCESSABLE_ENTITY
Parâmetros válidos, mas sem resultado processável.
429
RATE_LIMIT_EXCEEDED
Limite mensal do plano excedido.
500
INTERNAL_SERVER_ERROR
Falha inesperada no servidor.
502
CNPJ_PROVIDER_UNAVAILABLE
Falha ao consultar o provedor de CNPJ.