Atenção: Esse artigo é para os administradores da plataforma. Caso você seja um aluno, favor entrar em contato diretamente com a instituição responsável pelo seu curso.
Este artigo é um para iniciantes, que visa fundamentar as principais particularidades da API da Eadbox. Tendo o conhecimento deste em mãos, ao lado de conhecimentos de programação, será possível criar automações e integrações de sistemas externos à Eadbox com o nosso sistema. Nossa documentação está disponível aqui.
Passo a passo
Nossa API é dividida em três partes principais, cada uma com seu respectivo nível de permissões e acesso à métodos diferentes: Métodos Públicos, Métodos de Aluno e Métodos de Admin. Tal qual o acesso à nossa plataforma, cada perfil tem suas respectivas permissões.
- Público: Métodos que não exigem autenticação, são métodos de criação de usuário, métodos de login, e métodos de listagem de informações que são públicas na plataforma (como cursos disponíveis, por exemplo).
- Aluno: Métodos respectivos apenas ao perfil do aluno que os executa, como por exemplo a listagem de cursos no qual este aluno está matriculado e qual o seu estado de visualização em uma determinada aula.
- Admin: Métodos de gestão da plataforma, onde é possível executar operações em várias partes da plataforma, criar cursos e salas de aula, listar pagamentos, dentre outras funções.
A chave principal para a autenticação na plataforma é chamada de "auth_token", e é uma string de caracteres única para cada usuário. Esta string é renovada de tempos em tempos, e para perfis de administrador, não expiram.
Ao utilizar a chave de autenticação de um perfil para executar uma chamada da API, todas as funções executadas na plataforma serão realizadas como se aquele perfil estivesse executando tal ação.
Como obter o auth_token de um perfil?
Há duas formas de extrair a chave de autenticação de um perfil: Via login, e via listagem de usuários com perfil de administrador. Há algumas características a serem notadas antes da execução de qualquer método:
- Todos os métodos devem seguir o seguinte formato: url_da_sua_plataforma.eadbox.com + /api/ + método + ? + parâmetro=valor + & + parâmetro=valor.
- Toda chamada da API deve conter /api após a url da plataforma.
- Parâmetros são passados após o método, depois de um "?"
- Parâmetros são passados no seguinte formato: parâmetro=valor
- Para casos onde há mais de um parâmetro, encadeá-los com o caractere "&" entre cada um.
Sabendo isto, para a obtenção de um auth_token, basta fazer o seguinte:
- Login: Tendo em mãos a url da plataforma, login e senha válidos, basta executar uma requisição do tipo POST, passando como parâmetros na url o login e senha conforme o seguinte exemplo: https://SUA-PLATAFORMA.eadbox.com/api/login?email=testeapi@eadbox.com&password=123456
O retorno é um objeto no formato JSON, conforme o seguinte exemplo:
Note o campo "authentication_token", o valor deste campo é a chave de autenticação para o usuário que foi logado.
Métodos de Aluno e métodos de admin exigem a presença de um token de autenticação de um perfil daquele tipo para a execução de qualquer método. Para inserir o auth_token de um perfil como parâmetro, basta seguir o seguinte exemplo:
https://SUA-PLATAFORMA.eadbox.com/api/MÉTODO?auth_token=zx6QK5M1wxSwaKMr0000
Admin: Tendo em mãos o auth_token de um admnistrador, para a extração dos auth_token de todos os alunos basta a execução de uma requisição GET como o seguinte exemplo:
https://SUA-PLATAFORMAcom/api/admin/users?auth_token=zx6QK5M1wxSwaKMr0000&page=1
O retorno é um conjunto de 100 objetos JSON, de acordo com a paginação. Cada objeto segue o seguinte exemplo:
Note a presença, novamente do auth_token, para aquele perfil da plataforma.
Para casos onde a requisição retorna um conjunto de dados maior que 100 os dados serão paginados. Para acessar novas páginas, basta inserir o parâmetro "page=" e o número da página que deseja acessar na url.
A diferença entre auth_token e user_ID
Todo usuário além da sua chave de autenticação, tem seu id. Este id é uma string única identificadora dentro da plataforma, e todas as operações a serem feitas para aquele usuário devem ser feitas utilizando este valor. A diferença primordial entre auth_token e user_id é que o token é para a AUTENTICAÇÃO de acesso e permissões do usuário na plataforma, e o id é utilizado para a execução de métodos para o respectivo usuário.
Introdução à API de integração da Eadbox
Caso ainda tenha ficado alguma dúvida, entre em contato com a nossa equipe de atendimento através do suporte@eadbox.com
Comentários
0 comentário
Artigo fechado para comentários.