Materiais e arquivos

Depois que a conta adquire um produto (ou cria o próprio), o aplicativo pode ler os materiais dele e pedir os arquivos prontos para levar para outro lugar, como um curso SCORM para o LMS. Precisa do escopo materials:read e da assinatura ativa ou em teste.

Quais materiais o produto tem#

curl https://hotlearn.com.br/api/v1/products/136/materials \
  -H "Authorization: Bearer $HOTLEARN_KEY"

Cada material traz type (apostila, scorm ou quadro), source e formats:

• Matriz (apostila): se a escola personalizou a apostila, vem a versão dela (source: personalizada); senão, a original do acervo (original). Ler pela API nunca cria a versão personalizada.
• Curso SCORM (scorm): criado pela conta no HotLearn. Traz valid e errors: com erro, o pacote não sai.
• Quadro (quadro): aparece na lista, mas ainda não tem arquivo.

formats diz quais arquivos já dá para pedir daquele material: pdf na matriz; scorm12, scorm2004 e html5 no curso SCORM.

Quando a escola personaliza um produto do acervo, a matriz vira uma cópia com outro id (source passa de original a personalizada). Não guarde o id do material: liste de novo (GET /products/{id}/materials) antes de usar.

Saber se mudou#

GET /materials/{id} traz o material com as seções e o cabeçalho ETag. Guarde o ETag e mande de volta em If-None-Match: se nada mudou, a resposta é 304, sem corpo. A version muda toda vez que a escola salva o material.

curl -i https://hotlearn.com.br/api/v1/materials/161 \
  -H "Authorization: Bearer $HOTLEARN_KEY" \
  -H 'If-None-Match: "m161-1790850188"'

Pedir um arquivo: pedir, acompanhar, baixar#

Gerar um pacote pode levar alguns segundos, então funciona em três passos.

1. Peça (com Idempotency-Key):

curl -X POST https://hotlearn.com.br/api/v1/materials/162/exports \
  -H "Authorization: Bearer $HOTLEARN_KEY" \
  -H "Idempotency-Key: 6f1c2e8a-3b0d-4c55-9a7e-2f1d9b8c4a10" \
  -H "Content-Type: application/json" \
  -d '{"format": "scorm12"}'

• 202: o pedido entrou na fila (status: queued). Siga para o passo 2.
• 200: já havia um arquivo pronto da mesma versão e formato (status: ready). Vá direto ao passo 3.
• 422 scorm_invalid: o curso tem erros, listados em errors. Mostre à pessoa e peça para corrigir no editor SCORM do HotLearn.

2. Acompanhe a cada poucos segundos, até ready ou failed:

curl https://hotlearn.com.br/api/v1/exports/31 \
  -H "Authorization: Bearer $HOTLEARN_KEY"

3. Baixe:

curl -o curso.zip https://hotlearn.com.br/api/v1/exports/31/file \
  -H "Authorization: Bearer $HOTLEARN_KEY"

O arquivo fica disponível por 24 horas. Depois disso o pedido vira expired e o download responde 410: é só pedir de novo.

Formatos do curso SCORM#

format	Para quê
scorm12	SCORM 1.2, o mais aceito pelos LMS (Moodle, EstudioLMS e outros). Use este se não souber qual escolher.
scorm2004	SCORM 2004 (4ª edição), para LMS que pedem esse padrão.
html5	Pacote web sem SCORM, para publicar como página.

O pacote é o mesmo do botão Exportar do editor SCORM do HotLearn.

A apostila em texto#

GET /materials/{id}/content?format=html traz a apostila inteira; GET /materials/{id}/sections/{n}?format=html, um capítulo (o n é o index do sumário). O título do capítulo vem em title, fora do corpo, para virar o nome da lição.

O HTML de lição foi feito para colar em editores de LMS: só estrutura simples (títulos, parágrafos, listas, tabelas, citações e imagens) e as cores em estilo dentro das próprias tags. As caixas de destaque viram tabela de uma célula com fundo, que editores como o CKEditor 4 mantêm mesmo depois de editar. As respostas das perguntas vão num bloco Gabarito no fim.

Se o seu LMS usa CKEditor 4 e você quer manter as cores depois de editar, libere estas tags nas lições: config.extraAllowedContent = 'table td th p span h2 h3 ul ol li blockquote strong em img a iframe[*]{*}';

Para IA e ferramentas de texto, use format=markdown. Para guardar o documento do editor, format=json (só na apostila inteira).

O PDF sai pelo pedido de arquivo, com {"format": "pdf"} (apostila inteira) ou {"format": "pdf", "section": 2} (só o capítulo, sem capa nem sumário).

Provas#

GET /products/{id}/quizzes mostra a prova do produto e os formatos. GET /quizzes/{id}?format=csv-lms-estudio (ou csv-moodle) traz o CSV original, para importar com o importador da própria plataforma. format=json traz as perguntas com as alternativas e qual é a certa.

Registrar o que virou curso#

Depois de criar um curso, uma lição ou uma aula do seu lado, conte ao HotLearn:

curl -X POST https://hotlearn.com.br/api/v1/publications \
  -H "Authorization: Bearer $HOTLEARN_KEY" \
  -H "Idempotency-Key: 9b1f0c2e-7a44-4b0e-8d3c-5e6f7a8b9c0d" \
  -H "Content-Type: application/json" \
  -d '{"material_id": 161, "kind": "course", "title": "Turma A", "external_url": "https://escola.exemplo.com/cursos/77"}'

A publicação aparece para a escola na página Integrações do HotLearn. GET /publications diz se ela ficou para trás:

outdated	outdated_reason	Quando
false	null	Em dia. current_material_id é o próprio material_id.
true	updated	A escola salvou o material de novo.
true	personalized	A publicação saiu do original do acervo e a escola personalizou depois. A matriz dela agora é a cópia, cujo id vem em current_material_id.

Com outdated: true, é a hora de oferecer a atualização (a partir de current_material_id).

PATCH /publications/{id} muda só title, status e external_url (parts não muda). Não há DELETE: quando o curso for apagado do seu lado, mande PATCH com status = archived.