Documentação para Desenvolvedores

Carteiras de Cobrança

Para saber mais sobre as carteiras suportadas, acesse a página de Carteiras de Cobrança.
Recurso Descrição
POST /api/v1/bank_billet_accounts Criar carteira
GET /api/v1/bank_billet_accounts/:id Informações do carteira
PATCH /api/v1/bank_billet_accounts/:id Atualizar carteira
PUT /api/v1/bank_billet_accounts/:id Atualizar carteira
GET /api/v1/bank_billet_accounts Listar carteiras
GET /api/v1/bank_billet_accounts/:id/ask Solicitar homologação da Carteira de Cobrança
PATCH /api/v1/bank_billet_accounts/:id/validate Validar Carteira de Cobrança
PUT /api/v1/bank_billet_accounts/:id/validate Validar Carteira de Cobrança

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id N/A Integer   ID da carteira
bank_contract_slug Sim String 50 Slug da Carteira
next_our_number Não String 40 Próximo Nosso Número. Default: 1
agency_number Sim String 20 Agência
agency_digit * String 2 Dígito da Agência
account_number Sim String 20 Conta
account_digit Sim String 2 Dígito da Conta
extra1 * String 15 Campo Extra 1
extra1_digit * String 3 Dígito do Campo Extra 1
extra2 * String 15 Campo Extra 2
extra2_digit * String 3 Dígito do Campo Extra 2
extra3 ** String 30 Código de Remessa
beneficiary_name Não String 255 Nome do Beneficiário
beneficiary_cnpj_cpf Não String 20 CPF/CNPJ do Beneficiário
beneficiary_address Não String 255 Endereço do Beneficiário
name Não String   Nome da Conta ***
status Não String   Situação da carteira
homologated_at Não Date   Data de homologação
next_remittance_number Não String   Próximo Número da Remessa. Default: 1
default Não Boolean   Padrão
configuration Não JSON   Configuração de dados padrões para boleto
bank_contract Não Hash   Dados da Carteira ***

‘*’ Depende da carteira escolhida.

‘**’ Usado na remessa em bancos.

‘***’ Não é recebido na criação e nem na atualização, só é retornado na consulta e listagem.

Dicionário de Dados

status

Quando a carteira acaba de ser cadastrada, ela ganha o status pending.

Nesse momento o usuário deve aceitar os termos e iniciar a homologação.

Ao clicar em “Prosseguir com a Homologação”, o status passa para homologating.

Um boleto bancário é gerado e pago pela equipe do Boleto Simples.

Após a equipe do Boleto Simples efetuar o pagamento do boleto, o status para para validating.

A partir desse momento o usuário precisa informar o valor do boleto que foi pago.

Quando o valor é informado corretamente, o status passa para active.

pending Homologação não iniciada
homologating Em homologação, aguardand pagamento do boleto
validating Boleto pago, aguardando validação
active Ativa e pronta para uso

default

O campo default determina a carteira de cobrança que será usada na criação do boleto quando nenhuma carteira for informada.

No momento que a primeira carteira é homologada (para para o status = active), ela recebe o valor default = true

Criar carteira

POST /api/v1/bank_billet_accounts

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet_account":{}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Content-Type: application/json; charset=utf-8
...

{"errors":{"bank_billet_account":["não pode ficar em branco"]}}
Requisição:
@bank_billet_account = BoletoSimples::BankBilletAccount.create({bank_contract_slug: 'sicoob-02'})
if @bank_billet_account.persisted?
  puts "Sucesso :)"
  ap @bank_billet_account.attributes
else
  puts "Erro :("
  ap @bank_billet_account.response_errors
