Conhecendo uma API
Antes de iniciar o consumo das APIs Dataprev é altamente recomendado ler a documentação da API recebida em conjunto com essa orientação.
A documentação da API contempla a descrição das definições da API, incluindo suas operações, parâmetros, dados e códigos de resposta. São apresentados conceitos de negócio associados ao funcionamento da API que possam afetar sua utilização pelo parceiro da Dataprev.
Na documentação da API também é descrita a API de degustação utilizada para testes durante o desenvolvimento, incluindo os dados fictícios disponibilizados.
Consumindo uma API de degustação
As APIs de degustação (APIs Mocking) são disponibilizadas para que os desenvolvedores possam implementar e testar suas aplicações. Estas APIs contemplam as mesmas definições da API a ser utilizada em ambiente produtivo, porém as APIs de degustação utilizam dados fictícios e estão disponibilizadas para uso público com limites de requisição predefinidos. A seguir será apresentado um exemplo de consumo de uma API de degustação utilizando o aplicativo Postman.
Obtendo a definição da API de degustação
Inicie acessando o portal de desenvolvimento disponível no endereço https://devportal.dataprev.gov.br. Acesse o menu APIs e selecione a API de degustação desejada.
Na aba operações da API, no link /swagger.json, clique com o botão direito do mouse e selecione a opção Salvar link como, escolha um diretório no seu computador e nomeie o arquivo, por exemplo, “contrato.js”.
Realizando um teste com o Postman
Após a obtenção do contrato da API é possível realizar testes com a API de degustação, utilizando, por exemplo, o aplicativo Postman. Iniciando, realize a importação do contrato da API no Postman. Acesse o menu File, opção Import.
Clique no botão Upload Files, então selecione o arquivo salvo na seção anterior.
Na tela seguinte selecione Show advanced setting.
Nas opções request parameter generation e response parameter generation selecione Schema. Acione o botão Import e posteriormente o botão Confirme and Close.
Na aba Collections selecione a coleção para configuração de segurança e obtenção do Access Token. Inicie, na aba Authorization, selecionando OAuth 2.0 no campo Type.
Entre em Settings (engrenagem no canto superior direito), e em seguida desmarque a opção SSL certificate verification e feche a janela.
Na aba Authorization, em Configure new token, dê um nome para o token no campo Token name. Em Grant Type, selecione Client Credentials. Em Access Token URL informe a URL https://api.dataprev.gov.br/token. Informe os valores nos respectivos campos, como abaixo:
- Client ID informe o Consumer Key: V_h32rLjOsvOm2gPGoU3_dQwtoMa
- Client Secret informe o Consumer Secret: Wumr_sDUCjNuLdlx8rTSy8lU5NAa
Acione o botão Get New Access Token.
Caso a API tenha definido escopos customizados para acesso a recursos e operações, será necessário informar o escopo, em Scope, para geração do token.
Após a obtenção do token aparecerá uma tela confirmando a requisição de um novo token.
Acione o botão Use Token.
Configurado o token de acesso, é hora de testar as operações da API. As operações podem ter como entrada um ou mais parâmetros dos tipos Path ou Query, que devem ser informados na aba Params.
Algumas operações podem receber um objeto json de entrada com um conjunto de dados. Quando for o caso, este objeto deve ser informado na aba Body. As operações da API, com seus parâmetros e respostas são descritos na documentação da API, fornecida em conjunto com esta orientação.
Para realizar o teste da operação da API é necessário fazer uso do token de acesso configurado nos passos anteriores. Então, no Postman, na aba Auth, opção Type, selecione OAuth 2.0 e em Access Token selecione o token (nome) configurado. Para finalizar acione o botão Send para realizar a requisição.
Realizando a subscrição de uma API
Com a conclusão do desenvolvimento e o início da promoção da aplicação para o ambiente de produção, é necessário realizar a subscrição da API contratada. Para realizar a subscrição é necessário acessar o portal de desenvolvimento, cadastrar uma aplicação e realizar a subscrição da API. Estes passos serão detalhados a seguir.
Acessando o portal de desenvolvimento
O primeiro passo para realizar o consumo de uma API Dataprev inicia com a solicitação de cadastro feita por meio do gerente de contas. Após a realização do cadastro, o parceiro receberá um e-mail com link para alterar a senha de acesso ao portal de desenvolvimento.
O acesso ao portal é realizado por meio do endereço https://devportal.dataprev.gov.br. Para iniciar, basta acessar a opção Entrar e, na nova tela, informar o CPF, a nova senha e clicar no botão SIGN IN:
1.3.2- Cadastrando uma aplicação
Após acessar o portal de desenvolvimento, será necessário cadastrar uma aplicação. Acesse o menu Aplicações, em seguida Adicionar aplicação. Informe o nome da aplicação e acione o botão Adicionar.
Para finalizar o cadastro da aplicação é preciso gerar as chaves que serão utilizadas para obtenção de tokens de acesso. Acesse a aba Chaves de Produção, marque os Grant types Client Credential e Refresh Token, e acione o botão Gerar Chaves.
Atenção: As chaves da aplicação (Consumer key e Consumer Secret) utilizadas para realizar a subscrição da API devem ser protegidas de acesso não autorizado.
Grant types: São fluxos por meio do qual aplicações podem obter tokens para acesso a APIs, seus recursos e operações. O protocolo OAuth 2.0 oferece vários fluxos. A figura abaixo apresenta o grant type Client Credential, recomendado para uso na comunicação entre aplicações:
Subscrevendo a API
Realizado o cadastro da aplicação, é necessário realizar a subscrição da API. Para realizar a subscrição, acesse o menu APIs e selecione a API desejada.
Ao acessar a API, no canto superior direito, selecione a aplicação criada, plano de consumo disponível e acione o botão Subscrever.
Concluído o processo de subscrição de uma API, o passo final é configurar a aplicação cliente com a Consumer Key e Consumer Secret geradas e também com a URI da API subscrita. Concluído estes passos a aplicação estará pronta para consumir uma API Dataprev.