Tudo o que sua equipe precisa para integrar.

A plataforma expõe tudo o que a interface administrativa faz — usuários, cursos, matrículas, progresso, certificados, relatórios e webhooks — em uma API REST versionada, pensada para integração servidor-a-servidor com o seu RH, ERP ou sistema interno.

Ambientes

Homologação e produção usam a mesma base URL e as mesmas regras de negócio: o que muda é a credencial. O ambiente de homologação é um espaço (tenant) dedicado com dados descartáveis — desenvolva contra ele e, ao entrar em produção, troque apenas a chave. Nenhuma outra alteração de código é necessária.

1. Crie uma API Key. No painel administrativo, acesse Integrações → API Keys, escolha um nome e marque apenas os escopos que a integração vai usar. A chave completa (ik_live_...) é exibida uma única vez — guarde-a em um cofre de segredos. Se ela se perder, gere outra e revogue a anterior.

2. Faça a primeira chamada. Toda requisição leva a chave no header Authorization:

curl "https://api-dev.intellicreate.online/api
/v1/courses?limit=10" \
  -H "Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxxxxxx"

3. Fluxo típico de uma integração de treinamento:

API Keys

A forma principal de autenticação. Cada chave pertence a um espaço (tenant), carrega escopos explícitos e pode ser rotacionada ou revogada no painel a qualquer momento. O isolamento é automático: a credencial determina o tenant e nenhum dado de outro cliente é alcançável, em nenhuma rota.

Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxxxxxx

Escopos disponíveis

Chamadas fora do escopo da chave respondem 403 com type: authorization_error — conceda a cada integração somente o que ela usa.

OAuth 2.0 (Client Credentials)

Alternativa para equipes que padronizam integrações em OAuth. Cadastre um client no painel (Integrações → OAuth 2.0) e troque as credenciais por um token de acesso de curta duração; o token carrega os mesmos escopos e substitui a API Key no header.

curl -X POST https://api-dev.intellicreate.online/api
/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=cl_live_xxxxxxxxxxxxxxxx" \
  -d "client_secret=cs_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "scope=users:read enrollments:write"

→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "..." }

Também estão disponíveis POST /oauth/revoke (invalida um token) e POST /oauth/introspect (verifica validade e escopos), conforme as RFCs 7009 e 7662.

Paginação por cursor

Listagens que podem crescer sem limite (usuários, matrículas de um usuário, certificados) usam paginação por cursor: peça a primeira página com limit (padrão 20, máximo 100) e repita a chamada passando cursor=next_cursor até has_more ser false. O cursor é opaco — não interprete seu conteúdo.

GET /v1/users?limit=50
→ { "data": [ ... ], "next_cursor": "MTc4ODA1MzU4MQ==", "has_more": true, "limit": 50 }

GET /v1/users?limit=50&cursor=MTc4ODA1MzU4MQ==
→ { "data": [ ... ], "next_cursor": null, "has_more": false, "limit": 50 }

Filtros

Filtros são parâmetros de query documentados por recurso — por exemplo GET /v1/enrollments?user_id=...&status=completed ou GET /v1/users?email=maria@empresa.com.br. Em GET /v1/users o parâmetro fields permite reduzir a resposta às colunas desejadas.

Toda a superfície /v1 usa um envelope único de erro. O campo type classifica a falha, code dá o motivo específico (estável, próprio para switch no seu código), detail traz contexto estruturado quando existe e request_id identifica a chamada nos nossos logs — inclua-o em qualquer chamado de suporte.

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "type": "business_rule",
    "code": "regulatory_profile_missing",
    "message": "Este curso é regulado e exige o perfil regulatório completo do aluno...",
    "detail": { "missing_fields": ["cpf", "cnh"] },
    "request_id": "req_Zx8kQ2mN4pTv"
  }
}

Os limites protegem a estabilidade da plataforma para todos os clientes e são dimensionados com folga para operações reais — incluindo cargas de milhares de matrículas.

Ao receber 429, honre os headers RateLimit-Reset e repita após o intervalo. Para sincronizações grandes, prefira o endpoint em massa a laços de chamadas individuais — além de mais rápido, consome uma única requisição do limite.

