Conexão

Quando um dono autoriza um aplicativo, o HotLearn cria uma conexão: a ligação entre aquela conta e aquele aplicativo (e, se houver, aquele external_id). Ela aparece em Integrações, com o nome, quem autorizou, o que o aplicativo pode fazer e quando foi usado pela última vez.

Ver a conexão#

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

Resposta (resumida):

{
  "data": {
    "id": 7,
    "client": { "id": "01a13fdf-…", "name": "EstudioLMS" },
    "external_id": "42",
    "display_name": "Escola Exemplo",
    "url": "https://escola.exemplo.com",
    "open_url_template": null,
    "actions": [],
    "scopes": ["account:read", "catalog:read", "connection:write"],
    "authorized_by": { "name": "Ana Souza" }
  }
}

Ensinar ao HotLearn como abrir o seu lado#

Com o escopo connection:write, o aplicativo informa como o HotLearn abre uma ação nele. É daí que nasce o botão "Enviar para {display_name}" nos materiais da conta: a pessoa está no HotLearn, clica e cai na tela certa do seu aplicativo, já com o produto escolhido.

curl -X PUT https://hotlearn.com.br/api/v1/connection \
  -H "Authorization: Bearer $HOTLEARN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Escola Exemplo",
    "url": "https://escola.exemplo.com",
    "open_url_template": "https://escola.exemplo.com/hotlearn/enviar?produto={product}&material={material}&acao={action}",
    "actions": [
      { "key": "course", "label": "Criar um curso novo", "materials": ["apostila"] },
      { "key": "scorm",  "label": "Criar uma aula SCORM", "materials": ["scorm"] }
    ]
  }'

Regras:

• open_url_template precisa ser https e do mesmo domínio de url;
• use {product}, {material} e {action} onde precisar; o HotLearn troca pelos valores na hora de abrir;
• actions é a lista do que o seu aplicativo sabe fazer, até 10. materials diz para que tipo de material cada ação aparece: apostila, scorm ou quadro;
• campos que você não mandar continuam como estão. Para apagar um campo, mande null.

Com isso configurado, o HotLearn mostra o botão "Enviar para {display_name}" nos materiais compatíveis (listas e editores). A pessoa escolhe a ação, e o HotLearn monta o endereço no servidor e abre o seu aplicativo numa nova aba. O que você publicar depois (POST /publications) aparece como selo "Em {display_name}" no material.

Abrir o HotLearn já logado#

Para um botão "Editar no HotLearn" do seu lado, gere um link de entrada na hora do clique:

curl -X POST https://hotlearn.com.br/api/v1/login-links \
  -H "Authorization: Bearer $HOTLEARN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "coordenacao@escola.exemplo.com", "target": "material", "material_id": 161}'

O link vale 60 segundos e uma vez só. Quem já é membro da conta entra direto no editor; quem não é cai no login com o e-mail preenchido e, depois de entrar, vai ao destino. Por segurança, o dono da conta e os administradores do HotLearn nunca entram só com o link: vão ao login com o e-mail preenchido e, depois de entrar, seguem ao destino. Se alguém da mesma conta já estiver logado naquele navegador, segue com a própria sessão; se for alguém de outra conta, o HotLearn encerra essa sessão e pede o login. Limite: 30 links por minuto. No editor aparece "Voltar para {display_name}", que leva ao url da conexão. Precisa do escopo login_links:write.

Uma conexão por cliente#

Se o seu aplicativo atende vários clientes (as escolas de um LMS, por exemplo), mande external_id na autorização. Aplicativo cadastrado como de várias escolas é obrigado a mandar. Cada (conta, aplicativo, external_id) vira uma conexão separada, com chaves próprias, mesmo que o mesmo dono autorize as duas.

Ao conectar de novo o mesmo external_id com o mesmo redirect_uri, o HotLearn aprova sem tela e só emite uma chave nova (as antigas continuam valendo; nome e endereço não mudam). Para substituir a conexão (as chaves antigas param e o nome e o endereço são atualizados), mande prompt=consent, para o dono aprovar na tela. Detalhes em Autorização.