Class: StarkBank::Invoice

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

Overview

# Invoice object

When you initialize an Invoice, 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. To create scheduled Invoices, which will display the discount, interest, etc. on the final users banking interface, use dates instead of datetimes on the “due” and “discounts” fields.

## Parameters (required):

  • amount [integer]: Invoice value in cents. Minimum = 0 (any value will be accepted). ex: 1234 (= R$ 12.34)

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

  • name [string]: payer name. ex: ‘Iron Bank S.A.’

## Parameters (optional):

  • due [DateTime or string, default now + 2 days]: Invoice due date in UTC ISO format. ex: ‘2020-10-28T17:59:26.249976+00:00’

  • expiration [integer, default 5097600 (59 days)]: time interval in seconds between due date and expiration date. ex 123456789

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

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

  • discounts [list of hashes, default nil]: list of hashes with ‘percentage’:float and ‘due’:DateTime or string pairs

  • descriptions [list of hashes, default nil]: list of hashes with ‘key’:string and ‘value’:string pairs

  • tags [list of strings, default nil]: list of strings for tagging

## Attributes (return-only):

  • pdf [string, default nil]: public Invoice PDF URL. ex: ‘invoice.starkbank.com/pdf/d454fa4e524441c1b0c1a729457ed9d8’

  • link [string, default nil]: public Invoice webpage URL. ex: ‘my-workspace.sandbox.starkbank.com/invoicelink/d454fa4e524441c1b0c1a729457ed9d8’

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

  • nominal_amount [integer, default nil]: Invoice emission value in cents (will change if invoice is updated, but not if it’s paid). ex: 400000

  • fine_amount [integer, default nil]: Invoice fine value calculated over nominal_amount. ex: 20000

  • interest_amount [integer, default nil]: Invoice interest value calculated over nominal_amount. ex: 10000

  • discount_amount [integer, default nil]: Invoice discount value calculated over nominal_amount. ex: 3000

  • brcode [string, default nil]: BR Code for the Invoice payment. ex: ‘00020101021226800014br.gov.bcb.pix2558invoice.starkbank.com/f5333103-3279-4db2-8389-5efe335ba93d5204000053039865802BR5913Arya Stark6009Sao Paulo6220051656565656565656566304A9A0’

  • fee [integer, default nil]: fee charged by the Invoice. ex: 65 (= R$ 0.65)

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

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

  • updated [DateTime, default nil]: latest update datetime for the Invoice. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)

Defined Under Namespace

Classes: Log, Payment

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Utils::SubResource

#inspect, #to_s

Constructor Details

#initialize(amount:, tax_id:, name:, due: nil, expiration: nil, fine: nil, interest: nil, discounts: nil, tags: nil, pdf: nil, link: nil, descriptions: nil, nominal_amount: nil, fine_amount: nil, interest_amount: nil, discount_amount: nil, id: nil, brcode: nil, fee: nil, status: nil, transaction_ids: nil, created: nil, updated: nil) ⇒ Invoice

Returns a new instance of Invoice.



45
46
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
80
 
# File 'lib/invoice/invoice.rb', line 45

def initialize(
  amount:, tax_id:, name:, due: nil, expiration: nil, fine: nil, interest: nil, discounts: nil,
  tags: nil, pdf: nil, link: nil, descriptions: nil, nominal_amount: nil, fine_amount: nil, interest_amount: nil,
  discount_amount: nil, id: nil, brcode: nil, fee: nil, status: nil, transaction_ids: nil, created: nil, updated: nil
)
  super(id)
  @amount = amount
  @due = StarkBank::Utils::Checks.check_date_or_datetime(due)
  @tax_id = tax_id
  @name = name
  @expiration = expiration
  @fine = fine
  @interest = interest
  @tags = tags
  @pdf = pdf
  @link = link
  @descriptions = descriptions
  @nominal_amount = nominal_amount
  @fine_amount = fine_amount
  @interest_amount = interest_amount
  @discount_amount = discount_amount
  @brcode = brcode
  @fee = fee
  @status = status
  @transaction_ids = transaction_ids
  @updated = StarkBank::Utils::Checks.check_datetime(updated)
  @created = StarkBank::Utils::Checks.check_datetime(created)
  if !discounts.nil?
    checked_discounts = []
    discounts.each do |discount|
      discount["due"] = StarkBank::Utils::Checks.check_date_or_datetime(discount["due"])
      checked_discounts.push(discount)
    end
    @discounts = checked_discounts
  end
end

Instance Attribute Details

#amount ⇒ Object (readonly)

Returns the value of attribute amount.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def amount
  @amount
end

#brcode ⇒ Object (readonly)

Returns the value of attribute brcode.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def brcode
  @brcode
end

#created ⇒ Object (readonly)

Returns the value of attribute created.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def created
  @created
end

#descriptions ⇒ Object (readonly)

Returns the value of attribute descriptions.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def descriptions
  @descriptions
end

#discount_amount ⇒ Object (readonly)

Returns the value of attribute discount_amount.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def discount_amount
  @discount_amount
end

#discounts ⇒ Object (readonly)

Returns the value of attribute discounts.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def discounts
  @discounts
end

#due ⇒ Object (readonly)

Returns the value of attribute due.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def due
  @due
end

#expiration ⇒ Object (readonly)

