Como criar uma chave de API ou conectar um LMS com a POK

O painel Integrações é onde você conecta a POK Proof of Knowledge aos sistemas que já usa. Cada opção do painel gera uma destas duas coisas: uma chave de API para chamar a própria API da POK a partir dos seus sistemas, ou um registro LTI que você cola em um LMS para que ele solicite credenciais por conta própria. Escolha uma plataforma da lista, como Moodle ou Canvas, para uma configuração guiada, ou use "Integração personalizada" para gerar uma chave de API ou uma URL LTI simples para qualquer outro sistema.

Abra o painel Integrações

Você precisa do papel de administrador. "Integrações" só aparece no menu da barra superior para administradores; operadores e leitores não têm essa opção.

Na barra de navegação superior, clique no nome da sua organização e depois em "Integrações".

Você chega a duas seções: "Minhas integrações", com o que você já conectou, e "Lista de plataformas" logo abaixo, com cada plataforma que pode conectar. Uma coluna à esquerda traz um resumo curto ("Manual de integração") e, em "Documentação de integração", links para o guia de configuração de cada LMS da lista.

O que você pode conectar

A seção "Lista de plataformas" e a caixa de diálogo "Nova integração", aberta a partir de "Minhas integrações", oferecem as mesmas plataformas:

• Moodle (LMS): associe atividades do Moodle a modelos de certificados e emita-os automaticamente com a POK.
• Canvas (LMS): conecte o Canvas com a POK e emita certificados automaticamente baseados nas atividades de aprendizagem concluídas.
• OPEN edX (LMS): conecte seus cursos OPEN edX com a POK e emita certificados automaticamente baseados no progresso ou conclusão dos alunos.
• Blackboard (LMS): conecte o Blackboard com a POK e emita certificados automaticamente com base no progresso e desempenho dos participantes.
• D2L Brightspace (LMS): conecte seus cursos Brightspace com a POK e automatize a geração de credenciais com base no progresso e nas conquistas dos seus alunos.
• Sana (LMS): conecte seus cursos do Sana com a POK e emita credenciais automaticamente quando os alunos os concluírem. O Sana se conecta via xAPI, não via LTI.

Se o seu sistema não está nessa lista, abra "Nova integração" em "Minhas integrações" e escolha "Integração personalizada" ("URL LTI ou chave de API · qualquer sistema"). Ela gera uma chave de API simples ou uma URL LTI simples que funciona com qualquer sistema capaz de chamar uma API ou registrar uma ferramenta LTI.

Cada LMS da lista tem seu próprio guia de configuração: Moodle, Canvas, Blackboard, D2L Brightspace, Sana, Open edX.

Crie uma chave de API

1. Em "Minhas integrações", clique em "Nova integração".
2. Clique em "Integração personalizada".
3. No campo "Nome da integração", digite um nome que ajude a reconhecer essa integração depois, por exemplo o nome do sistema que você está conectando.
4. Selecione "Integração via chave API" ("Gere uma chave API para conexões diretas via nossa API a partir de sistemas externos").
5. Clique em "Confirmar".
6. Escolha a permissão que a chave terá: "Permissão de administrador" ("Poderá executar ações como emitir credenciais via API") ou "Permissão de leitura" ("Só poderá realizar consultas de leitura").
7. Clique em "Confirmar" novamente.

A POK gera a chave e a exibe em uma caixa de diálogo: "Esta é sua chave API. Copie-a e guarde-a, pois não poderá recuperá-la depois. Esta é a única vez que a verá." Depois que você fecha a caixa de diálogo, a chave em texto simples desaparece para sempre, o cartão dessa integração em "Minhas integrações" só a mostra mascarada a partir daí. Se você a perder, exclua a integração e crie uma nova; não há como recuperar o valor anterior.

A caixa de diálogo não deixa você fechá-la sem perceber: marque a confirmação de que já copiou a chave e a guardou em um lugar seguro antes que "Aceitar" fique habilitado.

O OPEN edX é a única exceção a esse fluxo. Ao clicar em "Conectar" no cartão dessa plataforma, os passos de nome e permissão são pulados por completo: a POK cria imediatamente uma chave chamada "OpenEdx" com permissão de administrador. Consulte o guia de integração com Open edX para saber o que fazer com ela do lado do Open edX.

O que uma chave de API pode fazer

