Documentação para Desenvolvedores

Boletos

Recurso Descrição
POST /api/v1/bank_billets Criar boleto
GET /api/v1/bank_billets/:id Informações do boleto
GET /api/v1/bank_billets Listar boletos
PUT /api/v1/bank_billets/:id/cancel Cancelar boleto
PUT /api/v1/bank_billets/:id Alterar boleto
POST /api/v1/bank_billets/:id/duplicate Duplicar boleto
GET /api/v1/bank_billets/cnpj_cpf Buscar por CPF ou CNPJ
GET /api/v1/bank_billets/our_number Buscar por nosso número
GET /api/v1/bank_billets/status Buscar por Situação do boleto (possíveis valores)
PUT /api/v1/bank_billets/:id/pay Marcar boleto como pago

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id N/A Integer   ID do boleto
bank_billet_account_id Sim Integer   ID da Carteira de Cobrança. Se não informado, usará a carteira padrão.
our_number Não Integer   Nosso Número. Se não informado, usará o Próximo Nosso Número da Carteira de Cobrança.
amount Sim String   Quantia (R$) Formato: 1.345,56
expire_at Sim Date   Data de vencimento
description Sim Text   Descrição do produto ou serviço
customer_id Não Integer   ID do Cliente. Quando esse ID é passado, os campos customer_person_name, customer_cnpj_cpf, customer_zipcode, customer_address, customer_city_name, customer_state e customer_neighborhood não são obrigatórios.
customer_person_name Sim String 255 Nome ou Razão Social do Pagador
customer_cnpj_cpf Sim String 20 CNPJ ou CPF do Pagador
customer_zipcode Sim Integer 8 CEP (formato 99999999)
customer_email Não String 255 E-mail do Pagador
customer_address Sim Text   Endereço
customer_city_name Sim String 255 Cidade(Nome deve estar correto e completo)
customer_state Sim String 2 Estado
customer_neighborhood Sim String 255 Bairro
customer_address_number Não String 255 Número
customer_address_complement Não String 255 Complemento
customer_phone_number Não String 255 Telefone (com DDD)
customer_person_type N/A String 255 Tipo de pagador (possíveis valores)
meta Não Campo Genérico   Aceita qualquer formato passado. Pode ser usado para salvar dados que não existam dentro do Boleto Simples. Exemplo: {pedido: 12345}
status N/A String   Situação do boleto (possíveis valores)
paid_at N/A Date   Data do pagamento
paid_amount N/A Float   Valor pago
shorten_url N/A String   URL para visualização do boleto
url N/A String   URL para visualização do boleto
carne_url N/A String   URL para visualização do carnê(Quando for parcela)
formats N/A String   URLs com formatos PDF e Imagem visualização do boleto
created_via_api N/A Boolean   Define se o boleto foi criado pela API
fine_for_delay Não Float   Multa por Atraso Ex: 2% x R$ 250,00 = R$ 5,00
late_payment_interest Não Float   Juros de Mora Mensal (O valor será dividido por 30. Ex 3% = 0,1% ao dia.)
guarantor_name Não String   Sacador/Avalista
guarantor_cnpj_cpf Não String   CNPJ/CPF do Sacador/Avalista
payment_place Não String   Local de Pagamento
instructions Não String   Instruções para o Caixa
document_date Não Date   Data do Documento
document_type Não String   Tipo de Documento
document_number Não Integer   Número do Documento
acceptance Não String   Aceite
bank_billet_layout_id Não Integer   ID do Modelo de Boleto
remittance_id Não Integer   ID da Remessa
notes Não Text   Anotações
tags Não Array   Tags associadas ao boleto
created_at N/A Date   Data de criação do boleto
updated_at N/A Date   Data de atualização do boleto
paid_bank N/A String   Banco de Pagamento
paid_agency N/A String   Agência de Pagamento
line N/A String   Linha Digitável
bank_rate N/A Float   Taxa bancária
beneficiary_name N/A String   Nome do Beneficiário
beneficiary_cnpj_cpf N/A String   CNPJ/CPF do Beneficiário
beneficiary_address N/A String   Endereço do Beneficiário
beneficiary_assignor_code N/A String   Agência/Código do Beneficiário
processed_our_number N/A String   Nosso Número com DV (formatado)
processed_our_number_raw N/A String   Nosso Número com DV (limpo)
bank_contract_slug N/A String   Slug da Carteira
agency_number N/A String   Agência
agency_digit N/A String   Dígito da Agência
account_number N/A String   Conta
account_digit N/A String   Dígito da Conta
extra1 N/A String   Campo extra 1
extra1_digit N/A String   Digito do Campo extra 1
extra2 N/A String   Campo extra 2
extra2_digit N/A String   Dígito do Campo extra 2
customer_subscription_id N/A Integer   ID da Assinatura
installment_number N/A Integer   Número da parcela do carnê
installment_id N/A Integer   ID do Carnê
bank_billet_discharges N/A Array   Retornos bancários

