Guia rápido – Integração APIs

Dúvidas e atendimento
atend.consignadoapi@dataprev.gov.br

Cadastramento de usuários

O primeiro passo, após a finalização dos trâmites contratuais, é o cadastramento de usuários pessoa física na base de dados da Dataprev: as instruções do cadastramento estão descritas no manual 07 – Subscrição de API e-Consignado.
Com o usuário e sua respectiva senha em mãos, passamos ao próximo passo.

Apresentação Marketplace

As APIs do eConsignado estão disponibilizadas através de nossa Marketplace. Essa loja fornece uma interface colaborativa contendo todas as informações necessárias para integração técnica com os serviços, desde documentação, até o processo de subscrição, autenticação e utilização destes.
O foco, nesse primeiro momento, são os itens de menu:

APIs – onde estão postos os serviços disponibilizados para subscrição:
- APIs disponíveis
  - eConsignado v7.0.0
- Importante estar atento nas informações de cada uma das APIs publicadas:
  - Na aba “Visão Geral” temos o endereço de chamada para os serviços, descrição da API e informações comerciais;
  - Na aba “Console de API”, além de informações visuais de cada um dos serviços disponibilizados, temos o Swagger disponível para download.
Aplicação – que é uma coleção lógica de APIs. As aplicações permitem que você use um único token de acesso (obtido através da chave e segredo do consumidor) – para invocar uma ou mais APIs.

Subscrição nas APIs

Autenticando-se no ambiente da Marketplace, deve-se seguir os passos abaixo (maiores detalhes em 07 – Subscrição de API e-Consignado):

Cadastramento de aplicação
- Acesse o menu “Aplicações”;
- Clique no botão “Adicionar aplicação”;
- Preencha o nome* da aplicação e clique no botão “Adicionar”.
- * Padrão: EC_NomeDoBanco_CBCdoBanco – Exemplo: EC_BancoTeste_999.
Geração de chaves para obtenção de token de acesso
- Acesse a aplicação criada no passo anterior;
- Clique na aba “Chaves de Produção” e, já dentro da aba, clique em “Gerar Chaves”;
- O sistema apresentará as chaves e os comandos para geração do “token de acesso”, o qual deverá ser no Header da requisição HTTP para acessar as operações das APIs.
- Importante: clique no botão “Mostrar chaves” para ver o comando pronto a ser utilizado na obtenção do “token de acesso”.
Subscrição nas APIs
- Acesse a API eConsignado v7.0.0;
- Selecione a aplicação criada no passo anterior;
- Selecione o plano de consumo disponível para subscrição;
  - Plano de consumo (Tier) – determina o número máximo de chamadas que você pode fazer para uma API durante um determinado período de tempo.
- Clique em “Subscrever”.

Pronto, a partir de agora pode-se iniciar o consumo das APIs.

Alerta – Em que pese seja possível cadastrar múltiplas aplicações e subscrições, é solicitado que seja feito o cadastramento somente de uma aplicação e subscrição por instituição financeira, preservando, assim, o limite de 25 requisições por segundo. A Dataprev realiza monitoramento ativo nas aplicações e subscrições cadastradas e, pode efetuar bloqueios em caso de violação das recomendações.

Importante ressaltar que para efetiva execução das operações disponibilizadas é necessário que a instituição financeira faça a autenticação e conectividade no gateway de API (passos acima), além de utilizar também um certificado A1 em seu nome (maiores detalhes descritos no manual 09 – Manual de Comunicação – Anexos dos Serviços online).

Em resumo, para o consumo dos serviços do eConsignado necessita-se de:

Usuário cadastrado, habilitado e subscrito em uma ou mais APIs de nossa Marketplace;
Certificado digital A1 (ICP Brasil) em nome da instituição financeira;
Token obtido em nossa Marketplace para ser enviado no Header da requisição HTTP,

Os manuais técnicos contendo regras de negócio e informações suplementares podem ser visualizados em https://docs.dataprev.gov.br/docs/e-consignado/,

Utilização prática

Acessando API Consulta de Datas Limite e Competências

Versão 7.0.0
Método GET
https://hapi-bancos.dataprev.gov.br/e-consignado/v7.0.0/emprestimos/consultar-datas-competencias?competencia=202302

Deve ser enviado no Header da requisição HTTP a chave "Authorization" com o seu valor no formato "Bearer fdabb5e4-b787-352a-bd03-f07825dc2a30"
* fdabb5e4-b787-352a-bd03-f07825dc2a30 é um exemplo fictício, deve ser alterado pelo token de acesso obtido através de https://hapi-bancos.dataprev.gov.br/token (conforme instruções acima)

Para o processo de autenticação (handshake) é necessário que, junto à requisição, exista um certificado A1 em nome da instituição financeira. Do contrário, a conexão não será estabelecida.

Uma dica preciosa é explorar, testar e utilizar as APIs através de softwares como o Postman e SOAP UI (por exemplo). Dadas as diversas formas de integração, tecnologias e arquiteturas, a Dataprev não indicará, sugerirá, ou dará suporte nos modos de implementação técnica para consumo das APIs.

Portal de Operações

Alternativamente à utilização de APIs, também está disponível um portal Web (maiores informações em 12 – Manual de Comunicação – Portal de Operações x Roteiro de testes) contendo todas as operações disponibilizadas através da Marketplace. Nesse portal, além dos serviços para consignação de empréstimos, também existem as seguintes funcionalidades:

Roteiros de testes de homologação (menu Informações) – são cenários disponibilizados para integração técnica das APIs, a grande maioria deles obrigatório para o início das operações em ambiente produtivo;
Inclusão de massa de dados extra (menu Informações) – funcionalidade implementada para que a própria instituição financeira possa cadastrar massa de dados específica para seus testes internos;
Consultas diversas (menu Consultas) – são disponibilizadas consultas de arquivos – gerados pela Dataprev, consultas de informações necessárias para operação dos serviços, extratos, relatórios, entre outros.

Como obter acesso

Em breve

Referências

Documentação eConsignado
https://docs.dataprev.gov.br/docs/e-consignado/
FAQ eConsignado
https://docs.dataprev.gov.br/wp-content/uploads/2022/11/FAQ-e-Consignado-v170.pdf
Market Place – Homologação
https://hdevportal.dataprev.gov.br
Market Place – Produção
https://devportal.dataprev.gov.br
Portal de Operações – Homologação
https://hecoportal.hom.dataprev.gov.br
Portal de Operações – Produção
https://ecoportal.dataprev.gov.br
Certificados digitais dos servidores
https://docs.dataprev.gov.br/docs/e-consignado/certificados-digitais-tipo-a1-icp-brasil/
Para obtenção do certificado de servidores da Dataprev:

1) No própria negociação dos protocolos (handshake SSL);
2) Acessando os endpoints da URLs*, através de um navegador - por exemplo, e baixando-os.
3) Utilizando o comando s_client / OpenSSL para testar a conectividade SSL:
Ex: openssl s_client -servername hapi-bancos.dataprev.gov.br -connect hapi-bancos.dataprev.gov.br:443 | openssl x509 –text
Ex2: openssl.exe s_client -showcerts -connect api-bancos.dataprev.gov.br:443

Dúvidas e atendimento