Boleto Fácil

A integração via API é a forma mais avançada de integração.
Conhecimentos de programação são fundamentais neste caso.

Índice:

• Testes
• Token
• Geração de cobranças
• Notificação de pagamentos
• Consulta de pagamentos e cobranças
• Simulação de pagamentos
• Consulta de saldo
• Solicitação de transferência
• Cancelamento de cobrança
• Plugins e Sistemas

Testes

Para testes utilize o ambiente Sandbox: https://sandbox.boletobancario.com/boletofacil

Neste ambiente você poderá simular pagamentos para testar o ciclo completo.

Este ambiente é totalmente separado do ambiente de produção, portanto você deve criar um novo cadastro nele.

Token

Para a integração será utilizado um token de identificação da sua conta.

Geração de cobranças

Método

A geração de boletos é feita através de requisições HTTPS, que podem utilizar tanto o método POST quanto o método GET.

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge

Charset

Todas as requisições feitas pelo seu sistema ao Boleto Fácil devem utilizar UTF-8. As respostas enviadas pelo Boleto Fácil também utilizam este mesmo charset.

Atenção

Antes de utilizar em produção, certifique-se de que o cadastro no Boleto Fácil esteja verificado para não haver problema com limites de emissão.

Parâmetros

Parâmetro	Descrição	Obrigatório
token	O token do Favorecido, que pode ser gerado acima	Sim
description	Descrição sobre a que se refere o pagamento Formato: Livre com até 400 caracteres - Até 4 linhas Exemplos: Pedido 48192 / TV 40 Polegadas / Cosméticos	Sim
reference	Código de referência da cobrança Este código fica associado à(s) cobrança(s) criada(s) por esta requisição e é útil para vincular as transações do Boleto Fácil às vendas registradas no seu sistema Formato: Livre com até 255 caracteres	Não
amount	Valor do boleto ou da parcela no caso de cobrança parcelada Formato: Decimal, separado por ponto. Maior ou igual a 2.30 e menor ou igual a 1000000.00	Sim
dueDate	Data de vencimento do boleto ou da primeira parcela, no caso de cobrança parcelada Para parcelamento as prestações terão vencimento com 1 mês de intervalo, a partir da data informada Formato: dd/mm/aaaa Valor padrão: Se não definido será 3 dias após a data de emissão	Não
installments	Número de parcelas da cobrança Se igual a 1, será gerado um boleto simples, se 2 ou mais, será gerado um carnê Formato: Número inteiro maior ou igual a 1 e menor ou igual a 12 Valor padrão: 1	Não
maxOverdueDays	Número máximo de dias que o boleto poderá ser pago após o vencimento Zero significa que o boleto não poderá ser pago após o vencimento Formato: Número inteiro maior ou igual a 0 e menor ou igual a 90 Valor padrão: 0	Não
fine	Multa para pagamento após o vencimento Só é efetivo se maxOverdueDays for maior que zero Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor ou igual a 20.00 (2.00 é o valor máximo permitido por lei) Valor padrão: 0.00	Não
interest	Juros para pagamento após o vencimento Só é efetivo se maxOverdueDays for maior que zero Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor ou igual a 20.00 (1.00 é o valor máximo permitido por lei) Valor padrão: 0.00	Não
discountAmount	Valor do desconto Formato: Decimal, separado por ponto. Maior ou igual a 0.00 e menor que o valor da cobrança (amount) Valor padrão: 0.00	Não
discountDays	Dias concessão de desconto para pagamento antecipado. Exemplo: Até 10 dias antes do vencimento. Formato: Número inteiro maior ou igual a -1 Valor padrão: -1 Atenção: Valor igual a 0 (zero) significa conceder desconto até a data do vencimento	Não
payerName	Nome completo do comprador Formato: Livre com até 80 caracteres	Sim
payerCpfCnpj	CPF ou CNPJ do comprador Formato: CPF ou CNPJ válido, aceito com ou sem pontuação	Sim
payerEmail	Endereço de email do comprador Formato: Endereço de email válido, com até 80 caracteres	Não
payerSecondaryEmail	Endereço de email secundário do comprador Formato: Endereço de email secundário válido, com até 80 caracteres	Não
payerPhone	Telefone do comprador Formato: Livre com até 25 caracteres	Não
payerBirthDate	Data de nascimento do comprador Formato: dd/mm/aaaa	Não
billingAddressStreet	Nome da rua/logradouro do comprador Formato: Livre com até 80 caracteres	Não*
billingAddressNumber	Número da residência do comprador Formato: Livre com até 30 caracteres	Não*
billingAddressComplement	Complemento do endereço do comprador Formato: Livre com até 30 caracteres	Não
billingAddressCity	Cidade comprador Formato: Livre com até 60 caracteres	Não*
billingAddressState	Estado do comprador Formato: Nome do estado ou UF válida	Não*
billingAddressPostcode	CEP do comprador Formato: CEP válido com ou sem hífen	Não*
notifyPayer	Define se o Boleto Fácil enviará emails de notificação sobre esta cobrança para o comprador O email com o boleto ou carnê só será enviado ao comprador se este parâmetro for igual a true e o endereço de email do comprador estiver presente O lembrete de vencimento só será enviado se as condições acima forem verdadeiras e se na configuração do Favorecido os lembretes estiverem ativados Formato: true ou false Valor padrão: true	Não
notificationUrl	Define uma URL de notificação para que o Boleto Fácil envie notificações ao seu sistema sempre que houver algum evento de pagamento desta cobrança. Se preferir, você pode configurar uma URL de notificação para todas as suas cobranças no tópico Notificação de pagamentos. Formato: Endereço de URL com até 255 caracteres	Não
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não
feeSchemaToken	Define o token de um esquema de taxas e comissionamento alternativo	Não
splitRecipient	Destinatário da divisão de receitas (split), caso os boletos sejam emitidos pelo "dono" do esquema de taxas e comissionamento (split invertido)	Não