Dicionário de Dados

status

generating Gerando
opened Aberto
canceled Cancelado
paid Pago
overdue Vencido

acceptance

S Sim
N Não

customer_person_type

individual Pessoa Física
juridical Pessoa Jurídica

Criar boleto

POST /api/v1/bank_billets

ATENÇÃO: Apesar de receber a resposta com os dados do boleto, isso, somente, não garante que o boleto esteja pronto para uso. Isso apenas indica que o boleto foi aceito e cadastrado em sua conta.

A partir desse momento o boleto entra em uma fila para ser gerado por completo(código de barras, linha digitável, layout).

Após o boleto ser gerado por completo seu status mudará para opened.

Só então você poderá disponibilizar o boleto aos seus clientes.

Para saber se um boleto foi gerado por completo, você deve preparar seu sisema para receber nossos Webhooks

Será retornado 404 Not Found ao tentar acessar a url de um boleto que ainda esteja sendo gerado(generating).

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet":{}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/bank_billets'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
...

{"errors":{"bank_billet":["não pode ficar em branco"]}}
Requisição:
@bank_billet = BoletoSimples::BankBillet.create({amount: 9.10})
if @bank_billet.persisted?
  puts "Sucesso :)"
  puts @bank_billet.attributes
else
  puts "Erro :("
  puts @bank_billet.response_errors