end
Resposta:
Erro :(
{
     :agency_number => [
        [0] "não pode ficar em branco"
    ],
    :account_number => [
        [0] "não pode ficar em branco"
    ]
}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet_account":{"bank_contract_slug": "sicoob-02", "agency_number": "4327", "agency_digit": "3", "account_number": "3666", "account_digit": "8", "next_our_number": "1", "extra1": "1234567"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts'
Resposta:
HTTP/1.1 201 Created
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/3
Content-Type: application/json; charset=utf-8
...

{
  "id":3,
  "bank_contract_slug":"sicoob-02",
  "next_our_number":"0000001",
  "agency_number":"4327",
  "agency_digit":"3",
  "account_number":"00003666",
  "account_digit":"8",
  "extra1":"1234567",
  "extra1_digit":null,
  "extra2":null,
  "extra2_digit":null,
  "extra3":null,
  "beneficiary_name":"Boleto Simples Cobranças Ltda.",
  "beneficiary_cnpj_cpf":"05.813.794/0001-26",
  "beneficiary_address":"Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
  "name":"Bancoob/Sicoob 02 - CC 00003666-8",
  "status":"pending",
  "bank_contract": {
    "bank":{
      "code":"sicoob",
      "name":"Bancoob/Sicoob",
      "number":"756"
    },
    "slug":"sicoob-02",
    "code":"02",
    "sufix":"02",
    "variation":null,
    "name":"1/02 - Simples Sem Registro"
  }
}
Requisição:
@bank_billet_account = BoletoSimples::BankBilletAccount.create({
  bank_contract_slug: 'sicoob-02',
  next_our_number: '1',
  agency_number: '4327',
  agency_digit: '3',
  account_number: '3666',
  account_digit: '8',
  extra1: '1234567'
})
if @bank_billet_account.persisted?
  puts "Sucesso :)"
  ap @bank_billet_account.attributes
else
  puts "Erro :("
  ap @bank_billet_account.response_errors
end
Resposta:
Sucesso :)
{
      "bank_contract_slug" => "sicoob-02",
         "next_our_number" => "0000001",
           "agency_number" => "4327",
            "agency_digit" => "3",
          "account_number" => "00003666",
           "account_digit" => "8",
                  "extra1" => "1234567",
            "extra1_digit" => nil,
                  "extra2" => nil,
            "extra2_digit" => nil,
                  "extra3" => nil,
        "beneficiary_name" => "Boleto Simples Cobranças Ltda.",
    "beneficiary_cnpj_cpf" => "05.813.794/0001-26",
     "beneficiary_address" => "Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
                    "name" => "Bancoob/Sicoob 02 - CC 00003666-8",
                  "status" => "pending",
           "bank_contract" => {
                                "bank" => {
                                  "code" => "sicoob",
                                  "name" => "Bancoob/Sicoob",
                                  "number" => "756"
                                },
                               "slug" => "sicoob-02",
                               "code" => "02",
                              "sufix" => "02",
                          "variation" => nil,
                               "name" => "1/02 - Simples Sem Registro"
                              },
                      "id" => 3
}

Informações do carteira

GET /api/v1/bank_billet_accounts/: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_billet_accounts/3'
Resposta:
HTTP/1.1 200 OK
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Content-Type: application/json; charset=utf-8
...

{
  "id":3,
  "bank_contract_slug":"sicoob-02",
  "next_our_number":"0000001",
  "agency_number":"4327",
  "agency_digit":"3",
  "account_number":"00003666",
  "account_digit":"8",
  "extra1":"1234567",
  "extra1_digit":null,
  "extra2":null,
  "extra2_digit":null,
  "extra3":null,
  "beneficiary_name":"Boleto Simples Cobranças Ltda.",
  "beneficiary_cnpj_cpf":"05.813.794/0001-26",
  "beneficiary_address":"Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
  "name":"Bancoob/Sicoob 02 - CC 00003666-8",
  "status":"pending",
  "bank_contract": {
    "bank":{
      "code":"sicoob",
      "name":"Bancoob/Sicoob",
      "number":"756"
    },
    "slug":"sicoob-02",
    "code":"02",
    "sufix":"02",
    "variation":null,
    "name":"1/02 - Simples Sem Registro"
  }
}
Requisição:
@bank_billet_account = BoletoSimples::BankBilletAccount.find(4)
ap @bank_billet_account.attributes
Resposta:
{
      "bank_contract_slug" => "sicoob-02",
         "next_our_number" => "0000001",
           "agency_number" => "4327",
            "agency_digit" => "3",
          "account_number" => "00003666",
           "account_digit" => "8",
                  "extra1" => "1234567",
            "extra1_digit" => nil,
                  "extra2" => nil,
            "extra2_digit" => nil,
                  "extra3" => nil,
        "beneficiary_name" => "Boleto Simples Cobranças Ltda.",
    "beneficiary_cnpj_cpf" => "05.813.794/0001-26",
     "beneficiary_address" => "Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
                    "name" => "Bancoob/Sicoob 02 - CC 00003666-8",
                  "status" => "pending",
           "bank_contract" => {
                                "bank" => {
                                  "code" => "sicoob",
                                  "name" => "Bancoob/Sicoob",
                                  "number" => "756"
                                },
                               "slug" => "sicoob-02",
                               "code" => "02",
                              "sufix" => "02",
                          "variation" => nil,
                               "name" => "1/02 - Simples Sem Registro"
                              },
                      "id" => 123
}

Atualizar carteira

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

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet_account":{"agency_number":""}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PATCH 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/1'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Content-Type: application/json; charset=utf-8
...

