Banking - bs2.pj.forIntegration - Versão: 1

Banking

O que é API de Banking?

API Banking disponibiliza operações relacionadas a gestão da conta bancária:

• Autenticação
• Consulta de Saldo
• Consulta de Extrato
• Envio de TED
• Consulta de TED
• Consulta Título
• Realiza Pagamento de Título
• Webhook de movimentação de CC (extrato)
• Webhook de transferências recebidas

Quem pode usar a API de Banking?

Todos os clientes e parceiros do banco BS2.

Quais são requisitos para a utilização da API de Banking ?

• Ser cliente do banco BS2
• Ter um token de acesso válido

Autenticação

Utilizamos em nossas API’s de autenticação um rate-limit, que permite até 10 requisições de Token e refresh por minuto, sendo necessário realizar o gerenciamento de token descrito abaixo:

Gerenciamento de Token

É necessário fazer a gestão do token de acesso e do refresh_token dentro da sua aplicação.

1.1 - Gerar um token utilizando ClientId, ClientSecret, username e password. Fluxo de geração de token descrito no passo acima. O token possui uma validade em segundos, apresentada no campo expires_in. 420 segundos em Sandbox e 300 segundos em Produção.

1.2 - Utilizando o refresh_token gerado no passo anterior, deve-se fazer o fluxo de refresh_token. Desta forma, não se deve utilizar usuário e senha para gerar novo token.

1.3 - Antes do refresh_token expirar (10 minutos de duração), é necessário renovar o token usando fluxo de refresh_token.

Pontos Importantes

Ao gerar um token utilizando username e password, deve-se apenas gerar novos tokens usando o fluxo de refresh_token (utilizando o refresh_token e não o username e password)

Só é necessário gerar um novo token, utilizando usuário e senha, caso não consiga realizar o fluxo de refresh_token.

O campo expires_in representa a validade do token em segundos, enquanto o token estiver válido, este token deve ser utilizado.

O refresh_token possui um tempo de validade maior que a validade do token (10 min), ou seja, mesmo se o token estiver inválido por tempo, e o refresh_token estiver válido, ainda é possível fazer o fluxo de Refresh_token para gerar um token válido.

Quando o token estiver próximo da validade, deve-se gerar um novo token, usando um refresh_token, para assim, receber um novo token valido pelo mesmo período de tempo.

Não há limite de requisições enquanto o token estiver válido.

Quando um novo token é gerado, o token anterior passa a ser inválido.

Token de Autenticação

Para usar a API é necessário obter o token de autenticação vinculado a um usuário BS2. Para e emissão do token de acesso reproduza os seguintes passos:

1.1 Realizar uma requisição Basic Auth no endpoint abaixo

1.2 Definir o valor password para o campo grant_type

1.3 Definir o valor apibanking para o campo scope

1.4 Inserir usuário e senha válidos nos campos de username e password

{
  "grant_type":"password",
  "scope":"apibanking",
  "username":"valid_username",
  "password":"valid_password"  
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "apibanking"
}

Parâmetros

Resposta

Token de Atualização

Após a geração de um token de autenticação é recomendável que o gerenciamento do seu tempo de expiração seja feita pelo fluxo de atualização de token conforme os seguintes passos:

1.1 Realizar uma requisição Basic Auth no endpoint abaixo

1.2 Definir o valor refresh_token para o campo grant_type

1.3 Definir o valor apibanking para o campo scope

1.4 Definir o valor do refresh token recebido previamente para o campo refresh_token

{
  "grant_type": "refresh_token",
  "scope": "apibanking",
  "refresh_token": "refresh_token"
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "apibanking"
}

Parâmetros

Resposta

Consulta de Saldo

--curl
"GET": "/pj/forintegration/banking/v1/contascorrentes/principal/saldo"

{
 "valor": 0
}

Parâmetros

Não existe parâmetros!

Resposta

Consulta de Extrato

--curl
"GET": "/pj/forintegration/banking/v1/contascorrentes/principal/extrato"

{
 "saldo": {
  "inicial": 0,
  "final": 0,
  "bloqueado": {
   "por24Horas": 0,
   "por48Horas": 0,
   "acima": 0,
   "judicial": 0
  }
 },
 "chequeEspecial": {
  "taxaJuros": 0,
  "valorLimite": 0,
  "vencimento": "2021-4-11T21:18:57.332Z",
  "iof": 0,
  "juros": 0,
  "cet": 0,
  "diasUtilizacao": 0
 },
 "historicoMovimentacao": {
  "itens": [
    {
     "movimentoEm": "2021-4-11T21:18:57.351Z",
     "natureza": [0, 1, 2],
     "remetente": {
      "nome": "string",
      "documento": "string",
      "banco": 0,
      "agencia": 0,
      "conta": 0
     },
     "favorecido": {
      "nome": "string",
      "documento": "string",
      "banco": 0,
      "agencia": 0,
      "conta": 0
     },
     "descricao": "string",
     "descricaoAbreviada": "string",
     "documento": "string",
     "valor": 0,
     "observacao": "string"
    }
  ],
  "inicio": 0,
  "limite": 0,
  "total": 0
 }
}

