Artigo dedicado a algumas informações importantes a serem consideradas sobre nosso sistema a integração com o Boleto.
Sumário
- Como conseguir o Token da Software House
- Bancos homologados pela API PlugBoleto
- Como solicitar homologação de novos bancos no PlugBoletos
- Rate limites no boleto
- Verificar saúde da API Plugboletos
- Como informar Desconto
- Como informar Multa
- Como informar Juros
- Como informar Baixa
- Como informar Protesto
- Demonstrações de Uso das APIs PlugBank
Como conseguir o Token da Software House
O Token é utilizado em todas rotas/métodos da API PlugBoleto.
Ele é encontrado na Central do Cliente. Para acessar deve ser informado o e-mail cadastrado e a senha.
Após feito o Login siga os passos:
- Clique no botão
MENU
localizado no canto superior direito. - Clique no botão
API
. - A tela possui a opção de regerar o token. Caso a mesma seja executada, é extremamente importante que sua aplicação seja atualizada e recompilada com o novo valor. Caso isso não aconteça a sua aplicação ficará impedida de consumir os métodos da API.
Exemplo abaixo:
Bancos homologados pela API PlugBoleto
Abaixo separamos uma tabela com os bancos/CNAB's já homologados pela API PlugBoleto.
Caso não encontre seu banco na lista de bancos homologados abaixo?
Caso o banco que você utiliza não esteja na lista de bancos homologados, você pode solicitar a homologação facilmente. Basta acessar o link abaixo para iniciar o processo:
Como solicitar homologação de novos bancos no PlugBoleto
240: Layout homologado no CNAB 240
400: Layout homologado no CNAB 400
Automática: Banco com homologação para a transmissão automática de remessa e retorno.
Registro WS: Banco homologado com registro via Web Service Bancário
Consulta WS: Banco homologado com a Consulta de boletos via Web Service Bancário
Validador: Banco com validação de layout.
Banco |
240 |
400 |
VAN Nexxera |
VAN Finnet |
Registro WS |
Consulta WS |
Homolog. WS |
Validador |
Alteração WS |
Baixa WS |
Híbrido (QrCode PIX) |
Banco Itaú (341) |
✔️ |
✔️ |
- (obs 2) |
- (obs 2) |
✔️ |
✔️(v2) |
✔️(v2) |
✔️ |
✔️(v2) |
✔️(v2) |
✔️(v2) |
Banco Santander (033) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
✔️ |
- |
- |
✔️(v2) |
Banco Bradesco (237) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
✔️(obs 1) |
✔️ |
✔️ |
- |
- |
- |
Banco do Brasil (001) |
✔️ |
✔️ |
- (obs 2) |
- (obs 2) |
✔️ |
✔️(v2) |
✔️ |
✔️ |
✔️(v2) |
✔️(v2) |
✔️(v2) |
Sicoob (756) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
- |
✔️ |
✔️ |
✔️ |
✔️ |
Sicredi (748) |
✔️ |
✔️ |
✔️ |
- |
✔️ |
✔️(obs 3) |
- |
✔️ |
- |
✔️(v2) |
✔️(v3) |
Caixa Econômica Federal (104) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
- |
✔️ |
- |
- |
✔️(obs 4) |
Banco Banrisul (041) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
✔️ |
- |
- |
- |
Banco Safra (422) |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
✔️ |
- |
- |
- |
Banco Inter (077) |
- |
- |
- |
- |
✔️ |
✔️ |
- |
- |
- |
✔️(v2) |
- |
Banco Daycoval (707) *Disponível apenas como correspondente Itaú |
- |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
- |
- |
- |
Cecred (Ailos) (085) |
✔️ |
- |
- |
✔️(obs 5) |
- |
- |
- |
- |
- |
- |
- |
UNICRED (136) |
✔️ |
✔️ |
✔️(obs 5) |
✔️(obs 5) |
✔️ |
✔️ |
- |
- |
- |
- |
- |
Cresol (133) |
✔️ |
✔️ |
- |
- |
- |
- |
- |
- |
- |
- |
- |
Banco de Brasília (070) |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
- |
Banco Sofisa (637) |
- |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
- |
- |
- |
Uniprime Norte do Paraná (084) |
- |
✔️ |
- |
- |
- |
- |
- |
- |
- |
- |
- |
Obs 1: O Banco Bradesco possui homologado conosco a Consulta via WebService apenas na modalidade ShopFácil.
Obs 2: Para o Banco do Brasil e Itaú, atualmente o PlugBoleto conta com todas as camadas de comunicação com o banco disponíveis via WebService (API). Ou seja, todos os recursos contemplados pela VAN Bancária estão também disponíveis via API. Deste modo, a integração por API se torna mais interessante pois é um modelo de comunicação mais ágil e robusto.
Neste link você pode consultar a documentação do recurso para efetuar a ativação desta modalidade de comunicação para o Banco do Brasil.
E Neste link você pode consultar a documentação do recurso para efetuar a ativação desta modalidade de comunicação para o Itaú.
Obs 3: Na V3 do banco Sicredi, as consultas automáticas de nossa API ocorrerão pelos seguintes horários: 7h, 15h e 19h.
Obs 4: As funcionalidades foram recentemente criadas e testadas, seguindo a documentação que está sujeita a alterações no início do uso direto com o banco.
Obs 5: Os bancos 136 e 085 são cooperativas e existem diferenças no funcionamento entre elas. Caso precise utilizar a VAN, confirme com sua agência se ela possui integração neste tipo de serviço, e na sequência, confirme com a nossa equipe técnica se há a integração junto à sua cooperativa.
Bancos Homologados com necessidade de acompanhamento da TecnoSpeed
Abaixo está a listagem de bancos compatíveis com o PlugBoleto, mas que necessitam de uma validação de layout da instituição bancária antes da entrada em produção.
Esta validação é importante pois se tratam de bancos com um volume menor de emissões, e por isso, estão sujeitos à ajustes. Nossa equipe de atendimento te apoiará nesta validação e nas eventuais solicitações de adequações vindas do banco.
240: Layout homologado no CNAB 240
400: Layout homologado no CNAB 400
Automática: Banco com homologação para a transmissão automática de remessa e retorno.
Registro WS: Banco homologado com registro via Web Service Bancário
Consulta WS: Banco homologado com a Consulta de boletos via Web Service Bancário
Validador: Banco com validação de layout.
Banco |
240 |
400 |
VAN Nexxera |
VAN Finnet |
Registro WS |
Consulta WS |
WS Homologação |
Validador |
Banco Athena (000) |
- |
✔️(obs 6) |
- |
|
- |
- |
- |
- |
Banco do Nordeste (004) |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
BS2 (218) |
- |
✔️ |
- |
✔️ |
- |
- |
- |
- |
Banco ABC Brasil S.A (246) |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
Banco C6 (336) |
- |
✔️ |
✔️ |
|
- |
- |
- |
- |
Bank of America (755) |
✔️ |
- |
✔️ |
✔️ |
- |
- |
- |
- |
Uniprime Iguaçu (099) |
- |
✔️ |
✔️(obs 7) |
- |
- |
- |
- |
- |
Banco da Amazônia (003) |
✔️ |
- |
✔️ |
✔️ |
- |
- |
- |
- |
Citibank (745) |
|
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
Banco Fibra (224) |
- |
✔️ |
- |
|
- |
- |
- |
- |
Banco Banestes (021) |
✔️ |
- |
✔️ |
✔️ |
- |
- |
- |
✔️ |
Banco Alfa (025) |
- |
✔️ |
- |
|
- |
- |
- |
- |
Banco Banpará (037) |
✔️ |
- |
- |
- |
- |
- |
- |
- |
Banese (047) |
✔️ |
- |
- |
- |
- |
- |
- |
- |
CREDISAN (089) |
- |
✔️ |
- |
- |
- |
- |
- |
- |
BRK (092) |
- |
✔️ |
- |
- |
- |
- |
- |
- |
Banco Grafeno | Banco MoneyPlus (274) |
- |
✔️ |
- |
- |
- |
- |
- |
- |
BCN (291) |
✔️ |
- |
- |
|
- |
- |
- |
- |
Banco Mercantil do Brasil (389) |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
Banco Voiter (ex Indusval) (653) |
✔️ |
✔️ |
✔️ |
✔️ |
- |
- |
- |
- |
Banco Votorantim (655) |
✔️ |
- |
✔️ |
✔️ |
- |
- |
- |
- |
Vortx |
- |
- |
- |
|
✔️ |
✔️ |
- |
- |
Obs 6: O Banco Athena está homologado no CNAB 444, exclusivamente.
Obs 7: O Banco UniPrime Iguaçu não está disponível para a VAN Finnet, apenas para a VAN Nexxera.
Bancos Compatíveis
Existe compatibilidade com algumas instituições que atualmente estão incorporadas a outros bancos. São elas:
Banco | Incorporado ao: |
Nossa Caixa (151) | Banco do Brasil |
Sudameris (347) | Santander |
Banespa (353) | Santander |
Banco Real (356) | Bradesco |
HSBC (399) | Bradesco |
Unibanco (409) | Itaú |
BankBoston (479) | Itaú |
Como solicitar homologação de novos bancos no PlugBoletos
Atualmente, nossa integração com Boletos possui diversas instituições financeiras homologadas, que podem ter suas respectivas disponibilidades em nosso produto consultadas no link abaixo:
Bancos Homologados: https://atendimento.tecnospeed.com.br/hc/pt-br/articles/360015272893-Bancos-Homologados
Contudo, sabemos da importância de novas integrações para atender as demandas de nossos clientes. Nesse sentido, através desta documentação, vou lhe apresentar como você pode solicitar a homologação de um novo banco ou método de transmissão para nossa aplicação de boletos.
* Antes de tudo, é essencial que você tenha em mãos o manual bancário do layout que você deseja homologar em nossa API, seja o CNAB 240, 400, ou transmissão via API / WS.
Passos para solicitar a Homologação de novos bancos:
- Acesse a sua Central do Cliente (https://clientes.tecnospeed.com.br)
- Realizar a abertura de um ticket ou chat com o time Fintech.
- No ticket ou atendimento via chat, informe ao atendente que você deseja homologar um novo banco, e encaminhe a documentação bancária que você obteve para solicitar esta integração.
- Caso você encaminhe no chat, o nosso atendente estará convertendo o atendimento para ticket e encaminhando a solicitação para a análise do nosso PO. Se o envio foi via ticket, o chamado também será disponibilizado para o PO do produto diretamente.
- Após essa etapa, o PO fará um orçamento de custos e prazos para a homologação do layout, e te encaminhará a proposta via email e no ticket que foi aberto para as tratativas.
- Sinalizando o aceite da proposta, nosso time iniciará a homologação e trabalhará para entrega-la no prazo estipulado junto ao PO da operação.
Rate limites no boleto
O rate limit é uma salvaguarda essencial implementada por provedores de API para mitigar sobrecargas nos servidores, especialmente em rotas sensíveis como a impressão de boletos.
Nas operações de impressão de boletos, seja de forma individual ou em lotes, um limite de 5 impressões por minuto é estabelecido. Ao ultrapassar esse limite, a API retorna o código HTTP 429, indicando o bloqueio temporário das requisições por um período de 1 minuto. Essa medida não apenas protege a infraestrutura do provedor contra congestionamentos, mas também garante a estabilidade e disponibilidade do serviço para todos os usuários, mantendo uma experiência consistente e confiável.
Outro rate limite que existe é por meio do waf nas rotas de impressão onde temos o limite de 500 requisições no intervalo de 5 minutos, onde após exceder essa regra o código HTTP retornado é 403.
Abaixo podemos ver as rotas que possuem rate limite e suas limitações:
Rota | Quantidade de requisições | Período |
/software-house/relatorios/van | 8 | 1 minuto |
/boletos/impressao/:id_integracao | 5 | 1 minuto |
/boletos/impressao/:id_integracao/pix | 5 | 1 minuto |
/boletos/impressao/* | 500 | 5 minutos |
Verificar saúde da API Plugboletos
A API Plugboletos oferece uma rota para verificar a saúde dos serviços. Essa funcionalidade permite que você confirme se a API está funcionando corretamente antes de realizar outras operações.
GET
Respostas da Rota
A rota /status
retornará um código de status HTTP que indica a saúde atual da API. Aqui está o significado dos códigos de status mais comuns:
- 200 OK: A API está em pleno funcionamento e pronta para processar solicitações.
- 503 Service Unavailable: A API está temporariamente indisponível ou em manutenção. Nesse caso, recomendamos aguardar e tentar novamente mais tarde.
Além disso, você pode consultar o corpo da resposta para obter informações adicionais, se necessário.
Lembre-se de que a verificação de saúde da API é uma etapa importante antes de utilizar outros recursos e operações disponíveis. Isso garante que você esteja se comunicando corretamente com a API Plugboletos e ajuda a evitar problemas durante a integração.
Como informar Desconto
Esta documentação foi feita considerando que a validação na emissão esta ativa.
Mais informações sobre o validador clique aqui.
Informando o 1º Desconto
Para emitir um boleto informando desconto, é obrigatório informar os campos TituloCodDesconto, TituloDataDesconto, TituloValorDescontoTaxa, e TituloValorDesconto onde:
Nome | Descrição | Exemplo |
TituloCodDesconto |
Campo onde pode ser informado o código para aplicar um determinado desconto. Códigos disponíveis: |
1 |
TituloDataDesconto | Campo onde pode ser informada a data limite para descontar um determinado valor. Formato DD/MM/YYYY | 27/12/2018 |
TituloValorDescontoTaxa | Campo onde pode ser informado o valor/taxa de um determinado desconto. *Valor irá sair na remessa, para ser descontado automaticamente, quando for pago. |
2,00 |
TituloValorDesconto |
Informe o mesmo valor do TituloValorDescontoTaxa, apenas se desejar visualizá-lo o campo de desconto no boleto em PDF. *Valor irá sair na remessa, para ser descontado automaticamente. |
2,00 |
Exemplo
Os exemplos abaixo foram feitos considerando que o banco aceita determinado valor para o campo TituloCodDesconto, ao utilizar o validador, o boleto será rejeitado na emissão se informado um valor diferente do aceito pelo banco.
Desconto em valor fixo até a data informada
Ao informar o campo TituloCodDesconto com o valor 1 automáticamente o valor informado em TituloValorDescontoTaxa será um valor monetário, que será descontado se o boleto for pago antes da data informada no campo TituloDataDesconto. Exemplo:
{
....
"TituloCodDesconto ": "1",
"TituloValorDescontoTaxa": "1,55",
"TituloDataDesconto": "07/01/2020"
....
}
Informando desta forma, se o boleto for pago antes da data informada no campo TituloDataDesconto
será descontado o valor de R$ 1,55.
Desconto em porcentagem até a data informada
Ao informar o campo TituloCodDesconto com o valor 2 automáticamente o valor informado em TituloValorDescontoTaxa será o valor em % sobre o valor total do boleto. Exemplo:
{
....
"TituloCodDesconto ": "2",
"TituloValorDescontoTaxa": "10,00",
"TituloDataDesconto": "DD/MM/AAAA"
....
}
Informando desta forma, se o boleto for pago antes da data informada no campo TituloDataDesconto
será descontado o valor de 10% sobre o valor total do boleto.
Supondo que um boleto tem um valor de R$ 100,00, será descontado o valor de R$ 10,00
Informando o 2º Desconto
Para informar mais de um desconto basta seguir as recomendações passadas acima, utilizando os campos TituloCodDesconto2, TituloDataDesconto2, e TituloValorDescontoTaxa2
Informando o 3º Desconto (Disponível apenas para Caixa via WS)
Para informar mais de um desconto basta seguir as recomendações passadas acima, utilizando os campos TituloCodDesconto3, TituloDataDesconto3, e TituloValorDescontoTaxa3
Como informar Multa
Quando emitimos boletos, algo muito importante é a informação no tx2/json de envio as informações de juros e multa. Neste post, iremos abordar a forma de informar a multa, utilizando a API PlugBoleto para a emissão de boletos.
Esta documentação foi feita considerando que a validação na emissão esta ativa.
Mais informações sobre o validador clique aqui.
Informando a Multa
Para emitir um boleto informando multa, é obrigatório informar os campos TituloCodigoMulta, TituloDataMulta, e TituloValorMultaTaxa, onde:
Nome | Descrição | Exemplo |
TituloCodigoMulta |
Campo onde pode ser informado o código para aplicar um determinada multa. Códigos disponíveis: |
1 |
TituloDataMulta | Campo onde pode ser informada a data para cobrar um determinado valor de Multa. Formato DD/MM/YYYY | 27/12/2018 |
TituloValorMultaTaxa | Campo onde pode ser informado o valor/taxa de uma determinada multa. *Valor irá sair na remessa, para ser calculado automaticamente, quando for pago. |
2,00 |
Exemplo
Os exemplos abaixo foram feitos considerando que o banco aceita determinado valor para o campo TituloCodigoMulta, ao utilizar o validador, o boleto será rejeitado na emissão se informado um valor diferente do aceito pelo banco.
Multa em valor monetário
Ao informar o campo TituloCodigoMulta com o valor 1 automáticamente o valor informado em TituloValorMultaTaxa será um valor monetário. Exemplo:
{
....
"TituloCodigoMulta": "1",
"TituloValorMultaTaxa": "1,55",
"TituloDataMulta": "07/01/2020"
....
}
Informando desta forma após a data informada no campo TituloDataMulta
será cobrado o valor de R$ 1,55 de multa.
Multa em porcentagem
Ao informar o campo TituloCodigoMulta com o valor 2 automáticamente o valor informado em TituloValorMultaTaxa será o valor da taxa sobre o valor total do boleto. Exemplo:
{
....
"TituloCodigoMulta": "2",
"TituloValorMultaTaxa": "2,00",
"TituloDataMulta": "DD/MM/AAAA"
....
}
Informando desta forma após a data informada no campo TituloDataMulta
será cobrado o valor de 2% sobre o valor total do boleto.
Supondo que um boleto tem um valor de R$ 100,00, será cobrado o valor de R$ 2,00
Como informar Juros
Quando emitimos boletos, algo muito importante é a informação no tx2/json de envio as informações de juros e multa. Iremos abordar a forma de fazermos isto utilizando a API PlugBoleto para a emissão de boletos.
Esta documentação foi feita considerando que a validação na emissão esta ativa.
Mais informações sobre o validador clique aqui.
Informando Juros
Para emitir um boleto informando Juros, é obrigatório informar os campos TituloCodigoJuros, TituloDataJuros, e TituloValorJuros, onde:
Nome | Descrição | Exemplo |
TituloCodigoJuros |
Campo onde pode ser informado o código para aplicar um determinado juros. Códigos disponíveis: |
1 |
TituloDataJuros | Campo onde pode ser informada a data de inicio para cobrar um determinado valor de juros/mora. Formato DD/MM/YYYY | 27/12/2018 |
TituloValorJuros | Campo onde pode ser informado o valor/taxa de um determinado juros/mora. *Valor irá sair na remessa, para ser calculado automaticamente, quando for pago. |
2,00 |
Exemplo
Os exemplos abaixo foram feitos considerando que o banco aceita determinado valor para o campo TituloCodigoJuros, ao utilizar o validador, o boleto será rejeitado na emissão se informado um valor diferente do aceito pelo banco.
Juros monetário por dia
Ao informar o campo TituloCodigoJuros com o valor 1 automaticamente o valor informado em TituloValorJuros será um valor monetário cobrando por dia. Exemplo:
{
....
"TituloCodigoJuros": "1",
"TituloValorJuros": "1,55",
"TituloDataJuros": "DD/MM/AAAA"
....
}
Informando desta forma após a data informada no campo TituloDataJuros
será cobrado o valor de R$ 1,55 ao dia.
Juros em porcentagem mensal
Ao informar o campo TituloCodigoJuros com o valor 2 automaticamente o valor informado em TituloValorJuros será o valor da taxa mensal. Exemplo:
{
....
"TituloCodigoJuros ": "2",
"TituloValorJuros": "2,00",
"TituloDataJuros": "DD/MM/AAAA"
....
}
Informando desta forma após a data informada no campo TituloDataJuros
será cobrado o valor de 2% ao mês sobre o valor total do boleto (0,066% ao dia).
Supondo que um boleto tem um valor de R$ 100,00, será cobrado o valor de R$ 0,07 ao dia.
Como informar Baixa
Nome | Tamanho | Descrição | Exemplo |
TituloCodBaixaDevolucao | 1 - 1 |
Campo onde pode ser informado o código para aplicar uma determinada baixa. Códigos disponíveis: |
1 |
TituloPrazoBaixa | 1 - 3 | Campo onde pode ser informada a quantidade de dias após o vencimento para realizar a baixa automática. | 30 |
Como informar Protesto
O que é o Protesto?
O protesto de títulos é uma instrução que pode ser enviada no momento da emissão para que o banco possa aplicar o protesto a títulos não pagos a partir da data que você definir.
Como fazer?
Para informar protesto de forma automática em seu boleto adicione os seguintes campos:
Nome | Tamanho | Descrição | Exemplo |
TituloCodProtesto | 1 - 1 |
Campo onde pode ser informado o código para aplicar um determinado protesto. Códigos disponíveis: |
1 |
TituloPrazoProtesto | 1 - 3 | Campo onde pode ser informada a quantidade de dias após o vencimento para realizar o protesto automático. | 30 |
Demonstrações de Uso das APIs PlugBank
Nesta seção, você encontrará demonstrações práticas de como utilizar as APIs de nossos produtos. Essas demonstrações foram criadas com o intuito de fornecer um ponto de partida para a integração do seu sistema com nossa API.
É importante destacar que esses exemplos são materiais básicos e demonstrativos, destinados a ilustrar o processo de integração de forma simples e direta. Eles não fazem uso de recursos avançados das linguagens de programação e não se preocupam com as melhores práticas de programação. Portanto, considere essas demonstrações como um ponto de partida e não como implementações finais.
Além disso, trabalhamos na criação de novas demonstrações que refletem as implementações mais atuais e funcionais. Isso significa que esta seção de demonstrações será atualizada regularmente, proporcionando a você acesso a exemplos práticos e recursos recentes de nossas APIs.
PlugBoleto
https://github.com/tecnospeed/Componente-Boleto/tree/master/demonstracoes
API de Pagamentos
https://github.com/tecnospeed/API_Pagamentos/tree/master/Demostracoes
PlugPix
https://github.com/tecnospeed/API_PIX/tree/main/Demonstracoes
Comentários
0 comentário
Por favor, entre para comentar.