# 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.

{% hint style="info" %}
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: <atendimento@rnp.br>.

{% endhint %}

### 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 <mark style="color:red;">`clientkey`</mark>, 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=><mark style="color:red;">`CLIENT_ID`</mark>\&scope=<mark style="color:red;">`SCOPE`</mark>\&redirect\_uri=<mark style="color:red;">`CALLBACK_URL`</mark>\&state=<mark style="color:red;">`STATE`</mark>, 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](https://developers.google.com/identity/protocols/oauth2/openid-connect?hl=fr#createxsrftoken).
* 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 <mark style="color:red;">`{redirect_uri}`</mark>?code=<mark style="color:red;">`AUTHORIZATION_CODE`</mark>\&state=<mark style="color:red;">`STATE`</mark>. 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 <mark style="color:red;">`content-type`</mark> igual a <mark style="color:red;">`application/x-www-form-urlencoded`</mark>.&#x20;
  * No corpo da requisição devem ser enviados o code contendo o código de autorização, o <mark style="color:red;">`client_id`</mark>, a <mark style="color:red;">`redirect_uri`</mark>, o parâmetro <mark style="color:red;">`grant_type`</mark> com valor igual a <mark style="color:red;">`authorization_code`</mark> e o <mark style="color:red;">`client_secret`</mark> com valor igual ao da chave de segurança (<mark style="color:red;">`clientkey`</mark>).
* 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
```