Documentação e integração com o LMS

1. Valide o que o seu LMS precisa oferecer

Administração do Canvas: acesso para criar/habilitar Developer Keys LTI e instalar aplicativos na conta ou subconta dos cursos. Se esses menus não aparecem, solicite a configuração ao administrador do LMS.
LTI 1.3 com lançamento de recurso: a ferramenta deve receber usuário, papel, curso e identificação do item aberto. Um link comum para a página do aluno não fornece esse contexto.
Identificação: compartilhar o nome e os papéis do usuário. Configure os campos customizados canvas_course_id=$Canvas.course.id e canvas_user_id=$Canvas.user.id. Os valores precisam chegar como IDs numéricos. O e-mail pode ser compartilhado quando permitido pela instituição.
Rede e navegador: o endereço definitivo do DocCert deve usar HTTPS público e certificado válido. O servidor precisa acessar o OIDC/JWKS e, se necessário, a API REST do Canvas. Confirme que a política do LMS permite abrir a ferramenta; teste também em uma nova aba.
Regra de liberação: confirme se a instituição usará os pré-requisitos do módulo, a nota do Canvas ou a emissão manual. Para nota/conclusão, será necessário um token REST com acesso às matrículas e notas dos alunos do curso.

Identifique se o Canvas é Cloud de produção, beta, teste ou uma instalação própria. A tabela de ambientes está no passo 4. O funcionamento LTI e os endpoints estão descritos no fluxo oficial de lançamento do Canvas.

2. Prepare o DocCert antes de instalar no LMS

Responsável pela hospedagem: publique o DocCert no domínio que os alunos usarão. Configure a URL pública do aplicativo no ambiente de produção; depois de mudar variáveis na Vercel, gere uma nova implantação. Os links LTI, redirecionamentos e QR Codes devem usar esse endereço definitivo.
Responsável pela hospedagem: confirme Firebase Authentication, banco com isolamento por instituição e conexão do Google Drive. Faça login no ambiente publicado e teste o envio de um fundo e a geração do PDF. Ter as credenciais apenas no computador não configura o servidor publicado.
Equipe responsável pela implantação: confirme o cadastro da instituição e o vínculo de seu proprietário. O proprietário deve ter uma conta autorizada antes de configurar o LMS.
Proprietário da instituição: entre em Entrar e abra Painel → Equipe e integração. A URL de configuração exibida ali é exclusiva da instituição. Use essa URL no próximo passo.

Firebase, Drive e chaves do servidor são configurados pelo operador da plataforma. Cada instituição preenche os dados do seu Canvas no painel; seus usuários não precisam receber as credenciais da plataforma.

3. Cadastre a ferramenta no Canvas

Como administrador do Canvas, abra Admin → sua conta → Developer Keys → + Developer Key → + LTI Key. Dê um nome à chave e informe o responsável.
Escolha o método de configuração por URL e cole a URL de configuração automática do painel da instituição. Se sua interface aceitar apenas JSON, abra essa URL e copie o JSON completo. Confira a URI de redirecionamento: ela deve ser exatamente a URL de lançamento abaixo.
Confira que o cadastro permite compartilhar o nome e os papéis do usuário, mantém os dois campos customizados Canvas e inclui a ferramenta para seleção no curso. Salve e habilite a Developer Key. Copie seu Client ID.
Na conta/subconta que contém o curso, vá a Configurações → Apps → Ver configurações dos apps → + App. Selecione Por Client ID, cole o ID e instale.
No menu do app instalado, abra Deployment ID e copie o identificador completo. Ele identifica a instalação e pode mudar se você remover e reinstalar o app. Volte ao DocCert e conclua o passo 4.

Endereços que o Canvas recebe do DocCert

Os exemplos usam a URL pública configurada. Substitua ID_DA_INSTITUICAO pelo ID real; a tela Equipe e integração já mostra os endereços prontos para sua instituição.

Configuração JSON: https://doccert.walvors.com/api/lti/config/ID_DA_INSTITUICAO
Início de login OIDC: https://doccert.walvors.com/api/lti/login?institutionId=ID_DA_INSTITUICAO
Lançamento / Redirect URI: https://doccert.walvors.com/api/lti/launch
Chaves públicas do DocCert: https://doccert.walvors.com/api/lti/jwks

Consulte os guias oficiais para criar a chave LTI e instalar por Client ID e localizar o Deployment ID. Os nomes dos menus podem variar conforme a tradução e a versão do Canvas.

