Pular para o conteúdo principal

API Examples

Introdução ao documento​

Este documento reúne exemplos rastreáveis de request e response para os endpoints cobertos em openapi.yaml. Os exemplos foram derivados apenas do código local: strings literais dos handlers, interfaces TypeScript, validações do frontend e chamadas reais feitas pelo próprio app.

Critério dos exemplos​

  • Quando o handler monta o JSON diretamente, o exemplo reflete esse shape.
  • Quando a resposta é repassada de um backend externo, o exemplo é parcial e isso é explicitado.
  • Quando o código não comprova body para um status, o documento diz isso em vez de inventar payload.

Evidências:

Exemplos públicos​

GET /api/liveness​

Response 200:

{
  "status": "alive",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "uptime": 12.34,
  "message": "Application is running"
}

Response 500:

{
  "status": "error",
  "message": "Application liveness check failed"
}

Evidências:

GET /api/health​

Response 200 ou 503:

{
  "status": "healthy",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "uptime": {
    "seconds": 123.45,
    "human": "0h 2m 3s"
  },
  "memory": {
    "used": 120,
    "total": 256,
    "external": 12,
    "usage": "46.88%",
    "unit": "MB"
  },
  "metrics": {
    "totalRequests": 10,
    "healthCheckCount": 3,
    "timeSinceLastRequest": "5ms",
    "healthCheckDuration": "2ms",
    "consecutiveSlowChecks": 0
  },
  "environment": {
    "nodeVersion": "v20.0.0",
    "platform": "linux",
    "env": "development"
  },
  "application": {
    "name": "dhedalos-app-onboarding-nextjs",
    "version": "1.0.0"
  }
}

Response 500:

{
  "status": "unhealthy",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "error": "Unknown error"
}

Evidências:

GET /api/readiness​

Response 200:

{
  "status": "ready",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "uptime": 10,
  "checks": {
    "environment": true,
    "memory": true,
    "uptime": true
  },
  "memory": {
    "used": 120,
    "total": 256,
    "usage": "46.88%",
    "unit": "MB"
  },
  "message": "Application is ready to serve requests"
}

Response 503:

{
  "status": "not_ready",
  "message": "Application is not ready to serve requests",
  "checks": {
    "environment": false,
    "memory": true,
    "uptime": true
  },
  "details": {
    "missingEnvVars": [
      "NEXTAUTH_SECRET"
    ]
  },
  "timestamp": "2026-03-20T12:00:00.000Z"
}

Evidências:

GET /api/config/keycloak​

Response 200 com integração desabilitada:

{
  "enabled": false
}

Response 200 com integração habilitada:

{
  "enabled": true,
  "url": "https://amei.sebrae.com.br/auth",
  "realm": "externo",
  "clientId": "conecta-sebrae"
}

Response 500:

{
  "error": "Internal server error while loading Keycloak configuration"
}

Evidências:

GET /api/v1/cursos/{slug}​

Response 200:

{
  "slug": "seu-curso",
  "title": "Curso",
  "description": "Descrição",
  "logo": "https://exemplo/logo.png",
  "banner": "https://exemplo/banner.png",
  "subscribers": 0
}

Observação: os ramos 400 e 404 não têm body comprovado no handler.

Evidências:

GET /api/envs​

Response 200:

{
  "appVersion": "1.0.0",
  "datadog": {
    "appId": "",
    "clientToken": "",
    "serviceName": "",
    "env": "",
    "sessionSampleRate": 100,
    "sessionReplaySampleRate": 20
  }
}

Evidências:

Exemplos autenticados​

GET /api/v1/participantes/{cpf}​

Autenticação observada: sessão NextAuth via getServerSession(). O handler não comprova body JSON para 401.

Response 200:

{
  "id": 1,
  "cpf": "00000000000",
  "name": "Nome",
  "email": "nome@exemplo.com",
  "phone": "+55 11 99999-9999",
  "gender": "Masculino",
  "race": "Branca",
  "birthday": "01/01/2000"
}

Evidências:

PUT /api/v1/participantes/{cpf}​

Autenticação observada: sessão NextAuth via getServerSession().

Request body parcial:

{
  "id": "",
  "cpf": "00000000000",
  "name": "Nome Sobrenome",
  "email": "nome@exemplo.com",
  "phone": "+55 11 99999-9999",
  "birthday": "01/01/2000",
  "gender": "Masculino",
  "race": "Branca"
}

Esse exemplo é rastreável pela combinação entre o body enviado pelo frontend e os campos validados no formulário.

Response 200 parcial de criação:

{
  "ok": true,
  "id": "123",
  "cpf": "00000000000",
  "name": "Nome Sobrenome",
  "email": "nome@exemplo.com",
  "phone": "+55 11 99999-9999",
  "race": "Branca"
}

Response 400:

{
  "message": "Falha na atualização dos dados"
}

Evidências:

POST /api/v1/otp/send​

Autenticação observada: sessão NextAuth via getServerSession().

Request:

{
  "phone": "+55 11 99999-9999"
}

Response 200:

{
  "message": "OK"
}

Response 400:

{
  "message": "Telefone inválido"
}

Observação: o handler não comprova body JSON para 401 e 405.

Evidências:

POST /api/v1/otp/confirm​

Autenticação observada: sessão NextAuth via getServerSession().

Request:

{
  "phone": "+55 11 99999-9999",
  "code": "123456"
}

Response 200 parcial:

{
  "message": "OK"
}

Observação: o shape acima é parcial. O handler faz json(await otpResponse.json()), então a resposta real depende do backend de OTP. A única evidência local de shape é a interface com message: string.

Response 400:

{
  "message": "Código ou telefone inváidos"
}

Response 500:

{
  "message": "erro retornado pelo sendTemplate"
}

Evidências:

POST /api/v1/flow/resend​

Autenticação observada: sessão NextAuth via getServerSession().

Request body observado: nenhum.

Response 200:

{
  "ok": true
}

Response 400:

{
  "message": "Erro no envio de template"
}

Response 401:

{
  "message": "Não autorizado"
}

Evidências:

Exemplo de tracking​

POST /api/meta-conversion​

O próprio frontend envia um exemplo real deste endpoint ao completar cadastro.

Request observado:

{
  "event_name": "CompleteRegistration",
  "user_data": {
    "em": "nome@exemplo.com",
    "ph": "+55 11 99999-9999",
    "fn": "Nome Sobrenome"
  },
  "event_source_url": "https://exemplo.com/curso/inscricao/confirmacao"
}

Response 500 quando faltar configuração:

{
  "error": "Configuração ausente"
}

Response 500 por erro interno:

{
  "error": "Internal error"
}

Evidências:

Endpoints sem cobertura suficiente​

  • /api/auth/[...nextauth] Evidência: ../../pages/api/auth/[...nextauth].ts#L25-L155 Motivo: o repositório delega o catch-all ao NextAuth(authOptions), sem detalhar de forma local todos os métodos, query params, cookies e payloads efetivamente expostos.

Pendências​

  • O payload de sucesso de POST /api/v1/otp/confirm depende diretamente do backend de OTP e tem apenas shape parcial confirmado.
  • O retorno de sucesso de PUT /api/v1/participantes/{cpf} é parcial; o adapter de update retorna any.
  • GET /api/v1/cursos/{slug} não fecha corretamente os ramos 400 e 404, então esses exemplos não podem ser afirmados.

Versionamento​

Atualizar este arquivo quando exemplos, handlers ou openapi.yaml divergirem do código.

Evidências:

Referencial teórico​

  • OpenAPI Example Object.
  • Documentação de exemplos orientada a evidência.