{"errors":{"agency_number":["não pode ficar em branco"]}}
Requisição:
@bank_billet_account = BoletoSimples::BankBilletAccount.find(3)
puts "Agência: #{@bank_billet_account.agency_number}"
@bank_billet_account.agency_number = ""
if @bank_billet_account.save
  puts "Sucesso :)"
  puts "Nova agência: #{@bank_billet_account.agency_number}"
else
  puts "Erro :("
  puts @bank_billet_account.response_errors
end
Resposta:
Erro :(
{
    :agency_number => [
        [0] "não pode ficar em branco"
    ]
}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"bank_billet_account":{"agency_number":"4567"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/3'
Resposta:
HTTP/1.1 204 No Content
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 204 No Content
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/3
...
Requisição:
@bank_billet_account = BoletoSimples::BankBilletAccount.find(3)
puts "Agência: #{@bank_billet_account.agency_number}"
@bank_billet_account.agency_number = "4842"
if @bank_billet_account.save
  puts "Sucesso :)"
  puts "Nova agência: #{@bank_billet_account.agency_number}"
else
  puts "Erro :("
  ap @bank_billet_account.response_errors
end
Resposta:
Sucesso :)
Nova agência: 4842

Listar carteiras

GET /api/v1/bank_billet_accounts

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_billet_accounts?page=1&per_page=50"
Resposta:
HTTP/1.1 200 OK
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Total: 4
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":3,
    "bank_contract_slug":"sicoob-02",
    "next_our_number":"0000001",
    "agency_number":"4327",
    "agency_digit":"3",
    "account_number":"00003666",
    "account_digit":"8",
    "extra1":"1234567",
    "extra1_digit":null,
    "extra2":null,
    "extra2_digit":null,
    "extra3":null,
    "beneficiary_name":"Boleto Simples Cobranças Ltda.",
    "beneficiary_cnpj_cpf":"05.813.794/0001-26",
    "beneficiary_address":"Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
    "name":"Bancoob/Sicoob 02 - CC 00003666-8",
    "status":"pending",
    "bank_contract": {
      "bank":{
        "code":"sicoob",
        "name":"Bancoob/Sicoob",
        "number":"756"
      },
      "slug":"sicoob-02",
      "code":"02",
      "sufix":"02",
      "variation":null,
      "name":"1/02 - Simples Sem Registro"
    }
  }
]
Requisição:
@bank_billet_accounts = BoletoSimples::BankBilletAccount.all(page: 1, per_page: 2)
puts "Carteiras Retornadas: #{@bank_billet_accounts.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:
Carteiras Retornadas: 3
Total: 3
Primeira Página:
Página Anterior:
Próxima Página: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts?page=2&per_page=2
Última Página: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts?page=2&per_page=2

Solicitar homologação da Carteira de Cobrança

GET /api/v1/bank_billet_accounts/:id/ask

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_billet_accounts/1/ask'
Resposta:
HTTP/1.1 200 OK
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/1
Content-Type: application/json; charset=utf-8
...

{
  "id":3,
  "bank_contract_slug":"sicoob-02",
  "next_our_number":"0000001",
  "agency_number":"4327",
  "agency_digit":"3",
  "account_number":"00003666",
  "account_digit":"8",
  "extra1":"1234567",
  "extra1_digit":null,
  "extra2":null,
  "extra2_digit":null,
  "extra3":null,
  "beneficiary_name":"Boleto Simples Cobranças Ltda.",
  "beneficiary_cnpj_cpf":"05.813.794/0001-26",
  "beneficiary_address":"Av. Presidente Vargas, 633 sala 1716. Rio de Janeiro - RJ",
  "name":"Bancoob/Sicoob 02 - CC 00003666-8",
  "status":"homologating",
  "bank_contract": {
    "bank":{
      "code":"sicoob",
      "name":"Bancoob/Sicoob",
      "number":"756"
    },
    "slug":"sicoob-02",
    "code":"02",
    "sufix":"02",
    "variation":null,
    "name":"1/02 - Simples Sem Registro"
  }
}

Validar Carteira de Cobrança

PATCH /api/v1/bank_billet_accounts/:id/validate ou PUT /api/v1/bank_billet_accounts/:id/validate

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id Sim Integer   ID da Carteira de Cobrança
homologation_amount Sim String   Valor recebido pelo boleto (R$) Ex.: 1,87

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"homologation_amount":""}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PATCH 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/1/validate'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Server: Cowboy
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Content-Type: application/json; charset=utf-8
...

{"errors":{"homologation_amount":["não pode ficar em branco"]}}

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"homologation_amount":"1,67"}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT 'https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/1/validate'
Resposta:
HTTP/1.1 204 No Content
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 204 No Content
Location: https://sandbox.boletosimples.com.br/api/v1/bank_billet_accounts/1
...