Guia de uso - API Externa

1. Visão Geral

Base URL: https://external-reporting.e-inscricao.com/v1

Swagger UI: https://external-reporting.e-inscricao.com/docs

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

URL do Painel Admin: https://admin-external-reporting.einscricao.app

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.

Fluxo recomendado:

• Iniciar login com email/senha.
• 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. Consultar Relatório Summary

Endpoint

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

Exemplo cURL

curl "https://external-reporting.e-inscricao.com/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

4. Consultar Relatório por Evento

Endpoint

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

Exemplo cURL

curl "https://external-reporting.e-inscricao.com/v1/reports/events?from=2025-01-01&to=2025-12-31" \
  -H "x-api-key: <API_KEY_SECRET>"

Response 200 (exemplo)

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

5. 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 "https://external-reporting.e-inscricao.com/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": [
    {
      "purchaseDate": "2025-10-03T14:22:11.000Z",
      "paymentType": "credit_card",
      "amount": 197.9,
      "age": 29,
      "gender": "female",
      "region": "Sudeste"
    },
    {
      "purchaseDate": "2025-10-02T09:01:05.000Z",
      "paymentType": "pix",
      "amount": 89.9,
      "age": null,
      "gender": "unknown",
      "region": "unknown"
    }
  ]
}

Campos principais de retorno

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

6. Erros Comuns e Diagnóstico Rápido