Inscription API

Para que serve?

• Consultar o progresso dos seus colaboradores nos cursos e trilhas de aprendizagem da Academia a partir dos seus próprios sistemas: reporting, dashboards internos, LMS/HRIS.

• Ver o detalhe de quais seções cada colaborador completou, seus resultados de quiz, e se está em dia, vencido ou por vencer.

Como se implementa?

Base URL: todos os endpoints vivem sob o prefixo {{base_url}}/api/companies/v1.

Para obter o host de produção (base_url), contate seu representante da Whalemate ou escreva-nos através do chat de suporte.

Autenticação: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Gere ou consulte sua chave em Configuração → Integrações → cartão Chaves API → Chaves Ativas. Detalhes em Chaves API: como gerá-las, usá-las e revogá-las.

A empresa é resolvida automaticamente a partir da API Key: você não envia company_id, e cada request opera apenas sobre as inscrições de colaboradores da sua empresa.

Importante: diferente da API de Funcionários, os filtros de texto desses dois endpoints são de correspondência exata, não LIKE parcial. Qualquer um deles também aceita um array de valores para fazer um OR entre vários (filter[department][]=Finanzas&filter[department][]=IT).

Endpoints

Inscrições em cursos

GET {{base_url}}/api/companies/v1/course-inscriptions

Paginado: retorna no máximo per_page inscrições por request, envolvidas em data/links/meta.

Exemplo Request:

GET {{base_url}}/api/companies/v1/course-inscriptions?filter[department]=Finanzas&filter[from_due_date]=2026-01-01&per_page=20

Resposta (200 OK):

{
  "data": [
    {
      "victim_name": "Juan Pérez",
      "victim_department": "Finanzas",
      "course_title": "Phishing 101",
      "start_date": "01/03/2026",
      "due_date": "31/03/2026",
      "status": "Completed",
      "victim_email": "[email protected]",
      "groups": ["Finanzas"],
      "victim_country": "Argentina",
      "events": [
        {
          "title": "Introducción",
          "section_type": "video",
          "completed_at": "2026-03-05 10:15:00",
          "result": null,
          "status": null
        },
        {
          "title": "Quiz final",
          "section_type": "quiz",
          "completed_at": "2026-03-05 10:22:00",
          "result": 8,
          "status": "approved"
        }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 20, "total": 134, "last_page": 7 }
}

status: Pending, About to expire (dentro dos 30 dias anteriores ao vencimento), Expired, Completed ou Deleted (colaborador desligado). start_date/due_date no formato d/m/Y.

events: mistura de seções completadas e resultados de quiz, ordenados por completed_at ascendente. Para uma seção normal, result e status vêm como null; para um quiz, result é a nota numérica e status é approved (nota > 5) ou disapproved.

Inscrições em trilhas de aprendizagem

GET {{base_url}}/api/companies/v1/learning-path-inscriptions

Mesmo formato que Inscrições em cursos, mas sobre trilhas de aprendizagem (conjuntos de cursos).

Resposta (200 OK):

{
  "data": [
    {
      "victim_name": "Juan Pérez",
      "victim_department": "Finanzas",
      "learning_path_title": "Onboarding de Seguridad",
      "start_date": "01/03/2026",
      "due_date": "30/04/2026",
      "status": "Pending",
      "victim_email": "[email protected]",
      "groups": ["Finanzas"],
      "victim_country": "Argentina",
      "courses": [
        {
          "title": "Phishing 101",
          "events": [
            {
              "title": "Introducción",
              "section_type": "video",
              "completed_at": "2026-03-05 10:15:00",
              "result": null,
              "status": null
            }
          ]
        },
        {
          "title": "Contraseñas seguras",
          "events": []
        }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 20, "total": 40, "last_page": 2 }
}

status aqui só pode ser Pending, Expired, Completed ou Deleted — as trilhas de aprendizagem não têm o estado About to expire.

courses: um objeto para cada curso que compõe a trilha, com seus próprios events (mesmo formato que em Inscrições em cursos). Um curso sem atividade ainda vem com events: [].

Erros comuns

Exemplo cURL

curl -X GET "https://api.whalemate.io/api/companies/v1/course-inscriptions?filter[department]=Finanzas&per_page=20" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

❓ Perguntas frequentes

• Enviei filter[department]=Fin esperando que trouxesse "Finanzas" e não trouxe nada. Esses filtros são de correspondência exata, não parcial. Você precisa enviar o valor completo tal como está armazenado (filter[department]=Finanzas).

• filter[teams] é o nome do grupo? Não, é o id numérico do grupo. Você pode consultá-lo na plataforma.

• filter[learning_path] aceita o ID da trilha? Não, espera o título exato da trilha de aprendizagem.

• Posso filtrar por vários valores ao mesmo tempo? Sim, a maioria dos filtros de texto/ID aceita um array (filter[country][]=Argentina&filter[country][]=Chile).

• Vem paginado? Sim, 20 por página por padrão (meta.per_page), ajustável com ?per_page= e navegável com ?page=.

• Onde consigo minha API Key? Em Configuração → Integrações → cartão Chaves API → Chaves Ativas.

Tem feedback ou quer solicitar melhorias? Nos avise em roadmap.whalemate.com/roadmap