Search…
AJUDA
API para integração com o eduplay
Este documento contempla a descrição dos pontos de integração disponíveis no eduplay. Tal descrição visa documentar como os web services devem ser chamados e especificar o funcionamento desses, de forma que seja verificado se atendem aos cenários esperados e identificar os próximos pontos de integração ou mesmo possíveis evoluções dos existentes.
Para que seja habilitado o acesso a API do eduplay será necessário entrar em contato com o service desk detalhando o cenário de uso da API.
Fale com o nosso Service Desk através do telefone/WhatsApp: 0800 722 0216 ou e-mail: [email protected]
Modelo de segurança / autenticação
Por questões mínimas de segurança, é esperada de as requisições de acesso aos serviços sejam realizados por meio de https. Além disso, no acesso aos web services estão previstos dois mecanismos de autorização: validação de chave de segurança e OAuth 2.0. A chave de segurança, nomeada como
clientkey, deve ser fornecida no header da requisição HTTPS e será validada pelo serviço. Caso a chave de segurança esteja incorreta ou não seja recebida, o web service retornará uma mensagem de erro no formato:1
<returnMessage>
2
<operationCode>107</operationCode>
3
<message>Application forbidden</message>
4
</returnMessage>
Copied!
Adicionalmente alguns serviços exigem, além da chave de segurança, a autorização seguindo protocolo OAuth 2.0. Nesse caso, os seguintes passos devem ser seguidos:
- Solicitar o código de autorização por meio do link https://eduplay.rnp.br/portal/oauth/authorize?response_type=code&client_id=
CLIENT_ID&scope=SCOPE&redirect_uri=CALLBACK_URL&state=STATE, em que:- response_type (obrigatório e valor fixo igual a 'code'): especifica que sua aplicação está solicitando um código de concessão de autorização;
- scope (obrigatório): especifica o nível de acesso que a aplicação está solicitando. Para os serviços os valores possíveis são: ws:read, que solicita acesso apenas de leitura e recuperação de informação por meio dos serviços, e ws:write, que solicita acesso aos serviços que adiciona, ou alteram informações no portal eduplay;
- client_id (obrigatório): é o identificador de cliente da aplicação (como a API identifica a aplicação);
- redirect_uri (opcional): é a URL de callback onde o serviço redireciona o agente do usuário depois que um código de autorização é concedido. A URL fornecida deve ser igual a uma das fornecidas no cadastro da aplicação no portal eduplay ou deve pertencer a um dos domínios cadastrados. Caso nenhuma URL seja enviada, o usuário será redirecionado para a URL cadastrada para a aplicação (caso exista), que nesse caso deve ser única. Caso não exista nenhum URL de callback cadastrada para a aplicação, o parâmetro redirect_uri passar a ser obrigatório;
- state (opcional mas altamente recomendado): é um parâmetro usado para proteger contra o CSRF (Cross-site request forgery). Seu aplicativo deve gerar uma string aleatória e a enviar para o servidor de autorização usando o parâmetro state. O servidor de autorização envia de volta o parâmetro de estado. Se os dois estados forem iguais, não hoube problema na requisição. Se os parâmetros de estado forem diferentes, outra pessoa iniciou o pedido. Para exemplo de como gerar e uso clique aqui.
- Quando o usuário clica no link, ele deve primeiro se autenticar no eduplay (a menos que ele já esteja logado). Em seguida ele será solicitado autorizar o acesso da aplicação à sua conta.
- No caso do usuário autorizar o acesso, o código de autorização será enviado para a URL de callback. O redirecionamento será algo parecido com
{redirect_uri}?code=AUTHORIZATION_CODE&state=STATE. IMPORTANTE: o código de autorização é para ser utilizado apenas uma vez e o tempo de vida desse código é de 10 minutos. - Com o código de autorização, a aplicação deve solicitar o token de acesso aos serviços por meio de requisição utilizando método POST para URL https://eduplay.rnp.br/portal/oauth/token com as seguintes informações:
- No header da requisição deve ser fornecido o
content-typeigual aapplication/x-www-form-urlencoded. - No corpo da requisição devem ser enviados o code contendo o código de autorização, o
client_id, aredirect_uri, o parâmetrogrant_typecom valor igual aauthorization_codee oclient_secretcom valor igual ao da chave de segurança (clientkey).
- Se a autorização for válida, a resposta recebida conterá o token de acesso juntamente com o tempo de expiração (em segundos) para os serviços, no seguinte formato:
1
{
2
"access_token": "ACCESS_TOKEN",
3
"expires_in": "TEMPO_EXPIRACAO",
4
"token_type": "bearer"
5
}
Copied!
- A aplicação está autorizada e as requisições aos serviços devem conter no header (além da clientkey) o token de acesso no parâmetro Authorization, no formato:
1
Authorization: Bearer ACCESS_TOKEN
Copied!
Last modified 2mo ago
Copy link