end
Resposta:
Erro :(
{
  :expire_at => [
    [0] "não pode ficar em branco",
    [1] "não é uma data válida"
  ],
  :customer_person_name => [
    [0] "não pode ficar em branco"
  ],
  :customer_cnpj_cpf => [
    [0] "não pode ficar em branco"
  ],
  :description => [
    [0] "não pode ficar em branco"
  ],
  :customer_zipcode => [
    [0] "não pode ficar em branco"
  ],
  :customer_state => [
    [0] "não pode ficar em branco"
  ],
  :customer_address => [
    [0] "não pode ficar em branco"
  ],
  :customer_neighborhood => [
    [0] "não pode ficar em branco"
  ],
  :customer_city_id => [
    [0] "não pode ficar em branco"
  ]
}
Requisição:
$bank_billet = BoletoSimples\BankBillet::create(['amount' => 9.1]);
if($bank_billet->isPersisted()) {
  echo "Sucesso :)\n";
  print_r($bank_billet->attributes());
} else {
  echo "Erro :(\n";
  print_r($bank_billet->response_errors);
}
Resposta:
Erro :(
Array
(
    [expire_at] => Array
        (
            [0] => não pode ficar em branco
            [1] => não é uma data válida
        )

    [customer_person_name] => Array
        (
            [0] => não pode ficar em branco
        )

    [customer_cnpj_cpf] => Array
        (
            [0] => não pode ficar em branco
        )

    [description] => Array
        (
            [0] => não pode ficar em branco
        )

    [customer_zipcode] => Array
        (
            [0] => não pode ficar em branco
        )
    [customer_state] => Array
        (
            [0] => não pode ficar em branco
        )

    [customer_address] => Array
        (
            [0] => não pode ficar em branco
        )

    [customer_neighborhood] => Array
        (
            [0] => não pode ficar em branco
        )

    [customer_city_id] => Array
        (
            [0] => não pode ficar em branco
        )

)

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet":{"amount":12.34, "expire_at": "2014-11-15", "description": "Prestação de Serviço", "customer_person_name": "Nome do Cliente", "customer_cnpj_cpf": "125.812.717-28", "customer_zipcode": "12312123", "customer_address": "Rua quinhentos", "customer_city_name": "Rio de Janeiro", "customer_state": "RJ", "customer_neighborhood": "bairro"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/bank_billets'
Resposta:
HTTP/1.1 201 Created
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 201 Created
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billets/1
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "expire_at":"2014-11-15",
  "paid_at":null,
  "description":"Prestação de Serviço",
  "status":"generating",
  "shorten_url":null,
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":0.0,
  "amount":12.34
}
Requisição:
@bank_billet = BoletoSimples::BankBillet.create({
  amount: 9.01,
  description: 'Despesas do contrato 0012',
  expire_at: '2014-01-01',
  customer_address: 'Rua quinhentos',
  customer_address_complement: 'Sala 4',
  customer_address_number: '111',
  customer_city_name: 'Rio de Janeiro',
  customer_cnpj_cpf: '012.345.678-90',
  customer_email: 'cliente@example.com',
  customer_neighborhood: 'Sao Francisco',
  customer_person_name: 'Joao da Silva',
  customer_person_type: 'individual',
  customer_phone_number: '2112123434',
  customer_state: 'RJ',
  customer_zipcode: '12312123'
})
if @bank_billet.persisted?
  puts "Sucesso :)"
  puts @bank_billet.attributes
else
  puts "Erro :("
  puts @bank_billet.response_errors
end
Resposta:
Sucesso :)
{
                         "amount" => 9.01,
                    "description" => "Despesas do contrato 0012",
                      "expire_at" => "2014-01-01",
               "customer_address" => "Rua quinhentos",
    "customer_address_complement" => "Sala 4",
        "customer_address_number" => "111",
             "customer_city_name" => "Rio de Janeiro",
              "customer_cnpj_cpf" => "012.345.678-90",
                 "customer_email" => "cliente@example.com",
          "customer_neighborhood" => "Sao Francisco",
           "customer_person_name" => "Joao da Silva",
           "customer_person_type" => "individual",
          "customer_phone_number" => "2112123434",
                 "customer_state" => "RJ",
               "customer_zipcode" => "12312123",
                             "id" => 854,
                        "paid_at" => nil,
                         "status" => "generating",
                    "shorten_url" => nil,
               "notification_url" => nil,
         "send_email_on_creation" => nil,
                "created_via_api" => true,
                    "paid_amount" => 0.0
}
Requisição:
$bank_billet = BoletoSimples\BankBillet::create(array (
  'amount' => 9.01,
  'description' => 'Despesas do contrato 0012',
  'expire_at' => '2014-01-01',
  'customer_address' => 'Rua quinhentos',
  'customer_address_complement' => 'Sala 4',
  'customer_address_number' => '111',
  'customer_city_name' => 'Rio de Janeiro',
  'customer_cnpj_cpf' => '012.345.678-90',
  'customer_email' => 'cliente@example.com',
  'customer_neighborhood' => 'Sao Francisco',
  'customer_person_name' => 'Joao da Silva',
  'customer_person_type' => 'individual',
  'customer_phone_number' => '2112123434',
  'customer_state' => 'RJ',
  'customer_zipcode' => '12312123'
));
if($bank_billet->isPersisted()) {
  echo "Sucesso :)\n";
  print_r($bank_billet->attributes());
} else {
  echo "Erro :(\n";
  print_r($bank_billet->response_errors);
}
Resposta:
Sucesso :)
Array
(
    [id] => 857
    [expire_at] => 2014-01-01
    [paid_at] =>
    [description] => Despesas do contrato 0012
    [status] => generating
    [shorten_url] =>
    [customer_person_type] => individual
    [customer_person_name] => Joao da Silva
    [customer_cnpj_cpf] => 012.345.678-90
    [customer_address] => Rua quinhentos
    [customer_state] => RJ
    [customer_neighborhood] => Sao Francisco
    [customer_zipcode] => 12312123
    [customer_address_number] => 111
    [customer_address_complement] => Sala 4
    [customer_phone_number] => 2112123434
    [customer_email] => cliente@example.com
    [notification_url] =>
    [send_email_on_creation] =>
    [created_via_api] => 1
    [customer_city_name] => Rio de Janeiro
    [paid_amount] => 0
    [amount] => 9.01
)

Informações do boleto

GET /api/v1/bank_billets/:id

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/1'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "expire_at":"2014-11-15",
  "paid_at":null,
  "description":"Prestação de Serviço",
  "status":"opened",
  "shorten_url":"http://bole.to/xxxxxxxx",
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":0.0,
  "amount":12.34
}