4. Preencha a integração da instituição

Em Equipe e integração, o proprietário ou administrador preenche estes seis campos com dados da mesma instalação do Canvas. Ao final, clique em Salvar configurações. O preenchimento dos campos não comprova conexão; faça os testes do passo 6.

Issuer: Identifica a plataforma que assina o acesso. No Canvas Cloud, use o issuer do ambiente na tabela do guia; ele pode ser diferente do domínio da sua instituição. Em instalação própria, confirme o valor de iss com o administrador do LMS.
Client ID: Copie o ID da chave em Admin → Developer Keys, depois de criar e habilitar a chave LTI. É o mesmo ID usado para instalar o aplicativo no Canvas.
Deployment ID: Depois de instalar o aplicativo, abra Configurações → Apps → Ver configurações dos apps → menu do DocCert → Deployment ID. Copie o valor completo dessa instalação.
Domínio Canvas da instituição: Informe a origem HTTPS usada para abrir o Canvas da instituição, sem /courses, /login ou outros caminhos. Esse endereço é usado para consultar notas e permitir a abertura dentro do LMS.
URL de autorização OIDC: É o endpoint de autorização do Canvas, usado para autenticar o lançamento. Use a URL do ambiente correto na tabela do guia ou a fornecida pelo administrador da instalação própria.
URL das chaves públicas do Canvas: É o endereço público das chaves do Canvas que validam a assinatura do acesso. Use o mesmo ambiente do issuer e da autorização. A URL JWKS do DocCert pertence ao cadastro da ferramenta no Canvas.

Endereços do Canvas Cloud por ambiente

Issuer, autorização OIDC e chaves públicas por ambiente Canvas Cloud
Ambiente	Issuer	Autorização OIDC / JWKS
Canvas Cloud · Produção	`https://canvas.instructure.com`	`https://sso.canvaslms.com/api/lti/authorize_redirecthttps://sso.canvaslms.com/api/lti/security/jwks`
Canvas Cloud · Beta	`https://canvas.beta.instructure.com`	`https://sso.beta.canvaslms.com/api/lti/authorize_redirecthttps://sso.beta.canvaslms.com/api/lti/security/jwks`
Canvas Cloud · Teste	`https://canvas.test.instructure.com`	`https://sso.test.canvaslms.com/api/lti/authorize_redirecthttps://sso.test.canvaslms.com/api/lti/security/jwks`

Para Canvas com hospedagem própria, solicite issuer e endpoints ao administrador. O domínio institucional é a origem HTTPS pela qual seus usuários acessam o LMS, por exemplo https://universidade.instructure.com. Consulte os endpoints e parâmetros oficiais do Canvas.

Token REST: necessário para nota e conclusão

O responsável autorizado no Canvas deve abrir Conta → Configurações → Integrações aprovadas → Novo token de acesso, identificar o uso como DocCert e definir validade conforme a política da instituição. Se a opção estiver bloqueada, o administrador do Canvas precisa conceder a permissão ou fornecer a credencial autorizada.

Cole o token no campo de senha do DocCert e salve. Depois de salvo, a tela informa que ele está configurado e não exibe seu valor. Deixar o campo vazio ao salvar mantém o token atual; preencher substitui. Registre a validade para renová-lo antes de expirar.

O usuário do token precisa conseguir consultar as matrículas e notas dos alunos do curso. A integração usa GET /api/v1/courses/:course_id/enrollments, filtrando o ID do aluno, e lê grades.current_score e enrollment_state. Se a política usar escopos REST, autorize esse endpoint. Os escopos LTI do JSON não substituem essa permissão.

Referências: obter e gerenciar tokens e permissões e resposta da API de matrículas.

5. Configure o curso e a liberação

No curso Canvas, adicione um item de Ferramenta externa no módulo e selecione o DocCert instalado. Publique o item e o módulo. O aluno deve abrir esse item dentro do curso para receber seu contexto LTI.
Abra a ferramenta com um professor ou administrador. O DocCert cria o curso no primeiro lançamento válido, inicialmente com emissão manual. Confira título, ID numérico e carga horária no painel; ajuste o curso correspondente em Regras de emissão.
Em Estúdio, envie PNG, JPG/JPEG ou PDF com uma ou mais páginas. Adicione nome do aluno e QR Code; escolha fontes, posições e páginas. Para assinatura, selo ou logotipo sobre o fundo, use Adicionar imagem; PNG sem fundo mantém a transparência. Gere o PDF de teste e clique em Salvar e ativar.
Escolha a regra abaixo, salve e faça um teste com aluno elegível e outro sem os requisitos. Conceda aos professores somente as permissões necessárias em Equipe e integração.