Parâmetros

Resposta

Envio de TED

{
 "favorecido": {
  "nome": "string",
  "documento": "string",
  "contaDestino": {
   "banco": {
    "codigo": 0,
    "nome": "string"
   },
   "agencia": "string",
   "numero": "string"
  }
 },
 "mesmaTitularidade": false,
 "valor": 0
}

{
 "id": "string",
 "protocolo": "string",
 "dataTransacao": "2021-4-11T21:18:57.351Z",
 "favorecido": {
  "nome": "string",
  "documento": "string",
  "contaDestino": {
   "banco": {
    "codigo": 0,
    "nome": "string"
   },
   "agencia": "string",
   "numero": "string"
  }
 },
 "mesmaTitularidade": false,
 "valor": 0
}

Parâmetros

Resposta

Consulta de TED

--curl
"GET": "/pj/forintegration/banking/v1/contascorrentes/transferencias/teds/{tedId}"

{
 "ted": {
  "id": "string",
  "conta": 0,
  "favorecido": {
   "nome": "string",
   "documento": "string",
   "contaDestino": {
    "banco": {
     "codigo": 0,
     "nome": "string"
    },
    "agencia": "string",
    "numero": "string"
   }
  },
  "valor": 0,
  "codigoFinalidade": 0,
  "dataTransacao": "2021-4-11T21:18:57.352Z"
 }
}

Parâmetros

Resposta

Consulta Título

--curl
"GET": "/pj/forintegration/banking/v1/pagamentos/{codigoIdentificacao}"

{
 "dataPagamento": "2021-4-11T21:18:57.352Z",
 "dataVencimento": "2021-4-11T21:18:57.352Z",
 "banco": {
  "codigo": 0,
  "nome": "string"
 },
 "beneficiario": {
  "nome": "string",
  "documento": "string"
 },
 "valores": {
  "boleto": 0,
  "cobrado": 0,
  "descontos": 0,
  "documento": 0,
  "mora": 0,
  "outrasDeducoes": 0,
  "outrosAcrescimos": 0
 },
 "descricaoPagamento": "string",
 "nomePagador": "string",
 "codigoBarras": "string",
 "linhaDigitavel": "string",
 "cedente": "string"
}

Parâmetros

Resposta

Realiza Pagamento de Título

{
 "codigoIdentificacao": "string",
 "valor": 0
}

{
 "autenticacao": "string",
 "pagoEm": "2021-4-11T21:18:57.352Z",
 "protocolo": "string"
}

Parâmetros

Resposta

Webhook de movimentação de CC (extrato)

O Banco BS2 disponibiliza um webhook para notificar os clientes em tempo real sobre as movimentações que ocorram na conta. Cada linha do extrato é enviada para o cliente que deseja receber esse webhook no momento em que o evento entra no extrato. Para utilizar o webhook, por favor entre em contato com a equipe do BS2 informando uma URL para que possamos ativar o webhook para você. No momento essa operação é feita apenas manualmente, sendo necessário a solicitação para a equipe Tech do BS2 Empresas.

Funcionamento

O webhook será disparado via uma requisição HTTP POST até que o cliente retorne com um status de sucesso (família HTTP 200).

Contrato

Abaixo segue o contrato que será enviado na requisição com os dados do evento. Cada webhook é exclusivo para um evento. Para cada evento uma nova chamada será feita.

{
    "Id":"66d4ee8e-0bf5-49ee-8219-66bdaf0fab60",
    "NumeroConta":259608,
    "DataNotificacao":"2020-01-30T23:50:50.4011586+00:00",
    "Natureza":"C",
    "Descricao":"RECEB.TRANSF.ENT.CONTAS IB",
    "DescricaoAbreviada":"RECEBIMENTO CONTAS BS2",
    "BancoOrigDest":218,
    "AgeOrigDest":1,
    "ContaOrigDest":254924,
    "NomeRemFav":"JAIR JUNIOR DOS REIS BORGES",
    "CnpjCpfRemFav":"88386660000101",
    "Observacao":null,
    "Valor":100.0
}

Descrição dos campos do modelo principal

Abaixo segue tabela descritiva dos campos enviados na notificação:

