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&eventId=123

eventId é opcional. Quando informado, retorna apenas o evento correspondente dentro do período.

Exemplo cURL

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

Response 200 (exemplo)

{
  "count": 1,
  "items": [
    {
      "eventId": 123,
      "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&eventId=123&page=1&pageSize=50

eventId é opcional. Quando informado, filtra as compras antes da paginação.

Exemplo cURL

curl "https://external-reporting.e-inscricao.com/v1/reports/purchases?from=2025-01-01&to=2025-12-31&eventId=123&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": 1,
  "totalPages": 1,
  "items": [
    {
      "eventId": 123,
      "purchaseDate": "2025-10-03T14:22:11.000Z",
      "paymentType": "credit_card",
      "amount": 197.9,
      "age": 29,
      "gender": "female",
      "region": "Sudeste",
      "meta": {
        "origem": "landing-page",
        "cupom": "PROMO10"
      }
    }
  ]
}

Campos principais de retorno

• page, pageSize, total, totalPages
• items[].eventId: identificador do evento, ou null quando não houver evento vinculado
• items[].purchaseDate, items[].paymentType, items[].amount
• items[].age, items[].gender, items[].region, items[].meta

6. Erros Comuns e Diagnóstico Rápido