Class: StarkBank::Boleto

Inherits:
Utils::Resource show all
Defined in:
lib/boleto/boleto.rb,
lib/boleto/log.rb

Overview

# Boleto object

When you initialize a Boleto, the entity will not be automatically sent to the Stark Bank API. The ‘create’ function sends the objects to the Stark Bank API and returns the list of created objects.

## Parameters (required):

  • amount [integer]: Boleto value in cents. Minimum = 200 (R$2,00). ex: 1234 (= R$ 12.34)

  • name [string]: payer full name. ex: ‘Anthony Edward Stark’

  • tax_id [string]: payer tax ID (CPF or CNPJ) with or without formatting. ex: ‘01234567890’ or ‘20.018.183/0001-80’

  • street_line_1 [string]: payer main address. ex: Av. Paulista, 200

  • street_line_2 [string]: payer address complement. ex: Apto. 123

  • district [string]: payer address district / neighbourhood. ex: Bela Vista

  • city [string]: payer address city. ex: Rio de Janeiro

  • state_code [string]: payer address state. ex: GO

  • zip_code [string]: payer address zip code. ex: 01311-200

## Parameters (optional):

  • due [Date, DateTime, Time or string, default today + 2 days]: Boleto due date in ISO format. ex: ‘2020-04-30’

  • fine [float, default 0.0]: Boleto fine for overdue payment in %. ex: 2.5

  • interest [float, default 0.0]: Boleto monthly interest for overdue payment in %. ex: 5.2

  • overdue_limit [integer, default 59]: limit in days for payment after due date. ex: 7 (max: 59)

  • receiver_name [string]: receiver (Sacador Avalista) full name. ex: ‘Anthony Edward Stark’

  • receiver_tax_id [string]: receiver (Sacador Avalista) tax ID (CPF or CNPJ) with or without formatting. ex: ‘01234567890’ or ‘20.018.183/0001-80’

  • descriptions [list of dictionaries, default nil]: list of dictionaries with ‘text’:string and (optional) ‘amount’:int pairs

  • discounts [list of dictionaries, default nil]: list of dictionaries with ‘percentage’:float and ‘date’:Date or string pairs

  • tags [list of strings]: list of strings for tagging

## Attributes (return-only):

  • id [string, default nil]: unique id returned when Boleto is created. ex: ‘5656565656565656’

  • fee [integer, default nil]: fee charged when Boleto is paid. ex: 200 (= R$ 2.00)

  • line [string, default nil]: generated Boleto line for payment. ex: ‘34191.09008 63571.277308 71444.640008 5 81960000000062’

  • bar_code [string, default nil]: generated Boleto bar-code for payment. ex: ‘34195819600000000621090063571277307144464000’

  • transaction_ids [list of strings, default nil]: ledger transaction ids linked to this boleto. ex: [‘19827356981273’]

  • status [string, default nil]: current Boleto status. ex: ‘registered’ or ‘paid’

  • created [DateTime, default nil]: creation datetime for the Boleto. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)

  • our_number [string, default nil]: Reference number registered at the settlement bank. ex:‘10131474’

Defined Under Namespace

Classes: Log

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Utils::SubResource

#inspect, #to_s

Constructor Details

#initialize(amount:, name:, tax_id:, street_line_1:, street_line_2:, district:, city:, state_code:, zip_code:, due: nil, fine: nil, interest: nil, overdue_limit: nil, receiver_name: nil, receiver_tax_id: nil, tags: nil, descriptions: nil, discounts: nil, id: nil, fee: nil, line: nil, bar_code: nil, status: nil, transaction_ids: nil, created: nil, our_number: nil) ⇒ Boleto

Returns a new instance of Boleto.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/boleto/boleto.rb', line 47

def initialize(
  amount:, name:, tax_id:, street_line_1:, street_line_2:, district:, city:, state_code:, zip_code:,
  due: nil, fine: nil, interest: nil, overdue_limit: nil, receiver_name: nil, receiver_tax_id: nil,
  tags: nil, descriptions: nil, discounts: nil, id: nil, fee: nil, line: nil, bar_code: nil,
  status: nil, transaction_ids: nil, created: nil, our_number: nil
)
  super(id)
  @amount = amount
  @name = name
  @tax_id = tax_id
  @street_line_1 = street_line_1
  @street_line_2 = street_line_2
  @district = district
  @city = city
  @state_code = state_code
  @zip_code = zip_code
  @due = StarkBank::Utils::Checks.check_date(due)
  @fine = fine
  @interest = interest
  @overdue_limit = overdue_limit
  @receiver_name = receiver_name
  @receiver_tax_id = receiver_tax_id
  @tags = tags
  @descriptions = descriptions
  @discounts = discounts
  @fee = fee
  @line = line
  @bar_code = bar_code
  @status = status
  @transaction_ids = transaction_ids
  @created = StarkBank::Utils::Checks.check_datetime(created)
  @our_number = our_number
