Guia de uso - API Externa

1. Visão Geral

Base URL: http://localhost:3000/v1

Swagger UI: http://localhost:3000/docs

Painel Admin: aplicação web separada para login, 2FA, API keys e relatórios.

URL do Painel Admin: http://localhost:5173

Fluxo recomendado:

• Iniciar login com email/senha.
• Se retornar setupToken, configurar 2FA e ativar com código do app autenticador.
• Fazer login final com twoFactorCode para obter JWT.
• Criar API key com JWT.
• Usar o secret da API key no header x-api-key para relatórios.

JWT para /api-keys x-api-key para /reports Formato de data YYYY-MM-DD

2. Regras Importantes

• O valor do x-api-key é o secret da chave, não o keyId.
• O campo name é o nome identificador da API key (ex.: cliente-abc-prod).
• Se scopes não for enviado, o padrão é ["reports:read"].
• O secret só aparece na criação/rotação da chave.
• O login pode retornar setupToken para concluir a configuração de 2FA antes de liberar o acesso.

3. Iniciar Login (obter setupToken)

Endpoint

POST /v1/auth/login

Request

{
  "email": "[email protected]",
  "password": "secret123"
}

Exemplo cURL

curl -X POST "http://localhost:3000/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secret123"}'

Response 200 (quando precisa configurar 2FA)

{
  "requiresTwoFactorSetup": true,
  "setupToken": "<SETUP_TOKEN>",
  "setupTokenExpiresInSeconds": 600
}

4. Configurar 2FA e concluir login

Status do 2FA

curl "http://localhost:3000/v1/auth/2fa/status" \
  -H "Authorization: Bearer <SETUP_TOKEN>"

Iniciar setup (gera chave + QR)

curl -X POST "http://localhost:3000/v1/auth/2fa/setup" \
  -H "Authorization: Bearer <SETUP_TOKEN>"

Ativar 2FA

curl -X POST "http://localhost:3000/v1/auth/2fa/enable" \
  -H "Authorization: Bearer <SETUP_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

Importante: este endpoint ativa o 2FA, mas não retorna access_token.

Fazer login final com 2FA ativo

curl -X POST "http://localhost:3000/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secret123","twoFactorCode":"123456"}'

Response 200 (login final)

{
  "access_token": "<JWT>"
}

5. Criar API Key

Endpoint

POST /v1/api-keys (header Authorization: Bearer <JWT>)

Request

{
  "name": "client-acme-prod",
  "scopes": ["reports:read"]
}

Exemplo cURL

curl -X POST "http://localhost:3000/v1/api-keys" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"client-acme-prod","scopes":["reports:read"]}'

Response 200 (exemplo)

{
  "keyId": "9f8c...",
  "name": "client-acme-prod",
  "scopes": ["reports:read"],
  "secret": "ab12cd34..."
}

Importante: o campo secret é exibido somente na criação/rotação da API key. Salve esse valor em local seguro, pois ele não será retornado novamente.

6. Consultar Relatório Summary

Endpoint

GET /v1/reports/summary?from=YYYY-MM-DD&to=YYYY-MM-DD

Exemplo cURL

curl "http://localhost:3000/v1/reports/summary?from=2025-01-01&to=2025-12-31" \
  -H "x-api-key: <API_KEY_SECRET>"

Campos principais de retorno

• eventsCount, enrollmentsCount
• contractedRevenueTotal, paidRevenueTotal
• purchasesByDay, byPaymentType
• byGender, byAgeBucket, byRegion

7. Consultar Relatório por Evento

Endpoint

GET /v1/reports/events?from=YYYY-MM-DD&to=YYYY-MM-DD

Exemplo cURL

curl "http://localhost:3000/v1/reports/events?from=2025-01-01&to=2025-12-31" \
  -H "x-api-key: <API_KEY_SECRET>"

Response 200 (exemplo)

{
  "count": 1,
  "items": [
    {
      "evento_id": 123,
      "titulo": "Congresso X",
      "data_inicio": "2025-06-10T00:00:00.000Z",
      "enrollmentsCount": 80,
      "contractedRevenue": 12000,
      "paidRevenue": 10300
    }
  ]
}

8. Consultar Relatório de Compras

Endpoint

GET /v1/reports/purchases?from=YYYY-MM-DD&to=YYYY-MM-DD&page=1&pageSize=50

Exemplo cURL

curl "http://localhost:3000/v1/reports/purchases?from=2025-01-01&to=2025-12-31&page=1&pageSize=50" \
  -H "x-api-key: <API_KEY_SECRET>"

Response 200 (exemplo)

{
  "from": "2025-01-01",
  "to": "2025-12-31",
  "page": 1,
  "pageSize": 50,
  "total": 2,
  "totalPages": 1,
  "items": [
    {
      "purchaseId": 999001,
      "purchaseDate": "2025-10-03T14:22:11.000Z",
      "paymentType": "credit_card",
      "provider": "pagarme",
      "amount": 197.9,
      "age": 29,
      "gender": "female",
      "region": "Sudeste",
      "eventId": 123,
      "enrollmentId": 456
    },
    {
      "purchaseId": 999000,
      "purchaseDate": "2025-10-02T09:01:05.000Z",
      "paymentType": "pix",
      "provider": "asaas",
      "amount": 89.9,
      "age": null,
      "gender": "unknown",
      "region": "unknown",
      "eventId": 123,
      "enrollmentId": 455
    }
  ]
}

Campos principais de retorno

• page, pageSize, total, totalPages
• items[].purchaseDate, items[].paymentType, items[].provider, items[].amount
• items[].age, items[].gender, items[].region
• items[].eventId, items[].enrollmentId

9. Erros Comuns e Diagnóstico Rápido