# API ZipData — Manual de Integração

**Consulta de CEPs e pesquisa de endereços**  
**Documentação pública para desenvolvedores**  
**Versão 1.2 | Outubro de 2026**  
**Interfix Informática Ltda. | ZipData**

## 1. Apresentação

A API ZipData permite integrar consultas de CEPs e pesquisas por endereço diretamente aos sistemas de clientes. As operações são realizadas por requisições HTTP `POST` e os resultados são disponibilizados em formato JSON.

**Acesso para testes:** solicite seu token de avaliação à equipe ZipData.

## 2. Conexão segura e autenticação

**Endereço base:** `https://consulta.zipdata.com.br`

A API utiliza HTTPS, com criptografia TLS para proteger os dados transmitidos entre a aplicação do cliente e o servidor ZipData. As consultas devem ser realizadas no endereço seguro informado acima.

**Formato de envio:** `application/x-www-form-urlencoded`.

Envie `type=api` e o token de acesso fornecido pela ZipData no corpo de cada requisição `POST`.

## 3. Operações disponíveis

| Endpoint | Método | Objetivo |
|---|---|---|
| `/search/unique` | `POST` | Consulta de endereço a partir do CEP |
| `/search/multiple` | `POST` | Pesquisa por logradouro, cidade e UF |

## 4. Consulta por CEP — `/search/unique`

| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| `type` | Sim | Sempre `api` |
| `token` | Sim | Token de acesso do cliente |
| `cep` | Sim | CEP desejado (ex.: `06660570`) |
| `return` | Não | Recomendado: `acento` para retorno com acentuação |

**Exemplo de consulta:** CEP `06660570`. O sistema envia os parâmetros e recebe uma resposta JSON acompanhada do status HTTP.

## 5. Pesquisa por endereço — `/search/multiple`

| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| `type` | Sim | Sempre `api` |
| `token` | Sim | Token de acesso do cliente |
| `street` | Sim | Nome do logradouro |
| `city` | Sim | Cidade |
| `uf` | Sim | Sigla do estado (ex.: `SP`) |
| `district` | Não | Bairro para refinar a busca |
| `cep` | Não | CEP para refinar a busca |
| `return` | Não | Recomendado: `acento` para retorno com acentuação |

**Exemplo:** pesquisar “Rua Augusta”, na cidade de São Paulo, UF SP. Para refinar, informe `district` e/ou `cep` quando disponíveis.

## 6. Integração PHP

Exemplo completo de consulta por CEP usando cURL. Configure a variável de ambiente `ZIPDATA_TOKEN` com seu token de avaliação antes de executar o exemplo.

```php
<?php
$baseUrl = "https://consulta.zipdata.com.br";
$token = getenv("ZIPDATA_TOKEN"); // Token de avaliação

$dados = [
    "type" => "api",
    "token" => $token,
    "cep" => "06660570",
    "return" => "acento"
];

$ch = curl_init($baseUrl . "/search/unique");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($dados),
    CURLOPT_HTTPHEADER => ["Content-Type: application/x-www-form-urlencoded"],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20
]);

$resposta = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($resposta === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Falha na consulta: HTTP " . $status);
}
$resultado = json_decode($resposta, true);
print_r($resultado);
```

### 6.1 PHP — pesquisa por endereço

Utilize o mesmo procedimento acima, alterando o endpoint para `/search/multiple` e o array de parâmetros:

```php
$dados = [
    "type" => "api",
    "token" => $token,
    "street" => "Rua Augusta",
    "city" => "São Paulo",
    "uf" => "SP",
    "return" => "acento"
];
// Endpoint: $baseUrl . "/search/multiple"
```

## 7. Integração Python

Exemplo com a biblioteca `requests`, utilizando conexão HTTPS e retorno JSON.

```python
import os
import requests

base_url = "https://consulta.zipdata.com.br"
token = os.environ["ZIPDATA_TOKEN"]

dados = {
    "type": "api",
    "token": token,
    "cep": "06660570",
    "return": "acento"
}
resposta = requests.post(
    f"{base_url}/search/unique",
    data=dados,
    timeout=20
)
resposta.raise_for_status()
resultado = resposta.json()
print(resultado)
```

### 7.1 Python — pesquisa por endereço

```python
dados = {
    "type": "api",
    "token": token,
    "street": "Rua Augusta",
    "city": "São Paulo",
    "uf": "SP",
    "return": "acento"
}
resposta = requests.post(
    f"{base_url}/search/multiple",
    data=dados,
    timeout=20
)
resposta.raise_for_status()
print(resposta.json())
```

## 8. Respostas da API

A API retorna dados em JSON com o código HTTP correspondente. O conteúdo e a quantidade de registros dependem da consulta efetuada. Nos exemplos de PHP e Python, a resposta é decodificada para permitir sua utilização pelo sistema integrador.

A documentação técnica de origem apresenta o campo `cep` como exemplo de informação retornada. O conjunto completo de campos deverá ser interpretado conforme a resposta efetiva de cada consulta.

## 9. Fluxo sugerido de integração

1. O sistema do cliente coleta o CEP ou os dados do endereço.
2. A aplicação envia uma requisição `POST` ao endpoint correspondente, por HTTPS.
3. A ZipData processa a consulta e retorna JSON.
4. O sistema do cliente interpreta o resultado e preenche, confere ou complementa os dados cadastrais.

## 10. Recomendações para implantação

Mantenha o token configurado no ambiente do servidor e utilize os exemplos como referência para integração. Recomenda-se realizar testes com CEPs e endereços conhecidos, conferir os dados retornados e tratar respostas HTTP de forma apropriada.

## 11. Suporte

**ZipData – Soluções para Validação de Endereços**  
**Interfix Informática Ltda.**  
**Ambiente de consultas:** https://consulta.zipdata.com.br

## 12. Referência rápida para integração

- **Consulta por CEP:** `POST https://consulta.zipdata.com.br/search/unique`
- **Pesquisa por endereço:** `POST https://consulta.zipdata.com.br/search/multiple`
- **Cabeçalho:** `Content-Type: application/x-www-form-urlencoded`
- **Campos comuns:** `type=api`, `token` e `return=acento`.
- **Resposta:** JSON.

Para evitar exposição da credencial, execute as consultas a partir do servidor da aplicação integradora.

## 13. Como começar a testar

Solicite um token de avaliação à equipe ZipData. Configure a credencial em seu ambiente de desenvolvimento e execute os exemplos de PHP ou Python utilizando os endpoints HTTPS documentados.

Os exemplos não incluem credenciais reais. O acesso à API depende de um token válido fornecido pela ZipData.