API Examples (Request/Response)

Introdução ao documento

Este documento reúne exemplos de chamadas HTTP rastreáveis para os endpoints expostos pelo serviço. Evidência: src/server.ts:102 Evidência: src/server.ts:162

Versionamento

• Versão do documento: 2.0.0.
• Última atualização: 2026-03-18. Evidência: docs/api/openapi.yaml:1

Referencial teórico

• OpenAPI 3.0.3 para contrato da API.
• Semântica HTTP (status 2xx/4xx/5xx) aplicada nos handlers Express. Evidência: docs/api/openapi.yaml:1 Evidência: src/routes/otp.ts:20 Evidência: src/server.ts:192

Base URLs observadas

• Local: http://localhost:4000.
• Piloto: https://api.onboarding.stg.dhedalos.com.
• Produção: https://api.cadastro.sebraeingresse.com.br.
• Essencia: https://api-onboarding.essencia.dhedalos.com. Evidência: src/server.ts:100 Evidência: kubernetes/oke-we-002/piloto-dhedalos-ecosystem/values.yaml:8 Evidência: kubernetes/oke-we-001/dhedalos-ecosystem/values.yaml:8 Evidência: kubernetes/oke-we-001/essencia-ecosystem/values.yaml:8

Autenticação

• Endpoints /otp, /otp/confirmation, /sendtemplate, /sendreminder exigem header Authorization validado por verifyServiceToken.
• Endpoint POST / valida assinatura x-hub-signature-256 somente quando APP_SECRET está configurado. Evidência: src/routes/otp.ts:9 Evidência: src/routes/sendTemplate.ts:8 Evidência: src/routes/sendGroupLink.ts:8 Evidência: src/auth/serviceToken.ts:6 Evidência: src/server.ts:341

Exemplo 1 - POST /otp

Fonte: src/routes/otp.ts:9

curl --request POST \
  --url 'http://localhost:4000/otp' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SERVICE_TOKEN>' \
  --data '{"phone":"5581999999999"}'

Resposta 201 (quando DEBUG=false, comportamento padrão):

{
  "message": "OTP generated",
  "otp": true
}

Resposta 500:

{
  "message": "Erro ao enviar código OTP"
}

Exemplo 2 - POST /otp/confirmation

Fonte: src/routes/otp.ts:27

curl --request POST \
  --url 'http://localhost:4000/otp/confirmation' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SERVICE_TOKEN>' \
  --data '{"phone":"5581999999999","code":"123456"}'

Resposta 200:

{
  "message": "OTP validated successfully"
}

Resposta 400:

{
  "message": "Invalid OTP"
}

Exemplo 3 - POST /sendtemplate

Fonte: src/routes/sendTemplate.ts:8

curl --request POST \
  --url 'http://localhost:4000/sendtemplate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SERVICE_TOKEN>' \
  --data '{
    "phone":"5581999999999",
    "flow_token":"curso_123",
    "template_id":"template_onboarding",
    "name":"Maria Silva",
    "image_url":"https://example.com/img.png"
  }'

Resposta 201:

{
  "message": "Mensagem enviada",
  "ok": true
}

Resposta 400:

{
  "message": "Invalid fields: phone, flow_token, image_url, template_id or name"
}

Exemplo 4 - POST /sendreminder

Fonte: src/routes/sendGroupLink.ts:8

curl --request POST \
  --url 'http://localhost:4000/sendreminder' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <SERVICE_TOKEN>' \
  --data '{
    "phone":"5581999999999",
    "class_name":"Turma A",
    "group_template_id":"grupo_template",
    "user_name":"Maria Silva",
    "enroll_id":"enroll_123"
  }'

Resposta 200:

{
  "message": "Mensagem enviada",
  "ok": true
}

Exemplo 5 - GET /webhook (verificação)

Fonte: src/routes/webhook.ts:83

curl --request GET \
  --url 'http://localhost:4000/webhook?hub.mode=subscribe&hub.verify_token=<WEBHOOK_VERIFY_TOKEN>&hub.challenge=12345'

Resposta 200:

12345

Resposta 403 quando token diverge:

Forbidden

Exemplo 6 - POST / (callback de flow criptografado)

Fonte: src/server.ts:102

curl --request POST \
  --url 'http://localhost:4000/' \
  --header 'Content-Type: application/json' \
  --header 'x-hub-signature-256: sha256=<assinatura>' \
  --data '{
    "encrypted_aes_key":"<base64>",
    "encrypted_flow_data":"<base64>",
    "initial_vector":"<base64>"
  }'

Resposta 200:

<base64_encrypted_response>

Resposta 400:

{
  "error": "Missing required fields: encrypted_aes_key, encrypted_flow_data, or initial_vector"
}

Resposta 432:

Exemplo 7 - GET /api/readiness

Fonte: src/server.ts:176

curl --request GET --url 'http://localhost:4000/api/readiness'

Resposta 200:

{
  "status": "ready",
  "checks": {
    "database": "ok"
  }
}

Resposta 503:

{
  "status": "not ready",
  "checks": {
    "database": "error"
  }
}

Endpoints sem cobertura funcional completa

• POST /webhook: o payload da Meta é dinâmico e o código processa apenas mensagens type=text; não há schema estrito no repositório.
• POST /: decryptedBody depende do contrato externo do WhatsApp Flow e dos fluxos (personal/business) em runtime. Evidência: src/routes/webhook.ts:16 Evidência: src/server.ts:288 Evidência: src/flows/personal.ts:52 Evidência: src/flows/business.ts:132

Pendências

• Confirmar exemplos oficiais de payload criptografado válidos para QA automatizado (o repositório não contém fixtures desse endpoint).
• Confirmar se o formato de Authorization oficial é sempre Bearer <token>; o middleware valida apenas o segundo token da string. Evidência: src/server.ts:102 Evidência: src/auth/serviceToken.ts:17