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 |
PATCH /api/v1/bank_billet_accounts/:id/set_default | Alterar Carteira de Cobrança padrão |
PUT /api/v1/bank_billet_accounts/:id/set_default | Alterar Carteira de Cobrança padrão |
Modelo de Dados
Parâmetro | Obrigatório | 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 | Sim | String | 255 | Nome do Beneficiário |
beneficiary_cnpj_cpf | Sim | String | 20 | CPF/CNPJ do Beneficiário |
beneficiary_address_street | Sim | String | 255 | Rua do Beneficiário |
beneficiary_address_street_number | Sim | String | 30 | Numero da rua do Beneficiário |
beneficiary_address_complement | Sim | String | 255 | Complemento do endereço do Beneficiário |
beneficiary_address_neighborhood | Sim | String | 255 | Bairro do Beneficiário |
beneficiary_address_city | Sim | String | 50 | Cidade do Beneficiário |
beneficiary_address_state | Sim | String | 2 | Estado do Beneficiário |
beneficiary_address_zipcode | Sim | String | 255 | CEP do Beneficiário |
beneficiary_address | Sim | String | Endereço completo do Beneficiário *** | |
name | Não | String | Nome da Conta *** | |
status | Não | String | Situação da carteira | |
homologated_at | Não | DateTime | 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 *** | |
custom_name | Não | String | 255 | Nome da Carteira para identificação dentro do Boleto Simples |
kind | Não | String | Tipo de CNAB | |
allow_expiration_on_weekends | Não | Boolean | Permitir vencimento em fim de semana e feriados |
’*’ 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
.
Será gerado um boleto e uma remessa de Homologação para ser enviada ao banco. Após o término, o status passa para validating
.
A partir desse momento o usuário precisa informar o valor do boleto que foi gerado ou enviar o retorno processado pelo banco.
Quando o valor é informado corretamente, ou no retorno processado, o banco diz estar tudo certo, 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 (passa para o status
= active
), ela recebe o valor default
= true
kind
cnab400 | CNAB 400 |
cnab240 | CNAB 240 |
Criar carteira
POST /api/v1/bank_billet_accounts
Exemplo de requisição inválida
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"bank_billet_account":{}}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X POST 'https://api-sandbox.kobana.com.br/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"]}}
@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 endResposta:
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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -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", "beneficiary_address_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004"}}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X POST 'https://api-sandbox.kobana.com.br/v1/bank_billet_accounts'Resposta:
HTTP/1.1 201 Created Server: Cowboy Connection: keep-alive Strict-Transport-Security: max-age=2592000 Location: https://api-sandbox.kobana.com.br/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_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004", "beneficiary_address": "Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name":"Bancoob/Sicoob 02 - CC 00003666-8", "status":"pending", "custom_name":"Minha Carteira", "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" } }
@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', beneficiary_address_street: 'Av. Presidente Vargas', beneficiary_address_street_number: '633', beneficiary_address_complement: 'sala 1716', beneficiary_address_city: 'Rio de Janeiro', beneficiary_address_neighborhood: 'Centro', beneficiary_address_state: 'RJ', beneficiary_address_zipcode: '20071-004' beneficiary_address: 'Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004' }) if @bank_billet_account.persisted? puts "Sucesso :)" ap @bank_billet_account.attributes else puts "Erro :(" ap @bank_billet_account.response_errors endResposta:
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_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004", "beneficiary_address" => "Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name" => "Bancoob/Sicoob 02 - CC 00003666-8", "status" => "pending", "custom_name" => nil, "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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X GET 'https://api-sandbox.kobana.com.br/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_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004", "beneficiary_address":"Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name":"Bancoob/Sicoob 02 - CC 00003666-8", "status":"pending", "custom_name":"Minha Carteira", "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" } }
@bank_billet_account = BoletoSimples::BankBilletAccount.find(4) ap @bank_billet_account.attributesResposta:
{ "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_street" => "Av. Presidente Vargas", "beneficiary_address_street_number" => "633", "beneficiary_address_complement" => "sala 1716", "beneficiary_address_city" => "Rio de Janeiro", "beneficiary_address_neighborhood" => "Centro", "beneficiary_address_state" => "RJ", "beneficiary_address_zipcode" => "20071-004", "beneficiary_address" => "Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name" => "Bancoob/Sicoob 02 - CC 00003666-8", "status" => "pending", "custom_name" => "Minha Carteira", "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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"bank_billet_account":{"agency_number":""}}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PATCH 'https://api-sandbox.kobana.com.br/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"]}}
@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 endResposta:
Erro :( { :agency_number => [ [0] "não pode ficar em branco" ] }
Exemplo de requisição válida
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"bank_billet_account":{"agency_number":"4567"}}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PUT 'https://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/v1/bank_billet_accounts/3 ...
@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 endResposta:
Sucesso :) Nova agência: 4842
Listar carteiras
GET /api/v1/bank_billet_accounts
Parâmetro | Obrigatório | Tipo | Descrição |
---|---|---|---|
page | Não | Number | Número da Página |
per_page | Não | Number | Quantidade de registros por página (Máximo de 50) |
Exemplo
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X GET "https://api-sandbox.kobana.com.br/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_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004", "beneficiary_address":"Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name":"Bancoob/Sicoob 02 - CC 00003666-8", "status":"pending", "custom_name":"Minha Carteira", "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" } } ]
@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://api-sandbox.kobana.com.br/v1/bank_billet_accounts?page=2&per_page=2 Última Página: https://api-sandbox.kobana.com.br/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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X GET 'https://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/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_street": "Av. Presidente Vargas", "beneficiary_address_street_number": "633", "beneficiary_address_complement": "sala 1716", "beneficiary_address_city": "Rio de Janeiro", "beneficiary_address_neighborhood": "Centro", "beneficiary_address_state": "RJ", "beneficiary_address_zipcode": "20071-004", "beneficiary_address":"Av. Presidente Vargas, 633, sala 1716 - Centro, Rio de Janeiro - RJ, 20071-004", "name":"Bancoob/Sicoob 02 - CC 00003666-8", "status":"homologating", "custom_name":"Minha Carteira", "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 | Obrigatório | 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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"homologation_amount":""}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PATCH 'https://api-sandbox.kobana.com.br/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
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"homologation_amount":"1,67"}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PUT 'https://api-sandbox.kobana.com.br/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://api-sandbox.kobana.com.br/v1/bank_billet_accounts/1 ...
Alterar Carteira de Cobrança padrão
PATCH /api/v1/bank_billet_accounts/:id/set_default
ou PUT /api/v1/bank_billet_accounts/:id/set_default
Modelo de Dados
Parâmetro | Obrigatório | Tipo | Tamanho | Descrição |
---|---|---|---|---|
id | Sim | Integer | ID da Carteira de Cobrança | |
default | Sim | Boolean | Define a Carteira padrão(Default: true) ou deixar de ser padrão(Default: false) |
Exemplo de requisição inválida
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"default":""}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PATCH 'https://api-sandbox.kobana.com.br/v1/bank_billet_accounts/1/set_default'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":{"default":["não pode ficar em branco"]}}
Exemplo de requisição válida
curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -d '{"default":"true"}' \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X PUT 'https://api-sandbox.kobana.com.br/v1/bank_billet_accounts/1/set_default'Resposta:
HTTP/1.1 204 No Content Date: Fri, 17 Oct 2014 19:30:06 GMT Status: 204 No Content Location: https://api-sandbox.kobana.com.br/v1/bank_billet_accounts/1 ...