end

Instance Attribute Details

#amount ⇒ Object (readonly)

Returns the value of attribute amount.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def amount
  @amount
end

#bar_code ⇒ Object (readonly)

Returns the value of attribute bar_code.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def bar_code
  @bar_code
end

#city ⇒ Object (readonly)

Returns the value of attribute city.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def city
  @city
end

#created ⇒ Object (readonly)

Returns the value of attribute created.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def created
  @created
end

#descriptions ⇒ Object (readonly)

Returns the value of attribute descriptions.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def descriptions
  @descriptions
end

#discounts ⇒ Object (readonly)

Returns the value of attribute discounts.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def discounts
  @discounts
end

#district ⇒ Object (readonly)

Returns the value of attribute district.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def district
  @district
end

#due ⇒ Object (readonly)

Returns the value of attribute due.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def due
  @due
end

#fee ⇒ Object (readonly)

Returns the value of attribute fee.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def fee
  @fee
end

#fine ⇒ Object (readonly)

Returns the value of attribute fine.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def fine
  @fine
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def id
  @id
end

#interest ⇒ Object (readonly)

Returns the value of attribute interest.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def interest
  @interest
end

#line ⇒ Object (readonly)

Returns the value of attribute line.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def line
  @line
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def name
  @name
end

#our_number ⇒ Object (readonly)

Returns the value of attribute our_number.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def our_number
  @our_number
end

#overdue_limit ⇒ Object (readonly)

Returns the value of attribute overdue_limit.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def overdue_limit
  @overdue_limit
end

#receiver_name ⇒ Object (readonly)

Returns the value of attribute receiver_name.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def receiver_name
  @receiver_name
end

#receiver_tax_id ⇒ Object (readonly)

Returns the value of attribute receiver_tax_id.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def receiver_tax_id
  @receiver_tax_id
end

#state_code ⇒ Object (readonly)

Returns the value of attribute state_code.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def state_code
  @state_code
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def status
  @status
end

#street_line_1 ⇒ Object (readonly)

Returns the value of attribute street_line_1.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def street_line_1
  @street_line_1
end

#street_line_2 ⇒ Object (readonly)

Returns the value of attribute street_line_2.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def street_line_2
  @street_line_2
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def tags
  @tags
end

#tax_id ⇒ Object (readonly)

Returns the value of attribute tax_id.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def tax_id
  @tax_id
end

#transaction_ids ⇒ Object (readonly)

Returns the value of attribute transaction_ids.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def transaction_ids
  @transaction_ids
end

#zip_code ⇒ Object (readonly)

Returns the value of attribute zip_code.



46
47
48
 
# File 'lib/boleto/boleto.rb', line 46

def zip_code
  @zip_code
end

Class Method Details

.create(boletos, user: nil) ⇒ Object

# Create Boletos

Send a list of Boleto objects for creation in the Stark Bank API

## Parameters (required):

  • boletos [list of Boleto objects]: list of Boleto objects to be created in the API

## Parameters (optional):

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • list of Boleto objects with updated attributes



93
94
95
 
# File 'lib/boleto/boleto.rb', line 93

def self.create(boletos, user: nil)
  StarkBank::Utils::Rest.post(entities: boletos, user: user, **resource)
end

.delete(id, user: nil) ⇒ Object

# Delete a Boleto entity

Delete a Boleto entity previously created in the Stark Bank API

## Parameters (required):

  • id [string]: Boleto unique id. ex: ‘5656565656565656’

## Parameters (optional):

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • deleted Boleto object



206
207
208
 
# File 'lib/boleto/boleto.rb', line 206

def self.delete(id, user: nil)
  StarkBank::Utils::Rest.delete_id(id: id, user: user, **resource)
end

.get(id, user: nil) ⇒ Object

# Retrieve a specific Boleto

Receive a single Boleto object previously created in the Stark Bank API by passing its id