Requisição:
@bank_billet = BoletoSimples::BankBillet.find(854)
puts @bank_billet.attributes
Resposta:
{
                      "expire_at" => "2014-01-01",
                        "paid_at" => nil,
                    "description" => "Despesas do contrato 0012",
                         "status" => "opened",
                    "shorten_url" => "http://bole.to/xxxxxxxx",
           "customer_person_type" => "individual",
           "customer_person_name" => "Joao da Silva",
              "customer_cnpj_cpf" => "012.345.678-90",
               "customer_address" => "Rua quinhentos",
                 "customer_state" => "RJ",
          "customer_neighborhood" => "Sao Francisco",
               "customer_zipcode" => "12312123",
        "customer_address_number" => "111",
    "customer_address_complement" => "Sala 4",
          "customer_phone_number" => "2112123434",
                 "customer_email" => "cliente@example.com",
               "notification_url" => nil,
         "send_email_on_creation" => nil,
                "created_via_api" => true,
             "customer_city_name" => "Rio de Janeiro",
                    "paid_amount" => 0.0,
                         "amount" => 9.01,
                             "id" => 854
}
Requisição:
$bank_billet = BoletoSimples\BankBillet::find(857);
print_r($bank_billet->attributes());
Resposta:
Array
(
    [id] => 857
    [expire_at] => 2014-01-01
    [paid_at] =>
    [description] => Despesas do contrato 0012
    [status] => opened
    [shorten_url] => http://bole.to/xxxxxxxx
    [customer_person_type] => individual
    [customer_person_name] => Joao da Silva
    [customer_cnpj_cpf] => 012.345.678-90
    [customer_address] => Rua quinhentos
    [customer_state] => RJ
    [customer_neighborhood] => Sao Francisco
    [customer_zipcode] => 12312123
    [customer_address_number] => 111
    [customer_address_complement] => Sala 4
    [customer_phone_number] => 2112123434
    [customer_email] => cliente@example.com
    [notification_url] =>
    [send_email_on_creation] =>
    [created_via_api] => 1
    [customer_city_name] => Rio de Janeiro
    [paid_amount] => 0
    [amount] => 9.01
)

Listar boletos

GET /api/v1/bank_billets

Parâmetro Obr. Tipo Descrição
page
Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET "https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=1&per_page=50"
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Link: <https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=3&per_page=50>; rel="last", <https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=2&per_page=50>; rel="next"
Total: 101
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "expire_at":"2014-11-15",
    "paid_at":null,
    "description":"Prestação de Serviço",
    "status":"opened",
    "shorten_url":"http://bole.to/xxxxxxxx",
    "customer_person_type":"individual",
    "customer_person_name":"Nome do Cliente",
    "customer_cnpj_cpf":"125.812.717-28",
    "customer_address":"Rua quinhentos",
    "customer_state":"RJ",
    "customer_neighborhood":"bairro",
    "customer_zipcode":"12312123",
    "customer_address_number":null,
    "customer_address_complement":null,
    "customer_phone_number":null,
    "customer_email":null,
    "send_email_on_creation":null,
    "created_via_api":true,
    "customer_city_name":"Rio de Janeiro",
    "paid_amount":0.0,
    "amount":12.34
  }
]
Requisição
@bank_billets = BoletoSimples::BankBillet.all(page: 1, per_page: 2)
puts "Boletos Retornados: #{@bank_billets.count}"
puts "Total: #{BoletoSimples.last_request.total}"
puts "Primeira Página: #{BoletoSimples.last_request.links[:first]}"
puts "Página Anterior: #{BoletoSimples.last_request.links[:prev]}"
puts "Próxima Página: #{BoletoSimples.last_request.links[:next]}"
puts "Última Página: #{BoletoSimples.last_request.links[:last]}"
Resposta:
Boletos Retornados: 2
Total: 124
Primeira Página:
Página Anterior:
Próxima Página: https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=2&per_page=2
Última Página: https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=62&per_page=2
Requisição
$bank_billets = BoletoSimples\BankBillet::all(['page' => 1, 'per_page' => 2]);
echo "Boletos Retornados: " . sizeof($bank_billets) . "\n";
echo "Total: " . BoletoSimples::$last_request->total . "\n";
echo "Primeira Página: " . BoletoSimples::$last_request->links['first'] . "\n";
echo "Página Anterior: " . BoletoSimples::$last_request->links['prev'] . "\n";
echo "Próxima Página: " . BoletoSimples::$last_request->links['next'] . "\n";
echo "Última Página: " . BoletoSimples::$last_request->links['last'] . "\n";
Resposta:
Boletos Retornados: 2
Total: 124
Primeira Página:
Página Anterior:
Próxima Página: https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=2&per_page=2
Última Página: https://sandbox.boletosimples.com.br/api/v1/bank_billets?page=62&per_page=2

