Referência

Guia da API

O Invoice-Agent expõe uma API REST/JSON sob /v1. Autenticação via header X-API-Key; rate limit por chave (default 60/min).

Endpoints públicos (sem auth)

Método	Path	Descrição
GET	/v1/health	Liveness + status das dependências
GET	/v1/ready	Readiness (DB acessível?)
GET	/v1/version	Versão + ambiente
GET	/v1/reports/types	Tipos de relatório registrados

Endpoints com auth (X-API-Key)

Extractions

POST /v1/extractions — cria job de extração assíncrono
GET /v1/extractions/{job_id} — estado do job
POST /v1/extractions/{job_id}/cancel — cancela job
POST /v1/extractions/compare — diff legacy vs novo

Admin (cutover)

GET /v1/admin/operadoras/ — lista operadoras + modo
POST /v1/admin/operadoras/{op}/mode — set modo (shadow/canary/full)
POST /v1/admin/operadoras/{op}/rollback — rollback de operadora

LGPD

DELETE /v1/invoices/{invoice_id} — direito ao esquecimento

Reports

POST /v1/reports/run — executar relatório

Exemplo de chamada

# Health (sem auth)
curl http://127.0.0.1:8080/v1/health

# Listar operadoras (com auth)
curl -H 'X-API-Key: <sua-chave>' \
     http://127.0.0.1:8080/v1/admin/operadoras/

# Criar extração
curl -X POST -H 'X-API-Key: <sua-chave>' \
     -H 'Content-Type: application/json' \
     -d '{"pdf_url": "s3://...", "operadora": "vivo"}' \
     http://127.0.0.1:8080/v1/extractions

Console interativo

Use o Swagger UI para testar endpoints sem escrever curl. Clique em qualquer endpoint → Try it out → preencha params → Execute.

Como obter uma API key

Em dev, configure em .env:

INVOICE_IA_API_KEYS=dev-key:extract,compare,admin

O formato é chave:escopo1,escopo2. Escopos disponíveis: extract, compare, admin, lgpd.