Returns the value of attribute expiration.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def expiration
  @expiration
end

#fee ⇒ Object (readonly)

Returns the value of attribute fee.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def fee
  @fee
end

#fine ⇒ Object (readonly)

Returns the value of attribute fine.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def fine
  @fine
end

#fine_amount ⇒ Object (readonly)

Returns the value of attribute fine_amount.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def fine_amount
  @fine_amount
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def id
  @id
end

#interest ⇒ Object (readonly)

Returns the value of attribute interest.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def interest
  @interest
end

#interest_amount ⇒ Object (readonly)

Returns the value of attribute interest_amount.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def interest_amount
  @interest_amount
end

#link ⇒ Object (readonly)

Returns the value of attribute link.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def link
  @link
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def name
  @name
end

#nominal_amount ⇒ Object (readonly)

Returns the value of attribute nominal_amount.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def nominal_amount
  @nominal_amount
end

#pdf ⇒ Object (readonly)

Returns the value of attribute pdf.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def pdf
  @pdf
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def status
  @status
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def tags
  @tags
end

#tax_id ⇒ Object (readonly)

Returns the value of attribute tax_id.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def tax_id
  @tax_id
end

#transaction_ids ⇒ Object (readonly)

Returns the value of attribute transaction_ids.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def transaction_ids
  @transaction_ids
end

#updated ⇒ Object (readonly)

Returns the value of attribute updated.



44
45
46
 
# File 'lib/invoice/invoice.rb', line 44

def updated
  @updated
end

Class Method Details

.create(invoices, user: nil) ⇒ Object

# Create Invoices

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

## Parameters (required):

  • invoices [list of Invoice objects]: list of Invoice 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 Invoice objects with updated attributes



94
95
96
 
# File 'lib/invoice/invoice.rb', line 94

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

.get(id, user: nil) ⇒ Object

# Retrieve a specific Invoice

Receive a single Invoice 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:

  • Invoice object with updated attributes



110
111
112
 
# File 'lib/invoice/invoice.rb', line 110

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 Invoices

Receive a list of up to 100 Invoice 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 Invoice objects with updated attributes and cursor to retrieve the next page of Invoice objects



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/invoice/invoice.rb', line 193

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

.payment(id, user: nil) ⇒ Object

# Retrieve a specific Invoice payment information

Receive the Invoice::Payment sub-resource associated with a paid Invoice.

## Parameters (required):

  • id [string]: Invoice 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:

  • Invoice::Payment sub-resource



240
241
242
 
# File 'lib/invoice/invoice.rb', line 240

def self.payment(id, user: nil)
  StarkBank::Utils::Rest.get_sub_resource(id: id, user: user, **resource, **StarkBank::Invoice::Payment.resource)
end

.pdf(id, user: nil) ⇒ Object

# Retrieve a specific Invoice pdf file

Receive a single Invoice pdf file generated 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:

  • Invoice pdf file



126
127
128
 
# File 'lib/invoice/invoice.rb', line 126

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

.qrcode(id, user: nil) ⇒ Object

# Retrieve a specific Invoice QR Code file

Receive a single Invoice QR Code png file generated 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:

  • Invoice QR Code png blob



142
143
144
 
# File 'lib/invoice/invoice.rb', line 142

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

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

# Retrieve Invoices

Receive a generator of Invoice 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 Invoice objects with updated attributes



161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/invoice/invoice.rb', line 161

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 



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/invoice/invoice.rb', line 244

def self.resource
  {
    resource_name: 'Invoice',
    resource_maker: proc { |json|
      Invoice.new(
        id: json['id'],
        amount: json['amount'],
        due: json['due'],
        tax_id: json['tax_id'],
        name: json['name'],
        expiration: json['expiration'],
        fine: json['fine'],
        interest: json['interest'],
        discounts: json['discounts'],
        tags: json['tags'],
        pdf: json['pdf'],
        link: json['link'],
        descriptions: json['descriptions'],
        nominal_amount: json['nominal_amount'],
        fine_amount: json['fine_amount'],
        interest_amount: json['interest_amount'],
        discount_amount: json['discount_amount'],
        brcode: json['brcode'],
        fee: json['fee'],
        status: json['status'],
        transaction_ids: json['transaction_ids'],
        updated: json['updated'],
        created: json['created'],
      )
    }
  }
end

.update(id, status: nil, amount: nil, due: nil, expiration: nil, user: nil) ⇒ Object

# Update an Invoice entity

Update an Invoice entity previously created in the Stark Bank API

## Parameters (required):

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

## Parameters (optional):

  • status [string, nil]: You may cancel the invoice by passing ‘canceled’ in the status

  • amount [string, nil]: Nominal amount charged by the invoice. ex: 100 (R$1.00)

  • due [datetime.date or string, default nil]: Invoice due date in UTC ISO format. ex: DateTime.new(2020, 3, 10, 10, 30, 12, 21)

  • expiration [number, default nil]: time interval in seconds between the due date and the expiration date. ex 123456789

## Return:

  • updated Invoice object



224
225
226
 
# File 'lib/invoice/invoice.rb', line 224

def self.update(id, status: nil, amount: nil, due: nil, expiration: nil, user: nil)
  StarkBank::Utils::Rest.patch_id(id: id, status: status, amount: amount, due: due, expiration: expiration, user: user, **resource)
end