Cancelar boleto

PUT /api/v1/bank_billets/:id/cancel ou PATCH /api/v1/bank_billets/:id/cancel

Você pode cancelar boletos nos status de Aberto(opened) ou Vencido(overdue)

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT https://sandbox.boletosimples.com.br/api/v1/bank_billets/1/cancel
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "errors": {
    "status": ["cannot transition via cancel"]
  }
}
Requisição
@bank_billet = BoletoSimples::BankBillet.find(863)
puts "Status Anterior: #{@bank_billet.status}"
if @bank_billet.cancel
  puts "Cancelado :)"
else
  puts "Erro :)"
  puts @bank_billet.response_errors
end
puts "Status Final: #{@bank_billet.status}"
Resposta:
Status Anterior: paid
Erro :)
{:status=>["cannot transition via cancel"]}
Status Final: paid
Requisição
$bank_billet = BoletoSimples\BankBillet::find(863);
echo "Status Anterior: " . $bank_billet->status . "\n";
if($bank_billet->cancel()) {
  echo "Cancelado :)\n";
} else {
  echo "Erro :)\n";
  print_r($bank_billet->response_errors);
}
echo "Status Final: " . $bank_billet->status . "\n";
Resposta:
Status Anterior: paid
Erro :)
Array
(
    [status] => Array
        (
            [0] => cannot transition via cancel
        )

)
Status Final: paid

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT https://sandbox.boletosimples.com.br/api/v1/bank_billets/1/cancel
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "expire_at":"2014-11-15",
  "paid_at":null,
  "description":"Prestação de Serviço",
  "status":"opened",
  "shorten_url":"http://bole.to/xxxxxxxx",
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":0.0,
  "amount":12.34
}
Requisição
@bank_billet = BoletoSimples::BankBillet.find(862)
puts "Status Anterior: #{@bank_billet.status}"
if @bank_billet.cancel
  puts "Cancelado :)"
else
  puts "Erro :)"
  puts @bank_billet.response_errors
end
puts "Status Final: #{@bank_billet.status}"
Resposta:
Status Anterior: opened
Cancelado :)
Status Final: canceled
Requisição
$bank_billet = BoletoSimples\BankBillet::find(860);
echo "Status Anterior: " . $bank_billet->status . "\n";
if($bank_billet->cancel()) {
  echo "Cancelado :)\n";
} else {
  echo "Erro :)\n";
  print_r($bank_billet->response_errors);
}
echo "Status Final: " . $bank_billet->status . "\n";
Resposta:
Status Anterior: opened
Cancelado :)
Status Final: canceled

Alterar boleto

PUT /api/v1/bank_billets/:id ou PATCH /api/v1/bank_billets/:id

Você pode alterar boletos no status de Aberto(opened) ou Vencido(overdue)

Você receberá webhooks generating e opened para o boleto alterado.

Em carteiras registradas, a alteração irá entrar na remessa e pode ser cobrada taxa bancária.

Parâmetro Obr. Tipo Descrição
expire_at Sim Date Data de vencimento
tags Não Array Tags associadas ao boleto

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"expire_at":"2017-11-15"}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT https://sandbox.boletosimples.com.br/api/v1/bank_billets/1
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "errors": {
    "status": ["cannot transition via cancel"]
  }
}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"expire_at":"2017-11-15"}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT https://sandbox.boletosimples.com.br/api/v1/bank_billets/1
Resposta:
HTTP/1.1 204 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 204 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "expire_at":"2017-11-15",
  "paid_at":null,
  "description":"Prestação de Serviço",
  "status":"opened",
  "shorten_url":"http://bole.to/xxxxxxxx",
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":0.0,
  "amount":12.34
}