Campos de criação e atualização

Cursos são criados e gerenciados pelo painel (inclusive importação de pacotes SCORM). A API é o espelho de leitura para integrações — o catálogo do seu portal interno, por exemplo, pode ser montado inteiramente a partir destes endpoints.

Como o progresso é medido

progress reflete o avanço real do aluno sobre o conteúdo (0–100) e score consolida a nota das avaliações. A conclusão muda status para completed, preenche completed_at e dispara o webhook enrollment.completed — em curso regulado, somente depois de todos os critérios validados no servidor. Para acompanhamento em tempo real prefira webhooks a consultas periódicas; para conciliação, o GET é a fonte da verdade.

GET /v1/enrollments/8098829c-...
→ {
  "data": {
    "id": "8098829c-...",
    "user_id": "57e49256-...",
    "course_id": "2c999245-...",
    "status": "COMPLETED",
    "progress": 100,
    "score": 95,
    "started_at": "2026-08-12T13:05:11.000Z",
    "completed_at": "2026-08-19T20:41:37.000Z",
    "expires_at": null
  }
}

Certificados são emitidos automaticamente na conclusão — não existe emissão manual. Cada um carrega um código único de verificação pública, o que permite a qualquer auditor confirmar a autenticidade sem credencial.

GET /v1/certificates/verify/IC-9F2K-QX7M
→ {
  "verified": true,
  "certificate": {
    "verification_code": "IC-9F2K-QX7M",
    "user_name": "Maria da Silva",
    "holder_cpf": "***.***.***-05",
    "course_title": "Curso de Segurança da Informação",
    "issued_by": "Empresa Exemplo",
    "issued_at": "2026-08-19T20:41:40.000Z",
    "expires_at": null
  }
}

Estes endpoints sustentam rotinas de relatório recorrentes (diárias ou semanais) sem processar listagens paginadas: uma chamada devolve o consolidado pronto para o seu BI, e o CSV alimenta planilhas e data lakes diretamente.

Em vez de consultar a API em intervalos, receba os eventos no seu endpoint HTTPS no momento em que acontecem. Cada entrega é um POST JSON assinado com HMAC-SHA256 — você valida a assinatura e tem garantia de origem e integridade.

Formato da entrega

POST https://seu-sistema.com.br/webhooks/plataforma
User-Agent: IntelliCreate-Webhooks/1.0
X-IntelliCreate-Signature: t=1788053581,v1=6d5f8a...
X-IntelliCreate-Event-Id: evt_a1b2c3d4e5f6a7b8c9d0e1f2
X-IntelliCreate-Event-Type: enrollment.completed
X-IntelliCreate-Delivery-Id: 7c3e...

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "enrollment.completed",
  "created": 1788053581,
  "version": "2026-05",
  "tenant_id": "0b66903f-...",
  "data": {
    "enrollment_id": "8098829c-...",
    "user_id": "57e49256-...",
    "course_id": "2c999245-...",
    "progress_percent": 100,
    "score": 95,
    "completed_at": "2026-08-19T20:41:37.000Z"
  }
}

Validação da assinatura (obrigatória)

A assinatura cobre timestamp.corpo_bruto. Valide com o secret do endpoint, em comparação de tempo constante, e rejeite timestamps com mais de 5 minutos (anti-replay). O mesmo X-IntelliCreate-Event-Id pode chegar mais de uma vez em retentativas — trate as entregas de forma idempotente.

import { createHmac, timingSafeEqual } from "node:crypto";

function verificarWebhook(rawBody, sigHeader, secret) {
  const partes = Object.fromEntries(sigHeader.split(",").map((p) => p.split("=")));
  const t = parseInt(partes.t, 10);

  if (Math.abs(Date.now() / 1000 - t) > 300) throw new Error("timestamp expirado");

  const esperado = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  if (!timingSafeEqual(Buffer.from(partes.v1), Buffer.from(esperado)))
    throw new Error("assinatura inválida");
}

Retentativas

