Sumário:
- Visão Geral
- Fluxograma completo de utilização
-
Como obter credenciais junto ao banco
- Como configurar as credenciais no PlugBoleto
- Instruções e codigos aceitos no registro via API
-
Recursos disponíveis API Santander
Visão Geral
O recurso de transmissão instantânea foi desenvolvido para facilitar a integração de sistemas de cobrança com as APIs bancárias, oferecendo uma solução prática e eficiente para desenvolvedores.
Esse método permite a consulta direta dos dados dos boletos nos servidores bancários, retornando imediatamente após sua criação o status REGISTRADO como nos boletos de cobranças de grandes marketplaces.
Ao utilizar a transmissão instantânea, desenvolvedores conseguem implementar um fluxo de emissão de boletos mais ágil e seguro, permitindo que clientes finais possam realizar o pagamento dos títulos logo após a criação. Isso elimina o tempo de espera que existe no tradicional método de transmissão de remessas e obtenção de retorno que é D+1, já que cada boleto emitido pelo sistema é validado instantaneamente, integrando-se com o servidor bancário em tempo real.
Essa solução simplifica a comunicação com instituições financeiras, reduzindo o esforço de implementação e manutenção de sistemas de cobrança, enquanto melhora a experiência do usuário final. Com a transmissão instantânea, é possível construir aplicações financeiras robustas que garantem precisão nos dados de pagamento, ao mesmo tempo em que agilizam o processo de verificação e registro de boletos.
Atenção: Apesar de a captura do status de REGISTRO ou REJEIÇÃO via API ser imediato as LIQUIDAÇÕES(pagamentos) não seguem a mesma dinâmica, dependendo dos procedimentos internos do banco. Isso significa que o status de liquidação não está disponível instantaneamente e depende dos prazos internos de atualização de suas bases. Esse tempo pode variar de acordo com o banco e o serviço de API.
Fluxograma completo de utilização
Como obter credenciais junto ao Banco
Pré-requisitos para realizar o procedimento completo liberação de credenciais bancárias.
Postman ou Insomnia: Ou qualquer outra ferramenta de sua preferencia para realizar o disparos de requisições HTTPS.
Passo 1 - Acesso ao portal de desenvolvimento Santander:
1: Certifique-se que o usuário do cliente é o Usuário Master* da conta.
2: Acessar o portal de desenvolvimento do Santander através do link:
https://developer.santander.com.br - Nesse acesso deve ser logado o usuário master da
3: Clique em “Entrar”;
4: Clique em “Acesse com sua conta PJ"
*OBS: Somente o Usuário Master, Secundário ou um usuário convidado pelo Master conseguem realizar a criação de
aplicações em Produção
5: Inserir "Agência";
6: Inserir "Conta";
7: Inserir "Usuário";
8: Inserir "Senha";
9: Clicar em "Login".
Passo 10: Uma vez logado no portal de desenvolvedor como Usuário Master acesse ícone de opções de usuário (no canto superior direito) e clique em “Minhas aplicações”
Passo 2 - Criação da aplicação:
1: Selecionar o marcador "Sou desenvolvedor";
2: Crie um nome para o aplicativo (a sua escolha);
3: Encaminhar o certificado para validação do banco (Padrão A1 - deverá ser emitido por um órgão autorizado e ser de 2048 bits)**;
4: Descrição da aplicação (opcional)
5: Busque pela API "Emissão de boletos" e "Geração de QRCode" (podem estar listados como API-PIX e API-Cobranca)
6: Selecione as 2 API's
7: Clique em Enviar
Após o envio no Passo 7, será encaminhado um e-mail ao endereço vinculado ao Usuário Master, confirmando a criação da aplicação
** ▪ O certificado deve possuir o atributo “Key Usage” habilitado para “Digital signature” ou “Key agreement",
“Enhanced Key Usage” deve ser no mínimo “Client Authentication (1.3.6.1.5.5.7.3.2)”.
▪ Certificado com repasse dos arquivos no formato PEM de uma certificadora autorizada (ACs externas confiáveis).
▪ Tipo x509 v3
▪ Mínimo de 90 dias de validade.
▪ Arquivos a serem repassados ao Santander:
• certificado raiz (root)
• certificado intermediário
• certificado parceiro
• certificado com a cadeia completa (três itens acima)
▪ O certificado não pode ser auto assinado e tem que ser emitido por uma CA externa.
Passo 3 - Acessar as aplicações:
1: Clique no ícone usuário;
2: Clique em Minhas aplicações.
Passo 4 - Coleta das credenciais:
1: Serão geradas 2 chaves para o cliente (ClientID e ClientSecret);
2: Para copiar, basta selecionar o botão ao lado de cada uma.
Criação do Workspace
Passo 1 - Importe a collection em anexo (Final da documentação) no programa Insomnia.
Passo 2 - Siga os passos da importação:
Passo 3 - Com a collection já importada, vá para adicione o certificado na rota host
Host: https://trust-open.api.santander.com.br/auth/oauth/v2/token
Passo 4 - Adicione a rota host, selecione o PFX, adicione o arquivo + senha e conclua a inclusão:
Passo 5 - Realize a autenticação pela rota "Token" gerando o "access_token":
Passo 6 - Realizar a criação do Workspace na rota "Criar Workspace" informando o "access_token" no header:
JSON de exemplo:
{
"type": "BILLING",
"description": "Workspace de Cobrança",
"covenants": [
{
"code": "Número do convênio"
}
]
}
Envio:
Feito isso o status de sucesso esperado é "201" com uma estrutura de retorno semelhante com a que segue abaixo:
{
"id": "eb30250f-1228-439c-ac9f-29fe72ba39b5",
"status": "ACTIVE, INACTIVE ou SUSPENDED",
"TYPE": "",
"covenants": [
{
"code": "Número do convênio" - Deve ser definido o número de convênio
}
]
}
Passo a passo em vídeo:
Como configurar as credenciais no PlugBoleto
Para melhor visualização e entendimento do processo vamos utilizar nossa GUI WEB para explicar o preenchimento de campos mas esse processo também poderá ser realizado via API conforme a documentação de integração com a API PlugBoletos.
Após realizar o cadastro da conta, acesse a na página de convênios e caso não tenha sido ainda criado o convenio referente a conta deve ser criado conforme a documentação de cadastro de convênios.
Com o convenio criado ative a opção "Registro instantâneo", esse campo é onde você habilita o uso desse recurso no seu convênio.
Quando o campo Registro instantâneo for ativado deve aparecer logo abaixo dois novos campos o campo "API - ID", onde deve ser informado o client_id informado pelo Santander, e o campo "Segredo" onde deve ser informado o client_secret.
Exemplo do cadastro das credenciais no portal do Plugboleto:
2) Fazer o upload do client certificate
Após o preenchimento das informações clicar em Salvar para realizar o upload do certificado.
Para visualizar ou trocar o certificado, após o cadastro, edite novamente o convênio e o certificado será exibido como na imagem abaixo:
Instruções e códigos aceitos no registro via API
Como informar Juros
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodigoJuros |
1 - Valor por dia. 2 - Valor em percentual mensal. |
||
| TituloDataJuros | DD/MM/AAAA | ||
| TituloValorJuros | 15 |
Como informar Multa
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodigoMulta |
0 - Não registra multa (isento). 1 - Valor em Reais (Fixo). 2 - Valor em percentual com duas casas decimais.. Clique aqui para ter a descrição dos códigos |
||
| TituloDataMulta | DD/MM/AAAA | ||
| TituloValorMultaTaxa | 15 |
Como informar Desconto
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodDesconto |
0 - Sem instrução de desconto. 2 - Valor em percentual até a Data informada |
||
| TituloDataDesconto | DD/MM/AAAA | ||
| TituloValorDescontoTaxa | 15 | ||
| TituloCodDesconto2 |
0 - Sem instrução de desconto. 2 - Valor em percentual até a Data informada |
||
| TituloDataDesconto2 | DD/MM/AAAA | ||
| TituloValorDescontoTaxa2 | 15 |
Como informar Protesto
| Campo | Valores aceitos | Tamanho mínimo | Tamanho máximo |
| TituloCodProtesto | boolean: true ou false reveeer | ||
| TituloPrazoProtesto | Quantidade de dias | 02 |
Outros campos que possuem validação
| Campo | valores aceitos | Tamanho mínimo | Tamanho máximo |
| ContaAgencia | 4 | ||
| ContaNumero | 5 | ||
| CodigoCarteira | 3 | ||
| TituloNossoNumero | 8 | ||
| TituloNumeroDocumento | 10 | ||
| TituloValor | 13 | ||
| TituloDocEspecie |
['01', '02', '03', '04', '05', '06', '07', '08', '09', '13', '15', '16', '17', '18', '99'] Clique aqui para a ter descrição dos códigos, |
||
| TituloAceite | S - Aceito; N - Não Aceito | ||
| TituloCodProtesto | [1, 2, 3, 7] Clique aqui para ter a descrição dos códigos | ||
| TituloCodBaixaDevolucao | 1 - Baixar/Devolver | ||
| SacadoEnderecoCep | 8 |
Recursos disponiveis na API Santander
Boleto Hibrido
O boleto híbrido do Santander combina as opções de pagamento via boleto e Pix para uma mesma cobrança. Isso permite oferecer aos clientes a flexibilidade de quitar o pagamento utilizando o código de barras do boleto ou o QR Code do Pix.
O que é necessário para utilizar o Boleto Hibrido com o banco Santander?
Para utilizar o boleto híbrido com o Banco Santander, basta realizar a liberação das credenciais conforme descrito neste passo. Após isso, você estará apto a usar a API bancária. No caso do Santander, não é necessária nenhuma liberação adicional de escopos ou serviços junto ao banco, com a credencial padrão já é possível realizar o registro.
Emitindo o boleto híbrido VIA API
Para comandar que um boleto seja registrado no modelo HIBRIDO basta adicionar ao JSON de envio anteriormente implementado o campo chamado "hibrido": true, caso tenha duvidas sobre a implementação da rota de inclusão de boletos basta acessar nossa documentação.
Abaixo um exemplo do campo a ser adicionado:
{
...
...
"TituloNossoNumero":"123",
"TituloValor":"100,00",
"hibrido": true
}
Consultando o boleto híbrido
A consulta do boleto hibrido segue a mesma implementação da consulta de boletos tradicionais conforme a documentação de consulta de boletos, sendo necessário apenas a leitura dos dois novos campos referentes ao boleto hibrido.
{
"hibrido": true,
"UrlPix": "http://plugboleto.com.br/api/v1/boletos/impressao/HRKCVJXVV/pix",
}
Impressão do boleto híbrido
Para saber mais sobre os tipos de impressão, acesse a documentação referente aos exemplos de impressão.
Exemplo de boleto híbrido:
Consulta de Boletos
Consulta individual
As requisições que forem disparadas para o endpoint de consulta do Plugboleto serão imediatamente processadas e apresentará os dados atuais do titulo em nosso banco de dados, em seguida replicaremos a consulta diretamente no servidor bancário a fim de buscar uma possível atualização de dados, caso seja identificado uma atualização de status automaticamente será disparado um webhook de notificação para a Software House, caso não tenha webhook configurado é possível obter as atualizações realizando uma nova consulta em seguida.
Um boleto pode ter 7 situações diferentes, que podem ser verificadas neste link.
Para verificar quais campos são retornados nesta consulta, clique aqui.
Consulta Automática
O PlugBoletos conta com rotinas de consultas automáticas que tem como intuito dar mais confiabilidade e celeridade as conciliações de boletos, no momento para o banco SANTANDER V2 temos disponivel apena a consulta geral, sem webhook ou francesa.
Consulta geral em boletos REGISTRADOS
Considerando que a consulta francesa e o webhook não estão disponíveis para o santander é realizada uma consulta em todos os títulos com status de REGISTRADO em nossa base, ela se inicia as 7 horas da manha e seu tempo de execução pode variar de acordo com o tamanho da base a ser consultada.
Informações do boleto atualizadas após a conciliação na API Santander V2.
Com a atualização via API o banco Santander reduz a quantidade de informações disponibilizadas sobre o pagamento limitando se as principais informações de LIQUIDAÇÃO:
- Situação
- PagamentoData
- PagamentoDataCredito
- PagamentoValorPago
- PagamentoValorAcrescimos
Vale apenas ressaltar que todas as outras informações da cobrança já foram capturadas e estamos focando apenas em campos atualizados após o pagamento do titulo.
Alteração Individual de Boletos via API
A alteração de boletos é útil em situações onde informações previamente registradas, como data de vencimento, valor ou valor de abatimento precisam ser modificadas após o titulo ja estar registrado. Abaixo está uma visão geral de como funciona o processo de alteração de boletos via API bancária no PlugBoletos.
Requisitos para a Alteração de Boletos
Antes de comandar uma alteração, é importante garantir que o boleto se enquadra em alguns requisitos. O boleto precisa estar REGISTRADO no SANTANDER.
- Apenas determinados campos podem ser modificados, como data de vencimento, valor de cobrança, multa, juros e descontos aplicáveis.
- É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao Banco para acessar a API SANTANDER V2.
Como ativar a Alteração via API
Para ativar a funcionalidade de alteração após ter configurado as credenciais no convenio basta ativar a opção "Alteração via WS" no cadastro de convenio.
Como disparar a requisição para realizar a alteração individual via API BANCÁRIA.
POST
Homologação:
Produção:
Headers
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| cnpj-sh | CNPJ da Software House | 01001001000113 |
| token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
Campos disponíveis para alteração
| Campo | Descrição | Exemplo |
| TituloValor |
Altera o valor do título
Boletos aptos a alteração de valor de acordo com as regras especificas do Santander API V2.
|
15,00 |
| TituloDataVencimento | Alterar a data de vencimento | 15/03/2023 |
| TituloValorDescontoTaxa | Alterar o valor do desconto | 100 |
| TituloValorAbatimento | Alterar o valor do abatimento ou redução do valor do boleto | 5 |
| TituloCodProtesto | Alterar o código de protesto | 8 |
| TituloPrazoProtesto | Alterar a data do protesto | 20/02/2023 |
Baixa de Boletos
Para boletos que alcançaram o status de REGISTRADO, o cancelamento só pode ser realizado através de uma solicitação formal de BAIXA. Esse processo, para o Santander, pode ser automatizado diretamente por meio da API bancária, facilitando o cancelamento e integração com sistemas de cobrança.
Requisitos para a Baixa de Boletos
- Status de REGISTRADO: Assim que um boleto é registrado no banco, ele fica disponível para pagamento e segue sob controle do sistema bancário.
- Solicitação de Baixa: Caso o boleto precise ser cancelado (por exemplo, devido a duplicidades, erros ou desistência de cobrança), uma requisição de baixa deve ser enviada ao banco.
- É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao Banco para acessar a API SANTANDER V2.
Como solicitar a Baixa
Para realizar a solicitação de baixa basta realizar a integração com o endpoint de baixa do Plugboletos.
Comentários
0 comentário
Por favor, entre para comentar.