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:

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 ?

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

Nome Localizado em Descrição Requerido
grant_type body Define o tipo de requisição Sim
scope body Define qual o escopo da requisição Sim
username body Inserir um usuário previamente cadastrado no banco BS2 Sim
password body Inserir uma senha válida referente ao usuário informado no campo acima Sim

Resposta

Código Descrição
200 Success
400 Bad Request
401 Unauthorized
  SandBox Produção
Requisições Solicitar URL ao time BS2 https://api.bs2.com:8443/auth/oauth/v2/token

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

Nome Localizado em Descrição Requerido
grant_type body Define o tipo de requisição Sim
scope body Define qual o escopo da requisição Sim
refresh_token body Inserir o refresh token recebido previamente Sim

Resposta

Código Descrição
200 Success
400 Bad Request
401 Unauthorized

Consulta de Saldo


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

{
 "valor": 0
}

Parâmetros

Não existe parâmetros!

Resposta

Código Descrição Schema
200 Success bs2.pj.banking.contasCorrentes.obterSaldo.Saldo
400 Bad Request [ bs2.pJ.sharedKernel.responseResult.DetalheBadRequest ]
404 Not Found [ bs2.pJ.sharedKernel.responseResult.DetalheBadRequest ]

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

Nome Localizado em Descrição Requerido Schema
movimentoInicial query   Não dateTime
movimentoFinal query   Não dateTime
inicio query   Não long
limite query   Não long

Resposta

Código Descrição Schema
200 Success bs2.pj.banking.contasCorrentes.obterExtrato.Extrato
400 Bad Request [ bs2.pJ.sharedKernel.responseResult.DetalheBadRequest ]

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

Nome Localizado em Descrição Requerido Schema
body body   Sim bs2.pj.banking.contasCorrentes.transferencias.teds.transferirSimplificado.TransferenciaSimplificadaParaRealizar

Resposta

Código Descrição Schema
200 Success bs2.pj.banking.contasCorrentes.transferencias.teds.transferirSimplificado.TransferenciaSimplificadaRealizada
400 Bad Request [ bs2.pJ.sharedKernel.responseResult.DetalheBadRequest ]

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

Nome Localizado em Descrição Requerido Schema
tedId path   Sim string (uuid)

Resposta

Código Descrição Schema
200 Success bs2.pj.banking.contasCorrentes.transferencias.teds.obterTedPorId.TedEncontrado
400 Bad Request [ bs2.pJ.utilities.modeling.api.BadRequestDetail ]

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

Nome Localizado em Descrição Requerido Schema
codigoIdentificacao path   Sim string

Resposta

Código Descrição Schema
200 Success bs2.pJ.apis.commands.banking.forIntegrationAndFrontend.pagamentos.consultarContas.ConsultaRealizada
400 Bad Request [ bs2.pJ.utilities.modeling.api.BadRequestDetail ]

Realiza Pagamento de Título


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

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

Parâmetros

Nome Localizado em Descrição Requerido Schema
body body   Sim bs2.pj.banking.pagamentos.efetuarPagamento.ContaParaPagar

Resposta

Código Descrição Schema
201 Success bs2.pJ.apis.commands.banking.forIntegrationAndFrontend.pagamentos.pagarContas.PagamentoRealizado
400 Bad Request [ bs2.pJ.sharedKernel.responseResult.DetalheBadRequest ]

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:

Campo Descrição
Id Código único da notificação
NumeroConta Identificação da conta bancária
DataNotificacao Data em que o evento está sendo disparado para o cliente
Natureza Informa o tipo de evento - C para Crédito e D para débito
Descricao Descrição do evento
DescricaoAbreviada Descrição abreviada do evento
BancoOrigDest Banco de origem ou destino do evento (conforme Natureza)
AgeOrigDest Agência de origem ou destino do evento (conforme Natureza)
ContaOrigDest Conta de origem ou destino do evento (conforme Natureza)
NomeRemFav Nome do remetente ou favorecido do evento (conforme Natureza)
CnpjCpfRemFav Documento do rementete ou favorecido do evento (conforme Natureza)
Observacao Observação do evento
Valor Valor da transferência

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:

