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: [phone] ou e-mail: [e-mail].

Modelo de segurança / autenticação

Por questões mínimas de segurança, é esperada que 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:

<returnMessage>
	<operationCode>107</operationCode>
	<message>Application forbidden</message>
</returnMessage>

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 houve 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-type igual a application/x-www-form-urlencoded.

  • No corpo da requisição devem ser enviados o code contendo o código de autorização, o client_id, a redirect_uri, o parâmetro grant_type com valor igual a authorization_code e o client_secret com 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:

{
	"access_token": "ACCESS_TOKEN",
	"expires_in": "TEMPO_EXPIRACAO",
	"token_type": "bearer"
}

• 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:

Authorization: Bearer ACCESS_TOKEN