* Os dados do endereço do comprador são opcionais, porém se qualquer dos parâmetros for informado, os demais passam a ser obrigatórios, exceto complemento (billingAddressComplement), que é sempre opcional.

Exemplo de requisição

https://www.boletobancario.com/boletofacil/integration/api/v1/issue-charge?token=SEUTOKEN&description=Pedido1791&amount=12.75&payerName=Nome+Sobrenome&payerCpfCnpj=94648945123

Parâmetros de resposta

Parâmetro	Descrição
success	Indica se a requisição foi executada com sucesso ou não Formato: true ou false
errorMessage	Texto contendo a mensagem de erro, presente somente se success = false Formato: Texto livre
data	Dados da resposta, presente somente se success = true Formato: Este elemento é apenas um container para charges
charges	Lista das cobranças geradas, este elemento é filho de data Formato: Array de charge
charge	Detalhes da cobrança, este elemento é filho de charges Objeto contendo os atributos: - code: Código único de identificação da cobrança no Boleto Fácil - dueDate: Data de vencimento do boleto ou parcela - link: Link para visualização/download do boleto ou carnê * - payNumber: Linha digitável para pagamento online

* Sempre que uma requisição gerar múltiplas cobranças (carnê), todas terão o mesmo link, pois apesar de cada parcela ser tratada individualmente no Boleto Fácil, apenas um documento é gerado. Você pode utilizar o link para redirecionar o comprador para a página do boleto ou carnet, ou, por exemplo, gravar o documento em seu sistema. Os links são permanentes, em nenhuma hipótese são excluídos, assim como as cobranças geradas.

Status da resposta

Além do parâmetro success, é recomendada a verificação do status HTTP para determinar se uma requisição foi executada com sucesso ou não.

Status	Significado
200	Indica que a requisição foi executada com sucesso pelo Boleto Fácil O corpo da resposta conterá o resultado, JSON ou XML conforme opção
400	Indica que a requisição não passou pelas validações do Boleto Fácil, portanto nenhuma cobrança foi emitida O corpo da resposta conterá o resultado (mensagem de erro), JSON ou XML conforme opção
Qualquer outro status	Indica que a requisição falhou por motivos alheios ao Boleto Fácil. Exemplos: Request Timeout, Request-URI Too Long, etc. Nestes casos o corpo da resposta não conterá o resultado JSON ou XML, e sim uma mensagem produzida pelo servidor web, podendo ser vazio.

Exemplos de Resposta

Formato JSON - Sucesso

{
    "success": true,
    "data": {
        "charges":[
            {
                "code": 101,
                "dueDate": "19/02/2013",
                "link": "https://boletofacil/boleto?token=23:m:3454"
                "payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000"
            },
            {
                "code": 102,
                "dueDate": "19/03/2013",
                "link": "https://boletofacil/boleto?token=23:m:3454"
                "payNumber": "03399.63290 64000.001024 00236.601027 3 67150000015000"
            }
        ]
    }
}

Formato JSON - Erro

{
    "success":false,
    "errorMessage":"Parâmetro 'payerName' não pode ter mais de 60 caracteres"
}

