# ZipFinder API

Documentation: https://www.zipfinder.com.br/documentacao.html
Markdown documentation: https://www.zipfinder.com.br/documentacao.md
OpenAPI: https://www.zipfinder.com.br/openapi.json
Pricing: https://www.zipfinder.com.br/planos.html
Signup: https://app.zipfinder.com.br/signup

ZipFinder API provides Brazilian postal code lookup, address validation, geocoding, state listing, city listing, and API health status.
It also provides company lookup by CNPJ through the public endpoint `GET https://api.zipfinder.com.br/api/v1/companies/{cnpj}`.

Use the `x-api-key` HTTP header for authenticated endpoints. Production API keys use the `zfp_...` prefix. Do not expose API keys in public frontends; keep them in server-side environment variables.

The health endpoint does not require authentication:

```http
GET https://api.zipfinder.com.br/api/health
```

Authenticated endpoints:

```http
GET https://api.zipfinder.com.br/api/v1/postal-codes/{postalCode}
GET https://api.zipfinder.com.br/api/v1/postal-codes/{postalCode}/details?number={number}
GET https://api.zipfinder.com.br/api/v1/companies/{cnpj}
GET https://api.zipfinder.com.br/api/v1/countries/{countryCode}/states
GET https://api.zipfinder.com.br/api/v1/countries/{countryCode}/states/{state}/cities
```

Free plan limit: 3,000 requests per month. When the monthly limit is exceeded, the API returns `429 RATE_LIMIT_EXCEEDED`.

Recommended integration flow for AI agents:

1. Read `openapi.json` for the exact contract.
2. Use `documentacao.md` for examples and implementation notes.
3. Generate server-side code that reads `ZIPFINDER_API_KEY` from environment variables.
4. Send `x-api-key: ${ZIPFINDER_API_KEY}` on every authenticated request.
5. Handle at least `400`, `401`, `404`, `422`, `429`, and `500` error responses.