Acesso ao módulo

O Canvas controla o bloqueio pelos requisitos. Configure pré-requisitos, exigência de conclusão e sequência para impedir que o aluno pule diretamente para o certificado. Ao receber um acesso LTI válido ao item, o DocCert libera a emissão sem consultar notas.

Nota e conclusão

Defina a nota mínima de 0 a 100 e configure o token REST. O DocCert compara a nota atual (current_score). Ao marcar curso concluído, exige também matrícula com estado completed; concluir atividades do módulo, por si só, pode não gerar esse estado.

Emissão manual

A equipe autorizada emite pela aba Certificados emitidos. O acesso do aluno ao item LTI não cria um certificado automaticamente. Para associar a emissão ao aluno Canvas, informe seu ID numérico de usuário e escolha o curso correspondente.

6. Homologue antes de liberar para os alunos

Use um curso de teste e contas distintas de professor e aluno. Confira o nome real, as regras e todas as páginas do PDF. Os certificados emitidos no teste são registros reais: ao finalizar, revogue os de homologação com uma justificativa identificável.

Critérios para liberar

Aluno sem requisito não emite; aluno elegível recebe um único certificado; o PDF contém nome, curso, carga horária, imagens e QR Code corretos; o QR abre o registro público correto; a revogação aparece na consulta; usuários de outra instituição não acessam os arquivos ou o painel institucional.

Se algo não funcionar

A configuração JSON ou o JWKS não abre

Confira se a implantação está ativa, se a instituição já foi cadastrada e se o endereço público coincide com o registrado no Canvas. A equipe de hospedagem deve verificar as variáveis do ambiente publicado e gerar uma nova implantação após alterações.

Plataforma não reconhecida / lançamento não autenticado

Confira Developer Key habilitada, Client ID, issuer e URLs OIDC/JWKS do mesmo ambiente. Verifique também se o nome do usuário está sendo compartilhado.

Destino ou claims inválidos

Compare a Redirect URI com /api/lti/launch no domínio definitivo, sem diferenças de caminho. Confira o Deployment ID do app instalado e os campos customizados de curso/usuário. Após reinstalar o app, atualize o Deployment ID.

Lançamento expirado ou já utilizado

Volte ao curso e abra a ferramenta novamente. Cada lançamento vale por poucos minutos e só pode ser usado uma vez; recarregar a resposta antiga não inicia uma nova sessão.

A ferramenta não abre dentro do LMS

Confira o domínio Canvas da instituição, permissões de abertura e conteúdo HTTPS. Teste a opção do Canvas para carregar a ferramenta em uma nova aba e faça um novo lançamento pelo curso.

Aluno sem certificado ou nota não encontrada

Confira a regra selecionada, o template ativo e o curso correto. Para nota/conclusão, valide o token, sua validade e sua permissão de ler a matrícula do aluno. Confirme current_score e, quando exigido, enrollment_state=completed.

Origem da solicitação não permitida

Abra o DocCert pelo endereço configurado para esse ambiente. Na publicação, confira a URL pública e gere nova implantação depois da alteração. O cadastro no Canvas deve usar o mesmo domínio definitivo.

Imagem não é importada ou PDF não é gerado

PNG/JPG/JPEG e PDFs de várias páginas são aceitos, com até 50 MB por arquivo no aplicativo. Imagens até 400 MP são aceitas e as muito grandes são otimizadas mantendo proporção e transparência. Para PDF protegido, exporte uma cópia sem senha. Confirme também a conexão com o Drive no ambiente em uso; limites da hospedagem podem reduzir o tamanho de upload disponível.

Ao solicitar suporte, informe o ambiente, o curso, o horário e o texto do erro. Preserve tokens, senhas, chaves privadas e dados pessoais dos alunos.

Documentação oficial e próximos acessos

Os passos deste guia refletem o comportamento implementado no DocCert. Os links oficiais ao longo da página detalham as opções do Canvas. Confirme particularidades de instalações próprias com a equipe responsável pelo LMS.

Abrir painel Validar certificado

Do seu LMS ao primeiro certificado.