API pública REST

A API REST do Skillment expõe operações comuns de leitura e escrita em recursos do tenant. Ideal pra integrar com seu funil de marketing, seu CRM ou pra automações n8n / Zapier.

OpenAPI 3.1 spec

A especificação completa está disponível em:

GET /api/public/v1/openapi.json

Você pode importar essa URL diretamente em Postman, Insomnia, Hoppscotch, Scalar, Swagger UI, etc.

Autenticação

Toda chamada exige header Authorization: Bearer skllm_xxx. Gere uma API key em /admin/api-keys. As keys são per-tenant e podem ter escopo limitado (read-only, write-trilhas, etc).

curl https://[seu-tenant].skillment.app/api/public/v1/users \
  -H "Authorization: Bearer skllm_seu_token_aqui"

Endpoints principais

Users

• GET /api/public/v1/users — lista paginada de learners
• POST /api/public/v1/users — cria learner (envia magic link)
• GET /api/public/v1/users/:id — detalhe + XP + progresso
• PATCH /api/public/v1/users/:id — atualiza área/turma/cargo
• DELETE /api/public/v1/users/:id — soft-delete (LGPD compliant)

Trilhas

• GET /api/public/v1/trails — lista trilhas
• GET /api/public/v1/trails/:slug — detalhe com fases
• POST /api/public/v1/trails/:slug/enroll — matricula learner em trilha

Eventos & analytics

• GET /api/public/v1/events — eventos auditáveis (XP earned, lição concluída, conquista desbloqueada)
• GET /api/public/v1/analytics/funnel — funil de conclusão por trilha

Webhooks

Em vez de polling, registre uma URL pra receber eventos em tempo quase real. Em /admin/webhooks:

• URL do seu endpoint (HTTPS)
• Eventos: trail.completed, certificate.issued, achievement.unlocked, reward.redeemed, etc
• Secret HMAC (gerado automaticamente)

Verificação de assinatura (Stripe-style)

Toda requisição traz header X-Skillment-Signature no formato:

X-Skillment-Signature: t=1737036273,v1=ab12cd34...

Pra verificar:

const signed = `${timestamp}.${rawBody}`;
const expected = crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(signed)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(receivedV1)
);
// Reject if timestamp older than 5min (replay protection)

Rate limits

Default: 60 requisições/minuto por API key. Plans Growth e Enterprise têm limites mais altos. Headers de resposta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1737036420

Erros

Padrão JSON:

{
  "error": {
    "code": "validation_error",
    "message": "email is required",
    "fields": ["email"]
  }
}

Status codes: 200/201 sucesso, 400 validação, 401 sem auth, 403 sem scope, 404 não existe, 409 conflito (duplicate email), 429 rate limited, 5xx erro nosso (reporte).