# ZipFinder API Documentation

Base URL:

```text
https://api.zipfinder.com.br/api
```

Machine-readable contract:

- OpenAPI: `https://www.zipfinder.com.br/openapi.json`
- Agent guide: `https://www.zipfinder.com.br/llms.txt`
- Human documentation: `https://www.zipfinder.com.br/documentacao.html`

## Quickstart

1. Create an account at `https://app.zipfinder.com.br/signup`.
2. Generate or copy your API key.
3. Store the key in a server-side environment variable, for example `ZIPFINDER_API_KEY`.
4. Send the key in the `x-api-key` header on authenticated endpoints.

Example:

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/v1/postal-codes/04134020 \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Do not expose API keys in public frontends.

## Authentication

Authenticated endpoints require:

```http
x-api-key: zfp_...
```

The health endpoint does not require authentication.

## Health / Status

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

Returns the operational status of the API.

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/health
```

Response:

```json
{
  "status": "ok",
  "timestamp": "2026-05-20T17:45:52.392Z"
}
```

## Company Lookup by CNPJ

```http
GET https://api.zipfinder.com.br/api/v1/companies/{cnpj}
```

Looks up company registration and address data from a Brazilian CNPJ with 14 digits.

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/v1/companies/22685030000111 \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Response:

```json
{
  "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"
}
```

The CNPJ endpoint requires an eligible plan. If the plan does not include it, the API returns `403 PLAN_NOT_ALLOWED`.

## Postal Code Lookup

```http
GET https://api.zipfinder.com.br/api/v1/postal-codes/{postalCode}
```

Looks up a Brazilian postal code. Latitude and longitude can be approximate because this endpoint does not receive an address number.

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/v1/postal-codes/04134020 \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Response:

```json
{
  "IsoAlpha2Country": "BR",
  "IsoAlpha3Country": "BRA",
  "ZipCode": "04134-020",
  "Street": "Rua das Uvaias",
  "TypeStreet": "Rua",
  "NameStreet": "das Uvaias",
  "Neighborhood": "Saude",
  "City": "Sao Paulo",
  "State": "SP",
  "IbgeCode": "3550308",
  "Latitude": -23.615189,
  "Longitude": -46.633281,
  "Source": "Correios do Brasil",
  "LastUpdated": "2026-04-22T19:10:42.000Z"
}
```

## Postal Code Details

```http
GET https://api.zipfinder.com.br/api/v1/postal-codes/{postalCode}/details?number={number}
```

Looks up an address with greater geocoding precision using postal code and address number.

```bash
curl --request GET \
  --url "https://api.zipfinder.com.br/api/v1/postal-codes/69309630/details?number=503" \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Response:

```json
{
  "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"
}
```

## States

```http
GET https://api.zipfinder.com.br/api/v1/countries/{countryCode}/states
```

Lists states for a country using the ISO alpha-3 country code.

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/v1/countries/BRA/states \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Response:

```json
{
  "Country": {
    "IsoAlpha2": "BR",
    "IsoAlpha3": "BRA",
    "Name": "Brasil"
  },
  "States": [
    { "Code": "SP", "Name": "Sao Paulo" },
    { "Code": "RJ", "Name": "Rio de Janeiro" }
  ]
}
```

## Cities

```http
GET https://api.zipfinder.com.br/api/v1/countries/{countryCode}/states/{state}/cities
```

Lists cities for a state inside a country.

```bash
curl --request GET \
  --url https://api.zipfinder.com.br/api/v1/countries/BRA/states/SP/cities \
  --header "x-api-key: $ZIPFINDER_API_KEY"
```

Response:

```json
{
  "Country": {
    "IsoAlpha2": "BR",
    "IsoAlpha3": "BRA",
    "Name": "Brasil"
  },
  "State": {
    "Code": "SP",
    "Name": "Sao Paulo"
  },
  "Cities": ["Campinas", "Sao Paulo"]
}
```

## Rate Limits

The Free plan includes 3,000 requests per month.

When the monthly limit is exceeded, the API returns:

```text
429 RATE_LIMIT_EXCEEDED
```

See plans at `https://www.zipfinder.com.br/planos.html`.

## Errors

| Status | Code | Description |
| --- | --- | --- |
| 400 | `INVALID_FORMAT` | Invalid parameter format. |
| 401 | `MISSING_API_KEY` or `INVALID_API_KEY` | Missing or invalid API key. |
| 404 | `NOT_FOUND` | Resource not found. |
| 422 | `UNPROCESSABLE_ENTITY` | Valid parameters, but no processable result. |
| 429 | `RATE_LIMIT_EXCEEDED` | Monthly plan limit exceeded. |
| 500 | `INTERNAL_SERVER_ERROR` | Unexpected server error. |

## AI Agent Implementation Notes

- Prefer `openapi.json` as the source of truth for routes, parameters, response schemas, and errors.
- Use this Markdown file for examples and integration notes.
- Generate server-side integrations, not public frontend calls with exposed keys.
- Use an environment variable such as `ZIPFINDER_API_KEY`.
- Do not use deprecated routes such as `/v1/cep` when building new integrations.
- Use `GET /v1/companies/{cnpj}` for company lookup when the plan supports CNPJ access.