## Parameters (required):

  • id [string]: object unique id. ex: ‘5656565656565656’

## Parameters (optional):

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • Boleto object with updated attributes



109
110
111
 
# File 'lib/boleto/boleto.rb', line 109

def self.get(id, user: nil)
  StarkBank::Utils::Rest.get_id(id: id, user: user, **resource)
end

.page(cursor: nil, limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil) ⇒ Object

# Retrieve paged Boletos

Receive a list of up to 100 Boleto objects previously created in the Stark Bank API and the cursor to the next page. Use this function instead of query if you want to manually page your requests.

## Parameters (optional):

  • cursor [string, default nil]: cursor returned on the previous page function call

  • limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35

  • after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)

  • before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)

  • status [string, default nil]: filter for status of retrieved objects. ex: ‘paid’ or ‘registered’

  • tags [list of strings, default nil]: tags to filter retrieved objects. ex: [‘tony’, ‘stark’]

  • ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: [‘5656565656565656’, ‘4545454545454545’]

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • list of Boleto objects with updated attributes and cursor to retrieve the next page of Boleto objects



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/boleto/boleto.rb', line 178

def self.page(cursor: nil, limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
  after = StarkBank::Utils::Checks.check_date(after)
  before = StarkBank::Utils::Checks.check_date(before)
  return StarkBank::Utils::Rest.get_page(
    cursor: cursor,
    limit: limit,
    after: after,
    before: before,
    status: status,
    tags: tags,
    ids: ids,
    user: user,
    **resource
  )
end

.pdf(id, layout: nil, hidden_fields: nil, user: nil) ⇒ Object

# Retrieve a specific Boleto pdf file

Receive a single Boleto pdf file generated in the Stark Bank API by passing its id.

## Parameters (required):

  • id [string]: object unique id. ex: ‘5656565656565656’

## Parameters (optional):

  • layout [string]: Layout specification. Available options are ‘default’ and ‘booklet’

  • hidden_fields [list of strings, default nil]: List of string fields to be hidden in Boleto pdf. ex: [‘customerAddress’]

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • Boleto pdf file



127
128
129
 
# File 'lib/boleto/boleto.rb', line 127

def self.pdf(id, layout: nil, hidden_fields: nil, user: nil)
  StarkBank::Utils::Rest.get_content(id: id, layout: layout, hidden_fields: hidden_fields, sub_resource_name: 'pdf', user: user, **resource)
end

.query(limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil) ⇒ Object

# Retrieve Boletos

Receive a generator of Boleto objects previously created in the Stark Bank API

## Parameters (optional):

  • limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35

  • after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)

  • before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)

  • status [string, default nil]: filter for status of retrieved objects. ex: ‘paid’ or ‘registered’

  • tags [list of strings, default nil]: tags to filter retrieved objects. ex: [‘tony’, ‘stark’]

  • ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: [‘5656565656565656’, ‘4545454545454545’]

  • user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call

## Return:

  • generator of Boleto objects with updated attributes



146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/boleto/boleto.rb', line 146

def self.query(limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
  after = StarkBank::Utils::Checks.check_date(after)
  before = StarkBank::Utils::Checks.check_date(before)
  StarkBank::Utils::Rest.get_stream(
    limit: limit,
    after: after,
    before: before,
    status: status,
    tags: tags,
    ids: ids,
    user: user,
    **resource
  )
end

.resource ⇒ Object 



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/boleto/boleto.rb', line 210

def self.resource
  {
    resource_name: 'Boleto',
    resource_maker: proc { |json|
      Boleto.new(
        amount: json['amount'],
        name: json['name'],
        tax_id: json['tax_id'],
        street_line_1: json['street_line_1'],
        street_line_2: json['street_line_2'],
        district: json['district'],
        city: json['city'],
        state_code: json['state_code'],
        zip_code: json['zip_code'],
        due: json['due'],
        fine: json['fine'],
        interest: json['interest'],
        overdue_limit: json['overdue_limit'],
        receiver_name: json['receiver_name'],
        receiver_tax_id: json['receiver_tax_id'],
        tags: json['tags'],
        descriptions: json['descriptions'],
        discounts: json['discounts'],
        id: json['id'],
        fee: json['fee'],
        line: json['line'],
        bar_code: json['bar_code'],
        status: json['status'],
        transaction_ids: json['transaction_ids'],
        created: json['created'],
        our_number: json['our_number']
      )
    }
  }
end