Webhook de transferências recebidas

O Banco BS2 disponibiliza um webhook para notificar os clientes em tempo real sobre transferências recebidas em sua conta, incluindo: TEDs recebidas de outros Banco e storno de TEDs enviadas, que foram recusadas pelo banco destino. Para utilizar o webhook, por favor entre em contato com a equipe do BS2 informando uma URL para que possamos ativar o webhook para você. No momento essa operação é feita apenas manualmente, sendo necessário a solicitação para a equipe Tech do BS2 Empresas.

Funcionamento

O webhook será disparado via uma requisição HTTP POST até que o cliente retorne com um status de sucesso (família HTTP 200).

Contrato

Abaixo segue o contrato que será enviado na requisição com os dados da transferência. Cada webhook é exclusivo para uma transferência. Para cada transferência uma nova chamada será feita.

{
  "Id": "dfc2b944-4572-4d94-83a0-791de441ab99",
  "Conta": 254584,
  "DataNotificacao": "2019-10-22T20:18:55.8463059-03:00",
  "Cliente": {
    "Nome": "DXS GESTAO E CONSULTORIA EMPRESARIAL EIRELI",
    "CpfCnpj": "30177427000120"
  },
  "FavorecidoRemetente": {
    "Nome": "JAIR JUNIOR DOS REIS BORGES",
    "CpfCnpj": "04153796603"
  },
  "ContaOrigem": {
    "Banco": 218,
    "Agencia": 1,
    "Conta": 259608
  },
  "ContaDestino": {
    "Banco": 218,
    "Agencia": 1,
    "Conta": 254924
  },
  "Movimento": {
    "Data": "2019-10-22T20:17:45.343+00:00",
    "Tipo": "C",
    "Codigo": 786,
    "Descricao": "RECEB.TRANSF.ENT.CONTAS IB"
  },
  "Valor": 258.74
}

Descrição dos campos do modelo principal

Abaixo segue tabela descritiva dos campos enviados na notificação:

Descrição dos campos do modelo Cliente

Abaixo segue a tabela descritiva dos campos enviados nos itens Cliente e FavorecidoRemetente

Descrição dos campos do modelo Conta

Abaixo segue a tabela descritiva dos campos enviados nos itens ContaOrigem e ContaDestino

Descrição dos campos do modelo Movimento

Abaixo segue a tabela descritiva dos campos enviados no item Movimento

Models

Saldo

bs2.pj.banking.contasCorrentes.obterSaldo.Saldo

DetalheBadRequest

bs2.pJ.sharedKernel.responseResult.DetalheBadRequest

Bloqueado

bs2.pj.banking.contasCorrentes.obterExtrato.Bloqueado

Saldo

bs2.pj.banking.contasCorrentes.obterExtrato.Saldo

ChequeEspecial

bs2.pj.banking.contasCorrentes.obterExtrato.ChequeEspecial

TipoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.TipoMovimentacao

ContaBancariaMovimento

bs2.pj.banking.contasCorrentes.obterExtrato.ContaBancariaMovimento

HistoricoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.HistoricoMovimentacao

PaginaHistoricoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.PaginaHistoricoMovimentacao

Extrato

bs2.pj.banking.contasCorrentes.obterExtrato.Extrato

Banco

bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Banco

ContaDestino

bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.ContaDestino

Favorecido

bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Favorecido

TransferenciaSimplificadaParaRealizar

bs2.pj.banking.contasCorrentes.transferencias.teds.transferirSimplificado.TransferenciaSimplificadaParaRealizar

TransferenciaSimplificadaRealizada

bs2.pj.banking.contasCorrentes.transferencias.teds.transferirSimplificado.TransferenciaSimplificadaRealizada

TedBuscado

bs2.pj.banking.contasCorrentes.transferencias.teds.obterTedPorId.TedBuscado

TedEncontrado

bs2.pj.banking.contasCorrentes.transferencias.teds.obterTedPorId.TedEncontrado

BadRequestDetail

bs2.pJ.utilities.modeling.api.BadRequestDetail

WebhookTransferencia

bs2.pj.banking.notificacoes.transferencias.WebhookTransferencia

ContaParaPagar

bs2.pj.banking.pagamentos.efetuarPagamento.ContaParaPagar

PagamentoRealizado

bs2.pJ.apis.commands.banking.forIntegrationAndFrontend.pagamentos.pagarContas.PagamentoRealizado

Banco

bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Banco

Beneficiario

bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Beneficiario

Valores

bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Valores

ConsultaRealizada

bs2.pJ.apis.commands.banking.forIntegrationAndFrontend.pagamentos.consultarContas.ConsultaRealizada