{
  "name": "ZipFinder Public API",
  "base_url": "https://api.zipfinder.com.br",
  "authentication": {
    "type": "API Key",
    "header": "x-api-key"
  },
  "versioning": {
    "current_version": "v1",
    "strategy": "Versionamento por path de API."
  },
  "endpoints": [
    {
      "name": "Consulta de CEP",
      "method": "GET",
      "path": "/v1/cep/{cep}",
      "description": "Consulta dados de endereço a partir de um CEP.",
      "input": {
        "cep": "CEP brasileiro com ou sem máscara."
      },
      "output_fields": [
        "country",
        "zipcode",
        "street",
        "neighborhood",
        "city",
        "state",
        "ibge_code",
        "latitude",
        "longitude",
        "source",
        "updated_at"
      ],
      "precision_note": "Como este endpoint não recebe o número do endereço, latitude e longitude podem ser aproximadas."
    },
    {
      "name": "Consulta de CNPJ",
      "method": "GET",
      "path": "/v1/companies/{cnpj}",
      "description": "Consulta dados cadastrais e de endereçamento de uma empresa a partir de um CNPJ brasileiro.",
      "input": {
        "cnpj": "CNPJ brasileiro com 14 dígitos."
      },
      "output_fields": [
        "Exists",
        "Cnpj",
        "LegalName",
        "TradeName",
        "Address",
        "Phone",
        "Email",
        "Latitude",
        "Longitude",
        "GeoSource",
        "GeoConfidence",
        "GeoLastUpdated",
        "Source",
        "Stale",
        "LastUpdated"
      ],
      "precision_note": "Endpoint público em `https://api.zipfinder.com.br/api`."
    },
    {
      "name": "Detalhe por CEP + número",
      "method": "GET",
      "path": "/v1/cep/{cep}/numero/{number}",
      "description": "Consulta dados de endereço com maior precisão geográfica a partir de CEP e número.",
      "input": {
        "cep": "CEP brasileiro com ou sem máscara.",
        "number": "Número do endereço."
      },
      "output_fields": [
        "country",
        "zipcode",
        "number",
        "street",
        "neighborhood",
        "city",
        "state",
        "ibge_code",
        "latitude",
        "longitude",
        "source",
        "updated_at"
      ],
      "precision_note": "Endpoint recomendado para cenários que exigem latitude e longitude mais precisas."
    }
  ],
  "rate_limits": {
    "description": "Os limites variam conforme o plano contratado.",
    "dimensions": [
      "requisições por minuto",
      "requisições por hora",
      "requisições mensais",
      "limite mensal para APIs pagas de fallback"
    ]
  },
  "error_handling": {
    "principles": [
      "Retornar mensagens claras",
      "Indicar quando o CEP não for encontrado",
      "Evitar expor detalhes internos da infraestrutura",
      "Preservar rastreabilidade da origem dos dados quando possível"
    ]
  }
}