# API — Wizard Leads (Sistema de TR)

Endpoint REST autenticado para consumir leads gerados pelo wizard público em `/wizard/create`. Substitui o uso anterior do arquivo `today-wizard-tests.txt`.

---

## Endpoint

```
GET https://www.sistemadetr.com.br/api/wizard-leads
```

## Autenticação

Token Bearer no header `Authorization`. Alternativamente, header `X-Api-Token`.

```
Authorization: Bearer <TOKEN>
```

O token é fornecido individualmente pela equipe do Sistema de TR (Viva Inovação). É vinculado a um nome (cliente) e a uma habilidade (`read-leads`). Não compartilhar.

Respostas de erro:
- `401 token_missing` — header ausente
- `401 token_invalid` — token não encontrado
- `401 token_expired` — token expirou
- `403 forbidden_ability` — token sem permissão para o endpoint

## Parâmetros (query string)

| Parâmetro | Tipo | Default | Descrição |
|---|---|---|---|
| `since_id` | int | 0 | Retorna leads com `id > since_id`. Use o `next_since_id` da resposta anterior para paginar (cursor). |
| `since_date` | date `YYYY-MM-DD` | — | Filtra `created_at >= since_date` |
| `until_date` | date `YYYY-MM-DD` | — | Filtra `created_at <= until_date 23:59:59` |
| `limit` | int | 100 | Quantos leads retornar (máx. 1000) |
| `municipio` | string | — | Filtro exato pelo campo `municipio` (ex.: `Recife-PE`) |

## Resposta (200 OK)

```json
{
  "data": [
    {
      "id": 12178,
      "nome": "Karine Cruz",
      "email": "karinecruz000@gmail.com",
      "phone": "75991723996",
      "municipio": "Japaratinga-AL",
      "instituicao": "Prefeitura",
      "instituicao_other": null,
      "enderecoe": "Praça Nsa Sra das Candeias, 106 ...",
      "objeto": "Contratação de empresa para fornecimento de drones",
      "ip": "189.126.2.40",
      "ip_city": "Ipirá",
      "request_id": "6a0f16047af4a",
      "created_at": "2026-05-21 11:27:17",
      "updated_at": null
    }
  ],
  "count": 1,
  "limit": 100,
  "next_since_id": 12178,
  "has_more": false
}
```

| Campo | Descrição |
|---|---|
| `data` | array de leads |
| `count` | número de leads retornados |
| `limit` | limite aplicado na consulta |
| `next_since_id` | cursor — usar como `since_id` na próxima chamada |
| `has_more` | `true` se ainda há leads não retornados (continue paginando) |

`created_at` está no timezone do servidor (`America/Sao_Paulo`).

## Padrão de polling recomendado

```
Estado local: last_seen_id = 0
A cada N minutos:
  GET /api/wizard-leads?since_id={last_seen_id}&limit=200
  while has_more:
    processar data
    last_seen_id = next_since_id
    GET /api/wizard-leads?since_id={last_seen_id}&limit=200
  Salvar last_seen_id
```

Sugestão: rodar polling a cada 5 minutos. Cada lead novo só aparece uma vez no fluxo.

## Exemplos

### curl — pegar últimos 10 leads de hoje

```bash
TOKEN="<seu-token>"
curl -H "Authorization: Bearer $TOKEN" \
  "https://www.sistemadetr.com.br/api/wizard-leads?since_date=$(date +%F)&limit=10"
```

### PHP (Laravel Http client)

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken($token)
    ->get('https://www.sistemadetr.com.br/api/wizard-leads', [
        'since_id' => $lastSeenId,
        'limit'    => 200,
    ]);

if ($response->successful()) {
    foreach ($response->json('data') as $lead) {
        // processar
    }
    $lastSeenId = $response->json('next_since_id');
}
```

### Node.js (fetch)

```javascript
const res = await fetch(
  `https://www.sistemadetr.com.br/api/wizard-leads?since_id=${lastSeenId}&limit=200`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const json = await res.json();
json.data.forEach(processarLead);
lastSeenId = json.next_since_id;
```

## Privacidade e LGPD

- Os dados retornados contêm PII (nome, e-mail, telefone, IP). O uso deve respeitar a LGPD (Lei 13.709/2018).
- O token autoriza apenas leitura. Mantenha sob sigilo. Em caso de comprometimento, solicitar revogação ao Sistema de TR (Viva Inovação).
- O endpoint registra `last_used_at` por token, permitindo auditoria.

## Mudanças relativas ao `today-wizard-tests.txt`

| Antes | Agora |
|---|---|
| Arquivo `.txt` público em `https://www.sistemadetr.com.br/today-wizard-tests.txt` | Endpoint REST autenticado |
| Pipe-separated | JSON estruturado |
| Sem cursor — baixa o arquivo inteiro | Cursor `since_id` — só o que é novo |
| ISO-8859-1 | UTF-8 |
| Sem filtro temporal | Filtros `since_date` / `until_date` |
| Acessível por qualquer pessoa (vazamento) | Acesso restrito por token revogável |
| Sem auditoria | `last_used_at` registrado |

O arquivo `today-wizard-tests.txt` continua sendo gerado durante o período de transição. Após confirmação da migração de consumo, será removido.