Formato XML - Sucesso

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data>
        <charges>
            <charge>
                <code>101</code>
                <dueDate>19/02/2013</dueDate>
                <link>https://boletofacil/boleto?token=23:m:3454</link>
                <payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber>
            </charge>
            <charge>
                <code>102</code>
                <dueDate>19/03/2013</dueDate>
                <link>https://boletofacil/boleto?token=23:m:3454</link>
                <payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber>
            </charge>
        </charges>
    </data>
</result>

Formato XML - Erro

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>false</success>
    <errorMessage>Valor mínimo para cobrança é de R$ 2,30</errorMessage>
</result>

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>false</success>
    <errorMessage>Valor mínimo para cobrança é de R$ 2,30</errorMessage>
</result>

Notificação de pagamentos

Você pode configurar o Boleto Fácil para enviar notificações para seu sistema sempre que houver um evento de pagamento.

Passo 1 - Notificação

O Boleto Fácil executa uma requisição POST na URL definida por você, informando o paymentToken para consulta das informações do pagamento.

Parâmetros da Notificação

Parâmetro	Descrição
paymentToken	Token que deverá ser utilizado pelo seu sistema para consultar os detalhes do pagamento no Boleto Fácil
chargeReference	Código de referência da cobrança em seu sistema, informado no momento da emissão. Poderá, será vazio.
chargeCode	Código único da cobrança no Boleto Fácil

- O Boleto Fácil utiliza o status HTTP retornado pelo seu sistema para confirmar que a notificação foi bem sucedida, status 200, ou mal sucedida, qualquer outro status. - Serão feitas até 50 tentativas de notificação com intervalos de 2 horas, tentativas extras poderão ser feitas no momento da confirmação. - As notificações de pagamento serão enviadas apenas para cobran¸as geradas via API de integração.

Atenção: Por questões de segurança esta primeira requisição não deve ser utilizada para para confirmar um pagamento em seu sistema. Para isso, utilize o Passo 2.

Passo 2 - Consulta

Seu sistema utiliza o paymentToken informado para consultar detalhes do pagamento

URL: https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-payment-details

Parametros de consulta

Parâmetro	Descrição	Obrigatório
paymentToken	O token identificador do pagamento	Sim
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não

Parâmetros da Resposta

Parâmetro	Descrição
success	Indica se a requisição foi executada com sucesso ou não Formato: true ou false
errorMessage	Texto contendo a mensagem de erro, presente somente se success = false Formato: Texto livre
data	Dados da resposta, presente somente se success = true Formato: Este elemento é apenas um container para payment
payment	Dados do pagamento Formato: Objeto
payment.id	Identificador único do pagamento no Boleto Fácil Formato: Número inteiro
payment.amount	Valor pago Formato: Decimal, separado por ponto
payment.date	Data do registro do pagamento no banco Formato: dd/mm/aaaa
payment.fee	Taxa sobre o pagamento, em Reais. Formato: Decimal, separado por ponto
payment.charge	Dados da cobrança associada a este pagamento Formato: Objeto
charge.code	Código único da cobrança no Boleto Fácil Formato: Número inteiro
charge.reference	Código de referência da cobrança em seu sistema Formato: Livre com até 255 caracteres
charge.amount	Valor cobrado Formato: Decimal, separado por ponto
charge.dueDate	Data de vencimento do boleto Formato: dd/mm/aaaa

Status da resposta

Além do parâmetro success, é recomendada a verificação do status HTTP para determinar se uma requisição foi executada com sucesso ou não.

Status	Significado
200	Indica que a requisição foi executada com sucesso pelo Boleto Fácil O corpo da resposta conterá o resultado, JSON ou XML conforme opção
400	Indica que a requisição não passou pelas validações do Boleto Fácil O corpo da resposta conterá o resultado, JSON ou XML conforme opção
Qualquer outro status	Indica que a requisição falhou por motivos alheios ao Boleto Fácil. Exemplos: Request Timeout, Request-URI Too Long, etc. Nestes casos o corpo da resposta não conterá o resultado JSON ou XML, e sim uma mensagem produzida pelo servidor web, podendo ser vazio.

Exemplos de Resposta

Formato JSON - Sucesso

{
    "success":true,
    "data":{
        "payment":{
            "id":32,
            "amount":95.00,
            "date":"19/02/2013",
            "fee":2.68,
            "charge":{
                "amount":95.00,
                "code":101,
                "dueDate":"21/02/2013",
                "reference":"yourChargeRef5291"
            }
        }
    }
}

