Documentação da API
Conectar um assistente (MCP)
O HotLearn tem um servidor MCP: o jeito padrão de ligar um assistente de IA (Claude, ChatGPT, Claude Code, Cursor…) a um serviço. Conectado, o assistente enxerga a sua conta: procura no acervo, lê as apostilas, pede PDFs, baixa provas, cria produtos, escreve apostilas, provas e páginas de vendas e, com a sua aprovação, adquire produtos e publica páginas.
Endereço
| Endereço | Quando vale |
|---|---|
https://hotlearn.com.br/mcp |
Sempre. |
https://mcp.hotlearn.com.br |
Quando o endereço próprio estiver ligado no servidor do HotLearn. |
Os dois levam ao mesmo servidor e à mesma conta; escolha o que o seu assistente aceitar. O login e a autorização são sempre feitos no HotLearn.
Duas formas de conectar
- Entrar com a sua conta (OAuth). Claude (site e aplicativo), ChatGPT e outros assistentes que aceitam "conectores" se cadastram sozinhos no HotLearn. Você só cola o endereço, o assistente abre a tela de autorização do HotLearn e você confere o que ele pede antes de aceitar. Esse cadastro automático aparece como não verificado: autorize só quando foi você quem pediu a conexão.
- Chave pessoal. Para ferramentas no seu computador (Claude Code, Cursor). Você cria a chave em Integrações (Chaves pessoais) e o assistente a envia em cada chamada. Para o assistente usar tudo o que está neste guia, marque na chave: ver o plano e o saldo, ver o acervo e a biblioteca, ler e baixar os materiais, ver e fazer aquisições, criar e editar seus produtos, criar e editar seus materiais, escrever e publicar suas páginas de vendas.
Atenção com a chave pessoal: ela também abre a API comum do HotLearn, não só o MCP. Com a opção fazer aquisições marcada, um assistente que executa comandos no seu computador (como o Claude Code) consegue comprar produtos direto pela API, sem passar pela tela de aprovação. Se você não quer esse risco, crie a chave do assistente sem o escopo de aquisição. O preço dessa escolha: sem o escopo,
adquirir_produtotambém não funciona (pedir a compra com aprovação exige o escopo), e as compras ficam por sua conta na tela do HotLearn.
Em qualquer das duas, o assistente age como o dono da conta e só pode o que a autorização ou a chave permite (Escopos). Para desligar, desconecte o aplicativo ou revogue a chave em Integrações.
Passo a passo
Claude (site e aplicativo)
- Abra Configurações › Conectores e escolha Adicionar conector personalizado.
- Informe o nome (ex.: HotLearn) e o endereço
https://hotlearn.com.br/mcp. - Clique em Conectar, entre no HotLearn se pedir e autorize.
ChatGPT
- Em Configurações › Conectores, ative o modo desenvolvedor (o ChatGPT só aceita conector próprio assim) e crie um conector novo.
- Informe o nome e o endereço
https://hotlearn.com.br/mcp, com a autenticação OAuth. - Conecte e autorize no HotLearn.
Claude Code (chave pessoal)
export HOTLEARN_KEY="cole-a-chave-aqui"
claude mcp add --transport http hotlearn https://hotlearn.com.br/mcp \
--header "Authorization: Bearer $HOTLEARN_KEY"
Cursor (chave pessoal)
No arquivo ~/.cursor/mcp.json (ou .cursor/mcp.json do projeto):
{
"mcpServers": {
"hotlearn": {
"url": "https://hotlearn.com.br/mcp",
"headers": { "Authorization": "Bearer ${env:HOTLEARN_KEY}" }
}
}
}
Os menus mudam de uma versão para outra dos assistentes; o que não muda é o endereço e a chave. Teste pedindo: "Qual é o meu saldo de créditos no HotLearn?".
O que o assistente consegue fazer
| Ferramenta | O que faz |
|---|---|
ler_guia |
O guia de um tema (apostila, pagina-vendas, prova, scorm ou quadro): formato, limites e ordem das ferramentas. O assistente chama antes de criar ou editar. Nunca gasta créditos. |
meu_saldo |
Mostra o plano, o saldo de créditos e quanto custa cada ação feita pela IA. Não gasta créditos. |
buscar_acervo |
Procura no acervo por tema, categoria, nível ou formato. Mostra o custo e se o produto já é da conta. |
minha_biblioteca |
Lista os produtos adquiridos e as criações da conta. |
ver_produto |
Descrição, sumário, custo e licença de um produto. |
ver_licenca |
Texto da licença comercial, para ler antes de aceitar. |
listar_materiais |
Materiais (apostila, SCORM, quadro), provas e itens soltos de um produto adquirido. |
ler_material |
Lê o texto de uma apostila, um capítulo por vez (ou a apostila inteira em JSON, para gravar_json; o JSON traz as imagens em base64 e pode ser grande). |
gerar_arquivo |
Pede o arquivo de um material: PDF, HTML ou JSON da apostila (PDF também por capítulo) e SCORM 1.2, SCORM 2004 ou HTML5. |
ver_arquivo |
Acompanha o pedido e, quando pronto, traz o link para baixar. |
baixar_prova |
A prova de um produto, em JSON ou em CSV (LMS Estúdio, Moodle ou genérico). |
adquirir_produto |
Pede para adquirir um produto do acervo. Só acontece com a sua aprovação. |
ver_pagina_vendas |
Mostra a página de vendas de um produto (ou os padrões sugeridos) e a versão para gravar. Nunca mostra código livre. |
escrever_pagina_vendas |
Grava campos da página de vendas (texto, oferta, FAQ, SEO, cores, IDs de rastreamento) sobre a versão lida. Não escreve código livre nem publica. Em página já publicada, a mudança só acontece com a sua aprovação. |
publicar_pagina_vendas |
Pede para publicar a página de vendas. Só acontece com a sua aprovação. |
relatorio_pagina_vendas |
Visitas da página publicada em 7, 30 ou 90 dias. |
criar_produto |
Cria um produto seu, sempre como rascunho privado (nada é publicado). |
editar_produto |
Altera os dados de um produto seu; não muda a situação nem mexe no acervo. |
publicar_produto |
Muda um produto seu de rascunho para publicado. Não pede aprovação: no produto da conta isso não deixa nada público (a página de vendas tem publicação própria). |
definir_capa |
Troca a capa de um produto seu pela imagem de um link https (recorte 9:16). |
criar_apostila |
Cria a apostila de um produto seu, do modelo do HotLearn ou do texto enviado. |
ver_estrutura |
Capítulos, capa, autor, contracapa e tema de uma apostila, com a versão para gravar. |
escrever_capitulo |
Grava um capítulo (troca, insere ou acrescenta) sobre a versão lida; o resto da apostila não muda. |
editar_capa, editar_autor, editar_contracapa, editar_tema |
Textos e imagens da capa, página do autor, contracapa, cores e fontes. Imagem vai por link https: o HotLearn baixa e recorta como o editor. |
inserir_imagem |
Põe a imagem de um link https no início ou no fim de um capítulo da apostila. |
preparar_envio_imagem |
Cria um link de envio (60 min, uso único) para a imagem que está no computador do assistente; depois o mesmo link vale como link da imagem nas outras ferramentas. |
gravar_json |
Grava a apostila inteira no JSON que ler_material devolve (formato json), sobre a versão lida: para mudanças em vários lugares ou na estrutura. O que está igual volta como está; JSON igual ao atual não grava nem cobra. |
personalizar_do_acervo |
Abre a cópia da sua conta da apostila de um produto do acervo. O original nunca muda. |
restaurar_original |
Pede para voltar a cópia ao original do acervo. Só acontece com a sua aprovação. |
criar_prova |
Cria a prova de um produto seu a partir das questões; o HotLearn gera o CSV do LMS Estúdio e o do Moodle. |
criar_curso |
Cria um curso SCORM num produto seu (ou do acervo adquirido) a partir de telas de blocos prontos (capa, texto com imagem, abas, quiz…), no template e na paleta escolhidos. |
editar_tela |
Grava uma tela do curso (troca, cria ou move) sobre a versão lida; o resto do curso não muda. |
verificar_curso |
Confere o curso antes do pacote (erros e avisos) e traz o curso inteiro com a versão para gravar. |
criar_diagrama |
Cria um quadro com um fluxograma, organograma ou mapa mental a partir do grafo (nós e ligações); o HotLearn calcula as posições e o quadro abre pronto no editor. |
criar_plano_de_aula |
Cria um quadro com o plano de uma aula em várias seções: mapas mentais, fluxogramas, organogramas, notas do roteiro e texto. No Apresentar, uma seção por vez. |
ler_diagrama |
Lê o diagrama de um quadro (feito pelo assistente ou à mão) como grafo, sem posições, e diz quantas peças ficaram de fora. |
reorganizar_diagrama |
Rearruma as peças do diagrama sobre a versão lida; imagem, desenho e notas ficam onde estão. |
apagar_rascunho |
Pede para apagar um produto, material ou prova que um assistente criou e que ainda é rascunho. Só acontece com a sua aprovação, e o item fica 30 dias em Itens apagados pelo assistente. |
ver_aprovacao |
Mostra como ficou um pedido de aprovação. |
Os links de download são temporários: valem 15 minutos e baixam direto no navegador, sem chave. Passou o prazo, peça de novo com ver_arquivo.
Imagens por link. definir_capa, inserir_imagem, as imagens de editar_capa/editar_autor e do curso SCORM (criar_curso, editar_tela) e as imagens  escritas no texto da apostila são baixadas pelo HotLearn e guardadas no material. Só vale link https:// público e direto da imagem: JPEG, PNG, WebP ou GIF, até 10 MB e 25 milhões de pixels. Link http://, com usuário ou senha, com outra porta, que redireciona, que aponta para rede interna ou que demora mais de 10 s é recusado (image_rejected, com o motivo). Cada chamada tem 25 s para baixar todas as suas imagens. No texto da apostila, no máximo 10 links novos por gravação; no gravar_json, no máximo 10 imagens novas por gravação, somando links e data:image/…; no curso SCORM, no máximo 10 imagens novas (links ou data:image/…) por criar_curso ou editar_tela. A imagem recusada sai com aviso e o resto é gravado.
Imagem sem link público. Para a imagem que está no computador do assistente (gerada por código, por exemplo), preparar_envio_imagem devolve um upload_url de uso único, válido por 60 minutos e só da sua conta. O assistente manda o arquivo com PUT (curl -T imagem.png "<upload_url>") ou POST com o campo file e depois usa o mesmo link onde as ferramentas aceitam o link de uma imagem. Mesmas regras de tipo e tamanho; não gasta créditos. Só funciona em assistentes que acessam a internet pelo próprio ambiente (Claude Code, Cursor, Claude Desktop com acesso ao computador); nos outros, use o link público da imagem (o de um gerador de imagens serve).
Guias e receitas
O assistente aprende o jeito de escrever no HotLearn pelos guias (ler_guia ou os recursos hotlearn://guias/apostila, hotlearn://guias/pagina-vendas, hotlearn://guias/prova, hotlearn://guias/scorm e hotlearn://guias/quadro): o Markdown estendido das apostilas, os campos da página de vendas, o formato das questões e as regras de uma boa prova, os templates, blocos e campos do curso SCORM, e o formato dos diagramas do quadro. Uma apostila também pode ser aberta como recurso (hotlearn://materiais/{id}), com as mesmas regras e o mesmo custo de ler_material.
As receitas são pedidos prontos que aparecem no assistente (em geral no menu de comandos ou de prompts):
| Receita | O que faz |
|---|---|
produto_completo |
Produto novo com apostila, prova e página de vendas, a partir de um tema e de um público. |
adaptar_apostila |
Reescreve a apostila de um produto para o seu público, capítulo por capítulo. |
pagina_de_vendas |
Escreve a página de vendas de um produto a partir do que a apostila entrega. |
prova_do_material |
Prova de múltipla escolha (padrão: 10 questões) tirada de uma apostila. |
Tudo pode ser desfeito
Antes de cada gravação do assistente (capítulo, capa, página de vendas…), o HotLearn guarda a versão anterior. Para voltar, abra o editor da apostila ou da página de vendas e use o botão Histórico. Se você estiver com a tela aberta e o assistente gravar, a tela avisa antes de salvar por cima.
Aprovações: o que só você decide
Seis ações só acontecem com a sua aprovação: adquirir um produto (adquirir_produto), publicar a página de vendas (publicar_pagina_vendas), mudar uma página de vendas que já está no ar (escrever_pagina_vendas numa página publicada: o resumo mostra o que muda), voltar uma apostila ao original do acervo (restaurar_original), apagar um rascunho criado pelo assistente (apagar_rascunho) e, quando a regra da ação pede, confirmar uma cobrança de créditos. O assistente nunca faz nenhuma delas sozinho. O caminho, no exemplo da compra, é este:
- O assistente chama
adquirir_produto. A resposta não é uma compra: vemstatus: pending, um resumo (produto, custo e saldo depois) e um link. - Ele mostra o resumo e o link para você.
- Você abre o link (ou Aprovações no menu do HotLearn), confere e aprova ou recusa. Aprovar significa aceitar a licença do produto. Só o dono da conta decide.
- Você avisa o assistente, e ele consulta com
ver_aprovacao:pending(esperando),executed(feito, com o resultado),denied(recusado),expired(venceu) oufailed(deu erro, com o motivo emerror_code).
O pedido vale 30 minutos; depois disso vence e é preciso pedir de novo. Pedir duas vezes a mesma coisa reaproveita o mesmo pedido aberto. Produto que a conta já tem responde already_owned, sem aprovação.
Apagar rascunho. O assistente só apaga o que um assistente da sua conta criou, que ainda é rascunho e que ninguém mexeu pela tela; um produto, além disso, não pode ter sido adquirido, nem ter página de vendas no ar ou material feito pela tela. Fora disso ele recebe o motivo (not_assistant, not_draft, edited_on_screen, has_acquisitions, has_published_sales_page, has_manual_materials ou other_account) e nem chega a pedir. Apagar o produto leva junto os materiais, a prova e a capa que o assistente criou nele. O que foi apagado fica 30 dias em Meus Produtos → Itens apagados pelo assistente, com o botão Restaurar; depois disso é apagado de vez.
Quando a aprovação é só a confirmação de uma cobrança, aprovar apenas libera a ação: nesse caso ver_aprovacao mostra released: true e o assistente deve repetir a mesma chamada, com os mesmos argumentos, para a ação rodar (a liberação vale uma vez).
Créditos
Criar pelas telas do HotLearn não gasta crédito; criar por um assistente de IA pode gastar, conforme a tabela de uso da conta (que começa sem cobrar). Cada ação do assistente (consultar o acervo, ler um material, gerar um arquivo, adquirir um produto, criar, publicar ou apagar um produto, criar ou escrever a apostila, escrever a página de vendas, criar a prova, criar, editar ou verificar o curso SCORM, criar, ler ou reorganizar o diagrama do quadro) tem o seu valor na tabela de uso da conta, e o que sai do saldo é o que a tabela diz. O assistente vê essa tabela em meu_saldo e pode avisar o custo antes de agir. Enquanto uma ação está em simulação, o uso é contado mas nada sai do saldo. Valores, franquia do mês e limite por dia estão em Créditos e limites de uso.
No MCP vale sempre a tabela do MCP, mesmo quando a conexão é feita com uma chave pessoal.
Algumas ações podem pedir a sua aprovação antes de cobrar: quando isso acontece, o assistente avisa, mostra o link e nada é gasto até você aprovar em Aprovações. Aprovou? Ele repete o pedido e só então o crédito sai (a aprovação vale uma vez, para aquele pedido).
Erros das ferramentas
Quando algo não pode ser feito, a ferramenta responde com erro e um texto em JSON com dois campos principais (e, quando houver, os mesmos detalhes da API, como current_version ou errors): code (estável, serve para decidir o que fazer) e detail (a frase para mostrar à pessoa). Os mais comuns:
code |
Quando |
|---|---|
insufficient_scope |
A autorização ou a chave não tem o escopo que a ferramenta pede. |
not_found |
O produto, o material ou o arquivo não existe ou é de outra conta. |
not_acquired |
O produto ainda não foi adquirido. |
insufficient_credits |
O saldo não cobre a ação. |
daily_limit_reached |
A conta chegou ao limite de hoje para a ação. |
format_unavailable |
O material não exporta nesse formato (o quadro, por exemplo). |
precondition_required |
A escrita veio sem a versão lida (versao): o assistente lê antes e grava com a versão. |
version_mismatch |
O conteúdo mudou depois da leitura (você ou outra chamada gravou): o assistente lê de novo e grava sobre a versão atual (o erro traz a current_version). |
content_too_large |
O texto passou do limite (um parágrafo muito longo, por exemplo): o assistente divide e tenta de novo. |
Segurança
- O assistente só enxerga a sua conta; nunca a de outra pessoa.
- Compras e outras decisões de peso passam pela sua aprovação na tela do HotLearn.
- Um aplicativo cadastrado automaticamente por um assistente só funciona no MCP: na API comum ele recebe
403comcode=mcp_client_only. - Para cortar o acesso na hora: Integrações › desconectar o aplicativo ou revogar a chave.
