# Integração API Caixa (Resultados Oficiais) — Stub

**Fase 30.10** — Documentação para implementação futura quando a Caixa disponibilizar API de resultados.

## Objetivo

Consumir resultados oficiais da Caixa para popular/atualizar concursos automaticamente, reduzindo digitação manual e garantindo consistência.

## Situação atual

- Resultados são cadastrados manualmente via admin (Admin Concursos, conferência).
- Fonte de verdade: site oficial da Caixa (https://loterias.caixa.gov.br/).
- Não existe API pública oficial da Caixa para consumo programático (em mar/2025).

## Quando a API estiver disponível

### Endpoints esperados (hipotéticos)

| Endpoint | Descrição |
|----------|-----------|
| `GET /api/resultados/{sigla}/{numero}` | Resultado de um concurso específico |
| `GET /api/resultados/{sigla}?ultimos=N` | Últimos N concursos de uma loteria |
| `GET /api/concursos/{sigla}?proximos=N` | Próximos concursos (datas, números) |

### Fluxo sugerido

1. **Cron/tarefa agendada** (ex.: após cada sorteio)
   - Consultar API Caixa para loterias do dia
   - Comparar com tabela `concurso` (numeros_sorteio, resultado_premiacao)
   - Inserir ou atualizar registros

2. **Service de integração**
   - `ApiCaixaService` (ou similar) em `api/src/Service/`
   - Métodos: `buscarResultado(sigla, numero)`, `sincronizarLoteria(sigla)`
   - Mapear formato Caixa → estrutura interna (numeros_sorteio, faixas, etc.)

3. **Compatibilidade**
   - Manter fluxo manual como fallback
   - Log de auditoria para alterações via API
   - Validação de formato antes de persistir

### Arquivos a criar/alterar

- `api/src/Service/ApiCaixaService.php` — cliente da API
- `api/src/Controller/CronController.php` — tarefa de sincronização (ou script)
- `docs/runbook-cron.md` — documentar job de sincronização
- Variáveis de ambiente: `API_CAIXA_URL`, `API_CAIXA_KEY` (se necessário)

## Referências

- ideias-melhorias.md §6 (Integrações)
- Site oficial: https://loterias.caixa.gov.br/
- Planos futuros da Caixa (verificar periodicamente)

## Status

**Pendente** — Aguardando disponibilização de API oficial pela Caixa.