Formato JSON - Erro

{
    "success":false,
    "errorMessage":"Token inválido"
}

Formato XML - Sucesso

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data>
        <payment>
            <id>32</id>
            <amount>95.00</amount>
            <date>19/02/2013</date>
            <fee>2.68</fee>
            <charge>
                <code>101</code>
                <reference>yourChargeRef5291</reference>
                <amount>95.00</amount>
                <dueDate>21/02/2013</dueDate>
            </charge>
        </payment>
    </data>
</result>

Formato XML - Erro

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>false</success>
    <errorMessage>Token inválido</errorMessage>
</result>

Pagamentos duplicados

- Apesar de pouco comum, é possível que um mesmo boleto seja pago múltiplas vezes. Recomendamos a utilização do id do pagamento para tratar estes casos.

- Por conta da possibilidade de pagamentos duplicados, notificações para cobranças com um pagamento já confirmado não devem ser ignoradas pelo seu sistema caso deseje fazer o tratamento automático.

- Opcionalmente você poderá tratar os pagamentos duplicados manualmente, o Boleto Fácil envia mensagens para o email de cadastro do favorecido com informações sobre cada pagamento duplicado.

Consulta de pagamentos e cobranças

DESCRIÇÃO

Caso seu sistema não possua uma URL para callback para receber as notificações de pagamento, este método pode ser utilizado para consultar ativamente pagamentos e cobranças.

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges

LIMITE

No ambiente de produção há um limite de 5 consultas diárias por cadastro, uma vez atingido este limite as consultas subseqüentes falharão com uma mensagem de erro apropriada.

Exemplo de requisição

https://www.boletobancario.com/boletofacil/integration/api/v1/list-charges?token=SEUTOKEN&beginPaymentDate=01/07/2017

Parâmetros

Parâmetro	Descrição	Obrigatório
token	O token do Favorecido	Sim
beginDueDate	Data de Vencimento - a partir de Formato: dd/mm/aaaa	Não*
endDueDate	Data de Vencimento - até Formato: dd/mm/aaaa	Não
beginPaymentDate	Data de Pagamento - a partir de Formato: dd/mm/aaaa	Não*
endPaymentDate	Data de Vencimento - até Formato: dd/mm/aaaa	Não
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não

* É necessário informar ao menos uma data inicial (beginDueDate ou beginPaymentDate).

Parâmetros de resposta

Parâmetro	Descrição
success	Indica se a requisição foi executada com sucesso ou não Formato: true ou false
errorMessage	Texto contendo a mensagem de erro, presente somente se success = false Formato: Texto livre
data	Dados da resposta, presente somente se success = true Formato: Este elemento é apenas um container para charges
charges	Lista das cobranças geradas, este elemento é filho de data Formato: Array de charge
charge	Detalhes da cobrança, este elemento é filho de charges Objeto contendo os atributos: - code: Código único de identificação da cobrança no Boleto Fácil - dueDate: Data de vencimento do boleto ou parcela - link: Link para visualização/download do boleto ou carnê * - payNumber: Linha digitável para pagamento online
payments	Lista dos pagamentos efetuados para esta cobrança, este elemento é filho de data Formato: Array de payment
payment	Detalhes do pagamento efetuado, este elemento é filho de payments Objeto contendo os atributos: - id: Código único de identificação do pagamento no Boleto Fácil - amount: O valor do pagamento efetuado - date: Data do pagamento efetuado - fee: Taxa sobre o pagamento, em Reais - type: Tipo de pagamento - status: Status do pagamento

Exemplos de Resposta

Formato JSON - Sucesso

{
    "success": true,
    "data": {
        "charges":[
            {
                "code": 101,
                "dueDate": "19/02/2013",
                "link": "https://boletofacil/boleto?token=23:m:3454"
                "payNumber": "03399.63290 64000.001014 00236.601027 8 67150000025000",
                "payments": [
                    {
                       "id": 1113123,
                       "amount": 163.9,
                       "date": "19/07/2017",
                       "fee": 4.34,
                       "type": "BOLETO",
                       "status": "CONFIRMED"
                    }
                ]
            },
            {
                "code": 102,
                "dueDate": "19/03/2013",
                "link": "https://boletofacil/boleto?token=23:m:3454"
                "payNumber": "03399.63290 64000.001024 00236.601027 3 67150000015000",
                "payments": [
                    {
                        "id": 1113122,
                        "amount": 1141.4,
                        "date": "19/07/2017",
                        "fee": 27.8,
                        "type": "BOLETO",
                        "status": "NEEDS_CHECK"
                    }
                ]
            }
        ]
    }
}