Uma chave de API funciona como a credencial da sua organização para um sistema de computador: quem a tem pode chamar a API da POK como se fosse sua organização, por exemplo para emitir credenciais automaticamente. O que ela pode fazer depende da permissão que você deu a ela:

• Permissão de administrador pode executar ações de escrita, incluindo emitir credenciais via API.
• Permissão de leitura só pode realizar consultas de leitura.

Para entender como uma requisição comprova que tem uma chave válida, consulte autenticação da API. Para a lista completa de endpoints, comece pela referência da API. Depois de ter uma chave com permissão de administrador, emitir uma credencial via API e filtrar por tags é o próximo passo natural.

Registre uma integração LTI personalizada

Para gerar uma URL LTI simples em vez de uma chave de API, siga o mesmo fluxo de "Integração personalizada" e, no passo 4, escolha "Integração LTI" ("Gere uma URL para integração LTI e cole no seu LMS") em vez de "Integração via chave API". Um registro LTI não tem etapa de permissão.

A POK mostra a URL assim que você confirma: "Copie a URL abaixo e cole na sua plataforma compatível com LTI. Guarde para manter a conexão ativa com o POK." Diferente de uma chave de API, essa URL não é exibida só uma vez: você pode copiá-la de novo quando quiser clicando em "Copiar URL" no cartão dela dentro de "Minhas integrações". Uma integração personalizada como essa não guarda credenciais próprias para atualizar, então, se os dados de conexão mudarem, exclua-a e crie uma nova.

Gerencie suas integrações

Cada chave de API, registro LTI e conexão do Sana que você criou aparece como um cartão em "Minhas integrações". Uma chave de API ou uma conexão do Sana sempre mostra uma marca de verificação; um registro LTI mostra a marca quando está ativo, ou um ícone de link quebrado se nunca terminou de se conectar.

Altere a permissão de uma chave de API. Clique no ícone de edição do cartão. Ele reabre a mesma caixa de diálogo para escolher o tipo de permissão; escolha a outra permissão e confirme.

Atualize as credenciais do Canvas ou do D2L Brightspace. Clique no ícone de edição de qualquer um dos dois cartões para reabrir os campos de credenciais e reconectar. Para qualquer outra integração, exclua-a e crie uma nova se os dados de conexão mudarem.

Reconfigure o Sana. O ícone de edição dele não toca na conexão, ele abre a configuração de credencial curso a curso.

Exclua uma integração. Clique no ícone de lixeira do cartão.

• Uma chave de API é removida imediatamente, sem confirmação. Qualquer sistema que ainda a use para chamar a POK começa a ser rejeitado na hora.
• Um registro LTI ativo pede confirmação primeiro: "Você está excluindo uma integração ativa" e "Após a exclusão, você não poderá emitir certificados automaticamente desta plataforma. Tem certeza?" Um que nunca terminou de se conectar é removido imediatamente.
• Uma conexão do Sana sempre pede essa mesma confirmação antes de ser removida.

Depois de excluída, a plataforma do outro lado não consegue mais alcançar a POK por ela, e a emissão automática a partir dessa fonte é interrompida até você conectá-la de novo.

"Integrações" não aparece no meu menu

Só o papel de administrador vê "Integrações" no menu da barra superior. Se você tem o papel de operador ou de leitor, peça a um administrador da sua organização que crie a integração para você, ou que te dê o papel de administrador. Consulte usuários e permissões para ver o que cada papel pode fazer.

A POK diz que a plataforma rejeitou as credenciais

Isso aparece ao conectar o Canvas, o D2L Brightspace ou o Moodle, as plataformas em que a POK chama a plataforma para validar o que você digitou:

• "Por favor, revise os dados inseridos e tente novamente." Uma falha de validação genérica; revise todos os campos.
• "Não conseguimos nos conectar a essa plataforma. Verifique a URL e se o site está acessível publicamente." A POK não conseguiu alcançar o endereço informado.
• "A plataforma rejeitou estas credenciais. Verifique o token ou o segredo do cliente e se ele tem as permissões necessárias." O endereço respondeu, mas rejeitou o token ou o segredo do cliente.
• "Esse endereço respondeu, mas não é uma plataforma com a qual possamos integrar. Verifique se a URL aponta para o LMS e se é uma versão compatível." Algo respondeu, mas não é um LMS compatível.

Corrija o dado indicado na mensagem e tente de novo. Se aparecer um código de erro específico da plataforma abaixo da mensagem, guarde-o caso entre em contato com o suporte.