Campo Descrição
Id Código único da notificação
Conta Identificação da conta bancária
DataNotificacao Data do disparo do webhook ao parceiro
Cliente Dados do cliente que está recebendo a notificação. [Vide tabela abaixo]
FavorecidoRemetente Dados do favorecido/remetente. [Vide tabela Cliente abaixo]
ContaOrigem Banco, agência e conta do remetente da transferência. [Vide tabela Conta abaixo]
ContaDestino Banco, agência e conta do favorecido, no momento, seus dados
Movimento Detalhes do movimento [Vide tabela abaixo]
Valor Valor da transferência

Descrição dos campos do modelo Cliente

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

Campo Descrição
Nome Nome do portador do CPF/CNPJ
CpfCnpj Documento

Descrição dos campos do modelo Conta

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

Campo Descrição
Banco Código do banco
Agencia Número da agência
Conta Número da conta

Descrição dos campos do modelo Movimento

Abaixo segue a tabela descritiva dos campos enviados no item Movimento

Campo Descrição
Data Data em que a operação foi realizada
Tipo Tipo de operação - C – Crédito / D – Débito
Codigo Código do tipo de movimento
Descricao Descrição do tipo movimento

Models

Saldo

bs2.pj.banking.contasCorrentes.obterSaldo.Saldo

Nome Tipo Descrição Tamanho Requerido
valor double   - Não

DetalheBadRequest

bs2.pJ.sharedKernel.responseResult.DetalheBadRequest

Nome Tipo Descrição Tamanho Requerido
tag string   - Não
descricao string   - Não

Bloqueado

bs2.pj.banking.contasCorrentes.obterExtrato.Bloqueado

Nome Tipo Descrição Tamanho Requerido
por24Horas double   - Não
por48Horas double   - Não
acima double   - Não
judicial double   - Não

Saldo

bs2.pj.banking.contasCorrentes.obterExtrato.Saldo

Nome Tipo Descrição Tamanho Requerido
inicial double   - Não
final double   - Não
bloqueado bs2.pj.banking.contasCorrentes.obterExtrato.Bloqueado   - Não

ChequeEspecial

bs2.pj.banking.contasCorrentes.obterExtrato.ChequeEspecial

Nome Tipo Descrição Tamanho Requerido
taxaJuros double   - Não
valorLimite double   - Não
vencimento dateTime   - Não
iof double   - Não
juros double   - Não
cet double   - Não
diasUtilizacao integer   - Não

TipoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.TipoMovimentacao

Nome Tipo Descrição Tamanho Requerido
bs2.pj.banking.contasCorrentes.obterExtrato.TipoMovimentacao integer   -  

ContaBancariaMovimento

bs2.pj.banking.contasCorrentes.obterExtrato.ContaBancariaMovimento

Nome Tipo Descrição Tamanho Requerido
nome string   - Não
documento string   - Não
banco integer   - Não
agencia integer   - Não
conta long   - Não

HistoricoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.HistoricoMovimentacao

Nome Tipo Descrição Tamanho Requerido
movimentoEm dateTime   - Não
natureza enum 0, 1, 2 - Não
remetente bs2.pj.banking.contasCorrentes.obterExtrato.ContaBancariaMovimento   - Não
favorecido bs2.pj.banking.contasCorrentes.obterExtrato.ContaBancariaMovimento   - Não
descricao string   - Não
descricaoAbreviada string   - Não
documento string   - Não
valor double   - Não
observacao string   - Não

PaginaHistoricoMovimentacao

bs2.pj.banking.contasCorrentes.obterExtrato.PaginaHistoricoMovimentacao

Nome Tipo Descrição Tamanho Requerido
itens [ bs2.pj.banking.contasCorrentes.obterExtrato.HistoricoMovimentacao ]   - Não
inicio long   - Não
limite long   - Não
total long   - Não

Extrato

bs2.pj.banking.contasCorrentes.obterExtrato.Extrato

