====== Orientações para Integração com o módulo de Orçamento Impositivo via API ======

===== 1. Processo de credenciamento para uso da API =====

Atualmente, a política de acesso via API do módulo de Orçameno Impositivo, está baseada nas mesmas regras de acesso dos usuários ao sistema, por isso, para utilização da API basta ter um usuário cadastrado no SIOP.

A solução de segurança da API utiliza as permissões do usuário conectado para autenticação e autorização de acesso. Portanto, o acesso às propriedades e operações do schema da API será disponibilizado de acordo com as permissões do usuário.

===== 2. Credenciais =====

Atualmente, não há necessidade de aquisição de credenciais ou envio de formulários para acesso à API, como no caso do web service. A solução de segurança da API utiliza o esquema de autenticação HTTP via token (**Bearer Authentication**). Portanto, para o acesso ao módulo de Orçamento Impositivo via API, basta o envio de requisições HTTP com o token de acesso, gerado para um usuário com acesso ao SIOP.

A API utiliza //GraphQL// como formato das requisições. Antes de solicitar qualquer informação é necessário obter o token do serviço de autenticação.
==== Como obter o Token de Acesso ====

O token de acesso pode ser obtido a partir de qualquer cliente HTTP, disponível nas bibliotecas da maioria das linguagens de programação. No exemplo a seguir é usado o utilitário //curl//, disponível em diversos sistemas operacionais.

   * Para obter o token usando o //curl//, basta realizar uma requisição //REST//  para a operação **login**, como no exemplo abaixo:

<code>
curl -k -X POST 'https://www.siop.planejamento.gov.br/modulo/login/rest/login'
 -H "Content-Type: application/json"
 -d '{"cpf": "<cpf do usuário>", "senha":"<senha do usuário>"}'

</code>

O retorno dessa requisição é o token, que deve ser passado no cabeçalho das demais requisições, tomando-se o cuidado de retirar as aspas.

^**ATENÇÃO!** O token de acesso tem validade de 48h.|
<code>

\\  ==== Como obter o Token de Acesso - Web-Service ====

</code>

O token de acesso pode ser obtido a partir de qualquer cliente HTTP, disponível nas bibliotecas da maioria das linguagens de programação. No exemplo a seguir é usado o utilitário //curl//, disponível em diversos sistemas operacionais.

  * Para obter o token usando o //curl//, basta realizar uma requisição //REST//  para a operação **login**, como no exemplo abaixo:

<code>
curl -k -X POST 'https://www.siop.planejamento.gov.br/modulo/login/rest/login'
 -H "Content-Type: application/json"
 -d '{"login": "<login do usuário>", "senha":"<senha do usuário>"}'

</code>

O retorno dessa requisição é o token, que deve ser passado no cabeçalho das demais requisições, tomando-se o cuidado de retirar as aspas.

^**ATENÇÃO!** O token de acesso tem validade de 48h.|

==== Como trocar a senha de acesso de um usuário ====

Caso seja necessária a troca da senha de acesso do usuário, pode-se utilizar a função de troca de senha, também via API do módulo de Orçamento Impositivo.

Para trocar da senha de acesso de um usuário, usando o //curl//, basta realizar uma requisição //REST//  para a operação **trocarsenha**, como no exemplo abaixo:
<code>

curl -k -X POST 'https://www.siop.planejamento.gov.br/modulo/login/rest/trocarsenha'
 -H 'Authorization: Bearer <token>' -H "Content-Type: application/json"
 -d '{"novasenha": "<nova senha do usuário>"}'

</code>

===== 3. Ambientes do SIOP para uso com a API =====

==== Ambiente de testes ====

Ambiente disponibilizado para testes de integração e utilização da API do módulo de Orçamento Impositivo.

^Recomenda-se, fortemente, a utilização desse ambiente para os testes necessários à fase de construção da solução de integração com a API, bem como, recomenda-se a boa prática de realização da homologação da solução, antes de sua disponibilização no ambiente de produção.|

Esse ambiente possui as seguintes características a serem consideradas:

  * **URL para acesso:** [[https://testews.siop.gov.br/|https://testews.siop.gov.br/]];
  * **Endpoints:**  consultar o Explorador de API's
  * **Origem do dados:**  os dados são obtidos por meio de cópia do ambiente de produção do SIOP;
  * **Periodicidade de atualização de dados:**  não existe período definido, os dados podem ser atualizados a qualquer momento devido a alguma necessidade interna da SOF ou por solicitação de algum cliente externo da API;
  * **Política de backup:**  não existe garantia de backup para esse ambiente;
  * **Formato de requisição para as operações dos serviços da camada de negócio da API:**
<code>

curl -k -X POST 'https://testews.siop.gov.br/modulo/impositivo/itens/api'
 -H 'Authorization: Bearer <token>' -H 'Content-Type:application/graphql'
 -d '<query, mutation ou subscription graphQL correspondente à operação desejada>'

</code>

==== Ambiente de produção ====

Ambiente disponibilizado para integração via API ao ambiente de produção do módulo de Orçamento Impositivo.

^Recomenda-se, fortemente, a utilização desse ambiente apenas por soluções de integração com a API que já estejam estáveis e homologadas.|

Esse ambiente possui as seguintes características a serem consideradas:

  * **URL para acesso:** [[https://siop.planejamento.gov.br/|https://siop.planejamento.gov.br/]].;
  * **Endpoints:**  consultar o Explorador de API's
  * **Origem do dados:**  dados do ambiente de produção do SIOP, **dados reais e "vivos"**;
  * **Periodicidade de atualização de dados:**  tempo real;
  * **Política de backup:**  mesma política de backup do SIOP;
  * **Formato de requisição para as operações dos serviços da camada de negócio da API:**
<code>

curl -k -X POST 'https://www.siop.planejamento.gov.br/modulo/impositivo/itens/api'
 -H 'Authorization: Bearer <token>' -H 'Content-Type:application/graphql'
 -d '<query, mutation ou subscription graphQL correspondente à operação desejada>'

</code>




===== 4. Explorador de API's =====

O [[https://siop.planejamento.gov.br/modulo/main/static/api-explorer.html#impositivo/itens|Explorador de API's]] é uma ferramenta disponibilizada para auxiliar integrações com o SIOP. Para acessá-la, é necessário se ter um usuário cadastrado no SIOP com a devida permissão.

Nela é possível testar a API e acessar a documentação do código mais atualizada.

Veja aqui [[https://www.youtube.com/watch?v=Yv6GmTdq5YE|vídeo explicativo]] de como usá-la.