Formato JSON - Erro

{
    "success":false,
    "errorMessage":"A data de início de pagamento não pode ser menor que 5 dias a partir do dia de hoje"
}

Formato XML - Sucesso

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data>
        <charges>
            <charge>
                <code>101</code>
                <dueDate>19/02/2013</dueDate>
                <link>https://boletofacil/boleto?token=23:m:3454</link>
                <payNumber>03399.63290 64000.001014 00236.601027 8 67150000025000</payNumber>
                <payments>
                    <payment>
                        <id>1113123</id>
                        <amount>163.90</amount>
                        <date>19/07/2017</date>
                        <fee>4.34</fee>
                        <type>BOLETO</type>
                        <status>CONFIRMED</status>
                    </payment>
                </payments>
            </charge>
            <charge>
                <code>102</code>
                <dueDate>19/03/2013</dueDate>
                <link>https://boletofacil/boleto?token=23:m:3454</link>
                <payNumber>03399.63290 64000.001024 00236.601027 3 67150000015000</payNumber>
                <payments>
                    <payment>
                        <id>1113122</id>
                        <amount>1141.40</amount>
                        <date>19/07/2017</date>
                        <fee>27.80</fee>
                        <type>BOLETO</type>
                        <status>NEEDS_CHECK</status>
                    </payment>
                </payments>
            </charge>
        </charges>
    </data>
</result>

Formato XML - Erro

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>false</success>
    <errorMessage>A data de início de pagamento não pode ser menor que 5 dias a partir do dia de hoje</errorMessage>
</result>

Simulação de pagamentos

Esta opção permite testes do ciclo completo de cobrança/pagamento.

A simulação está disponível no ambiente Sandbox: https://sandbox.boletobancario.com/boletofacil

Você pode simular pagamentos diretamente na página de cobranças!

Consulta de Saldo

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/fetch-balance

Parâmetros

Parâmetro	Descrição	Obrigatório
token	O token do Favorecido	Sim
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não

Exemplos de Resposta

Formato JSON

{
    "success": true,
    "data": {
        "balance": 100
        "withheldBalance": 30
        "transferableBalance": 70
    }
}

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data>
        <balance>100.00</balance>
        <withheldBalance>30.00</withheldBalance>
        <transferableBalance>70.00</transferableBalance>
    </data>
</result>

Solicitação de Transferência

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/request-transfer

Parâmetros

Parâmetro	Descrição	Obrigatório
token	O token do Favorecido	Sim
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não

Exemplos de Resposta

Formato JSON

{
    "success": true,
    "data": null
}

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data/>
</result>

Cancelamento de cobrança

URL

https://www.boletobancario.com/boletofacil/integration/api/v1/cancel-charge

Parâmetros

Parâmetro	Descrição	Obrigatório
token	O token do Favorecido	Sim
code	Código único de identificação da cobrança Formato: Número inteiro	Sim
responseType	Define o tipo de resposta à esta requisição Formato: JSON ou XML Valor padrão: JSON	Não

Exemplos de Resposta

Formato JSON

{
    "success": true,
    "data": null
}

Formato XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<result>
    <success>true</success>
    <data/>
</result>

Em caso de dúvidas, entre em contato.

Botão de pagamento

Cobrar diretamente em seu website requer apenas 2 passos:

Integração via API

A integração via API é a forma mais avançada de integração.Conhecimentos de programação são fundamentais neste caso.

Testes

Token

Geração de cobranças

Método

URL

Charset

Atenção

Parâmetros

Exemplo de requisição

Parâmetros de resposta

Status da resposta

Exemplos de Resposta

Notificação de pagamentos

Passo 1 - Notificação

Parâmetros da Notificação

Passo 2 - Consulta

Parametros de consulta

Parâmetros da Resposta

Status da resposta

Exemplos de Resposta

Pagamentos duplicados

Consulta de pagamentos e cobranças

DESCRIÇÃO

URL

LIMITE

Exemplo de requisição

Parâmetros

Parâmetros de resposta

Exemplos de Resposta

Simulação de pagamentos

Consulta de Saldo

URL

Parâmetros

Exemplos de Resposta

Solicitação de Transferência

URL

Parâmetros

Exemplos de Resposta

Cancelamento de cobrança

URL

Parâmetros

Exemplos de Resposta

Editar configurações do Favorecido

Confirmar

Excluir

A integração via API é a forma mais avançada de integração.
Conhecimentos de programação são fundamentais neste caso.