Duplicar boleto

POST /api/v1/bank_billets/:id/duplicate

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id Sim Integer   ID do boleto
expire_at_in_days Não Integer   Nº de dias para vencimento a partir da data de hoje (Default: 7)
cancel Não Boolean   Cancelar o boleto que está sendo duplicado(Default: true)
amount Não String   Valor do novo boleto. Formato: 1.345,56
with_fines Não Boolean   Atualizar o valor do novo boleto com juros e multa (Default: false)

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"expire_at_in_days":"5"}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/1/duplicate'
Resposta:
HTTP/1.1 201 Created
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 201 Created
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billets/2
Content-Type: application/json; charset=utf-8
...

{
  "id":2,
  "expire_at":"2014-11-20",
  "paid_at":null,
  "description":"Prestação de Serviço",
  "status":"generating",
  "shorten_url":null,
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":0.0,
  "amount":12.34
}

Buscar por CPF ou CNPJ

GET /api/v1/bank_billets/cnpj_cpf

Parâmetro Obr. Tipo Descrição
q Sim String CPF ou CNPJ formatado
page
Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/cnpj_cpf?q=125.812.717-28'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "city_name":"Rio de Janeiro",
    "person_name":"Nome do Cliente",
    "address":"Rua quinhentos",
    "address_complement":null,
    "address_number":null,
    "mobile_number":null,
    "cnpj_cpf":"125.812.717-28",
    "email":null,
    "neighborhood":"bairro",
    "person_type":"individual",
    "phone_number":null,
    "zipcode":"20071004",
    "mobile_local_code":null,
    "state":"RJ"
  }
]

Buscar por nosso número

GET /api/v1/bank_billets/our_number

Parâmetro Obr. Tipo Descrição
q Sim String Nosso número
page
Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/our_number?q=00000000441'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "city_name":"Rio de Janeiro",
    "person_name":"Nome do Cliente",
    "address":"Rua quinhentos",
    "address_complement":null,
    "address_number":null,
    "mobile_number":null,
    "cnpj_cpf":"125.812.717-28",
    "email":null,
    "neighborhood":"bairro",
    "person_type":"individual",
    "phone_number":null,
    "zipcode":"20071004",
    "mobile_local_code":null,
    "state":"RJ"
  }
]

Buscar por situação do boleto

GET /api/v1/bank_billets/status

Parâmetro Obr. Tipo Descrição
q Sim String Situação do boleto
page
Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/status?q=opened'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "city_name":"Rio de Janeiro",
    "person_name":"Nome do Cliente",
    "address":"Rua quinhentos",
    "address_complement":null,
    "address_number":null,
    "mobile_number":null,
    "cnpj_cpf":"125.812.717-28",
    "email":null,
    "neighborhood":"bairro",
    "person_type":"individual",
    "phone_number":null,
    "zipcode":"20071004",
    "mobile_local_code":null,
    "state":"RJ"
  }
]

Marcar boleto como pago

PUT /api/v1/bank_billets/:id/pay

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id Sim Integer   ID do boleto
paid_at Sim Date   Data de pagamento
paid_amount Sim String   Valor pago. Formato: 1.345,56
bank_rate Não String   Valor da taxa bancária. Formato: 1.345,56

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet":{"paid_amount":120.34, "paid_at": "2014-11-15"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT 'https://sandbox.boletosimples.com.br/api/v1/bank_billets/1/pay'
Resposta:
HTTP/1.1 204 No Content
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 204 
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billets/1
Content-Type: application/json; charset=utf-8
...

{
  "id":2,
  "expire_at":"2014-11-20",
  "paid_at":"2014-11-15",
  "description":"Prestação de Serviço",
  "status":"paid",
  "shorten_url":null,
  "customer_person_type":"individual",
  "customer_person_name":"Nome do Cliente",
  "customer_cnpj_cpf":"125.812.717-28",
  "customer_address":"Rua quinhentos",
  "customer_state":"RJ",
  "customer_neighborhood":"bairro",
  "customer_zipcode":"12312123",
  "customer_address_number":null,
  "customer_address_complement":null,
  "customer_phone_number":null,
  "customer_email":null,
  "send_email_on_creation":null,
  "created_via_api":true,
  "customer_city_name":"Rio de Janeiro",
  "paid_amount":120.34,
  "amount":12.34
}