Detalhamento técnico - Ambientes Homologação e Produção

Este documento apresenta todos os requisitos técnicos necessários para conectividade da instituição financeira à plataforma de Pre-matching nos ambientes de homologação e produção.

Conectividade

• Para ter acesso à API da plataforma e ao acesso WEB, sua instituição deverá possuir acesso a Rede de Telecomunicações para o mercado (RTM).
• A plataforma do Pre-matching permite acesso de duas maneiras: WEB e HTTP REST API.
• Todas as solicitações à API e WEB devem ser realizadas através de conexão HTTPS com TLS 1.2.
• O acesso através de HTTP REST API exige um “client_id” e uma chave de acesso chamado de “client_secret”. Cada instituição financeira obrigatoriamente deverá obter seu “client_id” e sua chave de acesso “client_secret” através do portal do Selic utilizando a aplicação “Gerenciador de Acesso”.”.

        client_id – Identificação da instituição financeira para acesso ao serviço.
        client_secret – Credencial (senha) de acesso exclusiva da instituição financeira à plataforma.
      

Regras de firewall

Acessando através da API

O acesso à API da plataforma de Pre-matching exige a obtenção de um “client_id” e um “client_secret”.

Estes dados podem ser acessados diretamente por cada instituição através do portal do Selic. Para o acesso a esta funcionalidade a instituição deve ter acesso as funções do sistema Pre-matching habilitadas previamente.

Caso seu perfil não seja de administrador você deve solicitar para o responsável da sua instituição que as habilite no sistema Logon associando a seu usuário. O Acesso é realizado através do Portal Selic na RTM, menu Logon > API's.

Abaixo segue uma figura apresentando a aplicação “Gerenciador de acesso” dentro do portal do Selic:

Acessando através da WEB

O acesso pela interface WEB se dá exclusivamente através das URLs abaixo:

A autenticação do acesso web (iselic + usuário + senha) é a mesma utilizada atualmente pelos usuários do portal do Selic na RTM (Ex. https://hml.rtm.selic.gov.br/). O exemplo abaixo apresenta como será a tela de autenticação da parte web.

Autenticação à API

O método de autenticação disponível na API da plataforma de Pre-matching é o OAuth2 e HTTP padrão através de TOKEN JWT.

Para iniciar a comunicação com a plataforma e acessar as URLs protegidas da plataforma você necessitará recuperar um token de acesso válido.

Nas seções seguintes seguem alguns exemplos utilizando a aplicação cURL para o envio da requisição autenticada para exemplificar a solicitação de um token.

Nota: cURL é um aplicativo open source e não é suportado pelo Selic. Ele é citado apenas para demonstração das chamadas HTTP.

Recuperação/Solicitação de um token JWT para uso na API.

As variáveis são identificadas por ${}. Exemplo: ${client_id} é a variável que identifica o cliente da API da sua instituição, como por exemplo "desenv" nos ambientes de desenvolvimento. Ex

        curl -X POST \
        https://pre-matching-hml.rtm.selic.gov.br/auth/realms/logon/protocol/openid-connect/token \
         -H 'Accept: */*' \
         -H 'Accept-Encoding: gzip, deflate' \
         -H 'Content-Type: application/x-www-form-urlencoded' \
         -H 'Host: pre-matching-hml.rtm.selic.gov.br' \
         -d 'grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}
      

Simulação de envio (Request)

        curl -X POST \
        https://pre-matching-hml.rtm.selic.gov.br/auth/realms/logon/protocol/openid-connect/token \
        -H 'Accept: */*' \
        -H 'Accept-Encoding: gzip, deflate' \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -H 'Host: pre-matching-hml.rtm.selic.gov.br' \
        -d 'grant_type=client_credentials&client_id=desenv&client_secret=secret'
      

Simulação de comunicação à API

Após recuperação do TOKEN válido, você deve utilizá-lo nas chamadas à API, seguindo o exemplo abaixo

        curl -X GET \
        https://api-pre-matching-hml.rtm.selic.gov.br/pre-matching/api/v1/negocios/202004010000001 \
        -H "accept: application/json" \
        -H 'Accept-Encoding: gzip, deflate' \
        -H 'Authorization: Bearer eyJhbGciOiJ...ctSsFxQ' \
        -H 'Host: api-pre-matching-hml.rtm.selic.gov.br'
      

Rate Limiting – Limitação de requisições

Para garantir a estabilidade e o desempenho da plataforma, foi implementado um mecanismo de limitação de requisições (rate-limiting) na API do Pre-matching.

Regras aplicadas:

• Cada endereço IP possui um limite de 300 requisições por minuto, independentemente do endpoint acessado.
• Quando o contador do cabeçalho RateLimit-Remaining atingir zero, novas requisições deverão ser suspensas por 60 segundos antes de retomar o envio.

Exemplo prático:

Se uma instituição enviar, a partir do mesmo IP, no intervalo de um minuto:

• 100 requisições para /pre-matching/api/v2/evento
• 50 requisições para /pre-matching/api/v2/negocios/*
• 2 requisições para /pre-matching/api/v2/especificacoes/requisicoes
• 150 requisições para /pre-matching/api/v2/comandos

O total será 302 requisições, ultrapassando o limite de 300 por IP. Nesse caso, o contador RateLimit-Remaining será zerado e novas requisições deverão aguardar 60 segundos para que o contador seja resetado.

As respostas do cabeçalho HTTP de qualquer requisição à API mostrarão o status atual do seu limite de requisições permitidas. Exemplo:

            curl -X GET \
            https://api.sandbox.selic.gov.br/pre-matching/api/v2/negocios/202004010000001 \
            -H "accept: application/json" \
            -H 'Authorization: Bearer eyJhbGciOiJ...ctSsFxQ' \
            -H 'Host: api.sandbox.selic.gov.br'

            HTTP/1.1 200 OK
            Date: Mon, 13 Jul 2020 09:27:06 GMT
            Status: 200 OK
            RateLimit-Limit: 300
            RateLimit-Remaining: 10
            RateLimit-Reset: 60
      

Descrição:

Caso sua aplicação cliente exceda este limite, ela receberá um HTTP STATUS 429 informando que o limite máximo permitido foi ultrapassado. Exemplo:

            GET /obter-status/123
            Response:
            HTTP/1.1 429 Too Many Requests
            Content-Type: application/json
            Date: Mon, 13 Jul 2020 09:27:40 GMT
            Retry-After: Mon, 13 Jul 2020 09:27:40 GMT
            RateLimit-Limit: 300
            Ratelimit-Remaining: 0
            RateLimit-Reset: 60

            {
                "title": "Too Many Requests",
                "status": 429,
                "detail": "Você ultrapassou o número de requisições permitidas"
            }