> For the complete documentation index, see [llms.txt](https://ajuda.rnp.br/eduplay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.rnp.br/eduplay/video-sob-demanda/manual-de-integracoes/api-para-integracao-com-o-eduplay.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ajuda.rnp.br/eduplay/video-sob-demanda/manual-de-integracoes/api-para-integracao-com-o-eduplay.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.