Nome Tipo Descrição Tamanho Requerido
saldo bs2.pj.banking.contasCorrentes.obterExtrato.Saldo   - Não
chequeEspecial bs2.pj.banking.contasCorrentes.obterExtrato.ChequeEspecial   - Não
historicoMovimentacao bs2.pj.banking.contasCorrentes.obterExtrato.PaginaHistoricoMovimentacao   - Não

Banco

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

Nome Tipo Descrição Tamanho Requerido
codigo integer   - Sim
nome string   30 Não

ContaDestino

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

Nome Tipo Descrição Tamanho Requerido
banco bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Banco   - Não
agencia string   15 Sim
numero string   10 Sim

Favorecido

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

Nome Tipo Descrição Tamanho Requerido
nome string   60 Sim
documento string   14 Sim
contaDestino bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.ContaDestino   - Não

TransferenciaSimplificadaParaRealizar

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

Nome Tipo Descrição Tamanho Requerido
favorecido bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Favorecido   - Não
mesmaTitularidade boolean   - Não
valor double   - Sim

TransferenciaSimplificadaRealizada

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

Nome Tipo Descrição Tamanho Requerido
id string (uuid)   - Não
protocolo string   - Não
dataTransacao dateTime   - Não
favorecido bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Favorecido   - Não
mesmaTitularidade boolean   - Não
valor double   - Sim

TedBuscado

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

Nome Tipo Descrição Tamanho Requerido
id string (uuid)   - Não
conta integer   - Não
favorecido bs2.pj.banking.contasCorrentes.transferencias.teds.compartilhados.Favorecido   - Não
valor double   - Não
codigoFinalidade integer   - Não
dataTransacao dateTime   - Não

TedEncontrado

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

Nome Tipo Descrição Tamanho Requerido
ted bs2.pj.banking.contasCorrentes.transferencias.teds.obterTedPorId.TedBuscado   - Não

BadRequestDetail

bs2.pJ.utilities.modeling.api.BadRequestDetail

Nome Tipo Descrição Tamanho Requerido
descricao string   - Não
tag string   - Não

WebhookTransferencia

bs2.pj.banking.notificacoes.transferencias.WebhookTransferencia

Nome Tipo Descrição Tamanho Requerido
conta integer   - Não
nomeCliente string   - Não
cpfCnpjCliente string   - Não
valor double   - Não
nomeFavorecidoRemetente string   - Não
cpfCnpjFavorecidoRemetente string   - Não
tipoMovimento string   - Não
codigoMovimento integer   - Não
descricaoMovimento string   - Não
dataHoraMovimento dateTime   - Não
bancoOrigem integer   - Não
agenciaOrigem integer   - Não
contaOrigem integer   - Não
bancoDestino integer   - Não
agenciaDestino integer   - Não
contaDestino integer   - Não

ContaParaPagar

bs2.pj.banking.pagamentos.efetuarPagamento.ContaParaPagar

Nome Tipo Descrição Tamanho Requerido
codigoIdentificacao string   - Não
valor double   - Não

PagamentoRealizado

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

Nome Tipo Descrição Tamanho Requerido
autenticacao string   - Não
pagoEm dateTime   - Não
protocolo string   - Não

Banco

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

Nome Tipo Descrição Tamanho Requerido
codigo integer   - Não
nome string   - Não

Beneficiario

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

Nome Tipo Descrição Tamanho Requerido
nome string   - Não
documento string   - Não

Valores

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

Nome Tipo Descrição Tamanho Requerido
boleto double   - Não
cobrado double   - Não
descontos double   - Não
documento double   - Não
mora double   - Não
outrasDeducoes double   - Não
outrosAcrescimos double   - Não

ConsultaRealizada

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

Nome Tipo Descrição Tamanho Requerido
dataPagamento dateTime   - Não
dataVencimento dateTime   - Não
banco bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Banco   - Não
beneficiario bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Beneficiario   - Não
valores bs2.pJ.apis.commands.banking.compartilhados.pagamentos.Valores   - Não
descricaoPagamento string   - Não
nomePagador string   - Não
codigoBarras string   - Não
linhaDigitavel string   - Não
cedente string   - Não

Precisa de mais informações?

Se você ainda tem dúvidas, entre em contato conosco, estamos prontos para atende-lo:

empresas@bs2.com