Consideramos entregue qualquer resposta 2xx em até 10 segundos. Fora disso, reentregamos com backoff exponencial — 7 tentativas ao longo de ~7h30 (imediata, +5s, +30s, +2min, +10min, +1h, +6h). Após a última falha a entrega fica visível no histórico e pode ser reenfileirada manualmente pelo endpoint de retry.

Catálogo de eventos

Cursos exigidos por regulamentação (trânsito, segurança do trabalho, setor financeiro) precisam de mais do que "aluno viu todas as telas". A plataforma suporta critérios de conclusão validados no servidor, por curso:

O impacto na integração é objetivo: POST /v1/enrollments em curso regulado responde 422 regulatory_profile_missing enquanto faltar CPF ou CNH — complete o cadastro via PATCH /v1/users/{id} e repita. A conclusão (e o certificado) só efetivam quando todos os critérios passam, mesmo que o conteúdo esteja 100% visto; até lá a matrícula permanece in_progress com progress: 100. O certificado emitido carrega o CPF e a CNH do titular (mascarados em toda a API) e é verificável publicamente.

Pacotes SCORM 1.2 e 2004 importados pelo painel se comportam como qualquer curso na API: mesma matrícula, mesmo progress, mesmos webhooks e o mesmo certificado automático. Pacotes com vários SCOs viram cursos com um módulo por SCO, e a conclusão consolida todos eles. Critérios regulatórios também se aplicam — o pacote se declarar concluído não basta.

Relatório por questão

Quando o pacote reporta as respostas dos quizzes ao runtime (cmi.interactions), a plataforma as armazena por aluno e questão. Sua integração lê tudo por matrícula:

GET /v1/enrollments/{id}/interactions
→ {
  "data": [
    {
      "module_id": "d8084120-...",
      "module_title": "Módulo 1",
      "interaction_id": "pergunta_01",
      "type": "choice",
      "description": "O que é engenharia social?",
      "response": "b",
      "correct_response": "b",
      "result": "correct",
      "latency_seconds": 14,
      "weighting": 1,
      "updated_at": "2026-08-30T01:26:59.991Z"
    }
  ]
}

Curso sem SCORM — ou pacote que não reporta interações, comportamento comum em conteúdos sem quiz — devolve lista vazia; não é erro. O painel administrativo exibe o consolidado por questão (respondentes e taxa de acerto) sem precisar de integração.

SSO — autenticação federada

Alunos e administradores podem entrar com a identidade corporativa via OIDC (Authorization Code + PKCE) ou SAML 2.0, com descoberta automática pelo domínio do e-mail. A configuração é feita no painel (Integrações → SSO), informando os metadados do seu IdP — Microsoft Entra ID, Google Workspace, Okta, Keycloak e equivalentes.

# Descoberta por domínio (sem autenticação)
GET https://api-dev.intellicreate.online/api
/api/sso/discover?domain=empresa.com.br
→ { "sso": true, "provider": "OIDC", "init_url": "..." }

# O navegador segue o fluxo do IdP; ao final a plataforma entrega a sessão
# por um ticket de uso único — nenhum token do IdP passa pelo frontend.

SCIM 2.0 — provisionamento automático

Conecte o provisionamento do seu IdP à base https://api-dev.intellicreate.online/api /scim/v2 com o token dedicado gerado no painel (Integrações → SCIM). Admissões criam o usuário, transferências atualizam departamento e cargo, desligamentos suspendem o acesso — sem nenhuma chamada manual. Suportamos Users com o schema enterprise (departamento, matrícula) nas operações padrão: GET, POST, PUT, PATCH e DELETE (soft delete → suspensão).

Dados pessoais são tratados conforme a LGPD, com a plataforma atuando como operadora dos dados do seu espaço. Relatórios de conformidade e acordos de tratamento de dados podem ser solicitados pelo canal comercial.

Dúvidas técnicas de integração, solicitação de ambiente de homologação ou reporte de problemas: comercial@intellicreate.online. Ao reportar um erro, inclua o request_id da resposta e o horário da chamada — com eles localizamos a requisição exata nos logs.

A especificação viva da API está sempre em Swagger UI e OpenAPI 3.1; em caso de divergência entre esta página e o OpenAPI, o OpenAPI prevalece.