Class: StarkInfra::CreditNote

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

Overview

# CreditNote object

CreditNotes are used to generate CCB contracts between you and your customers. When you initialize a CreditNote, the entity will not be automatically created in the Stark Infra API. The ‘create’ function sends the objects to the Stark Infra API and returns the list of created objects.

## Parameters (required):

  • template_id [string]: ID of the contract template on which the credit note will be based. ex: template_id=‘0123456789101112’

  • name [string]: credit receiver’s full name. ex: name=‘Edward Stark’

  • tax_id [string]: credit receiver’s tax ID (CPF or CNPJ). ex: ‘20.018.183/0001-80’

  • nominal_amount [integer]: amount in cents transferred to the credit receiver, before deductions. ex: nominal_amount=11234 (= R$ 112.34)

  • scheduled [DateTime, Date or string, default now]: date of transfer execution. ex: scheduled=DateTime.new(2020, 3, 10, 10, 30, 0, 0)

  • invoices [list of CreditNote::Invoice objects]: list of Invoice objects to be created and sent to the credit receiver. ex: invoices=[CreditNote::Invoice.new(), CreditNote::Invoice.new()]

  • payment [CreditNote::Transfer object]: payment entity to be created and sent to the credit receiver. ex: payment=CreditNote::Transfer.new()

  • signers [list of CreditNote::Signer objects]: signer’s name, contact and delivery method for the signature request. ex: signers=[CreditNote::Signer.new(), CreditNote::Signer.new()]

  • external_id [string]: a string that must be unique among all your CreditNotes, used to avoid resource duplication. ex: ‘my-internal-id-123456’

  • street_line_1 [string]: credit receiver main address. ex: ‘Av. Paulista, 200’

  • street_line_2 [string]: credit receiver address complement. ex: ‘Apto. 123’

  • district [string]: credit receiver address district / neighbourhood. ex: ‘Bela Vista’

  • city [string]: credit receiver address city. ex: ‘Rio de Janeiro’

  • state_code [string]: credit receiver address state. ex: ‘GO’

  • zip_code [string]: credit receiver address zip code. ex: ‘01311-200’

## Parameters (conditionally required):

  • payment_type [string]: payment type, inferred from the payment parameter if it is not a hash. ex: ‘transfer’

Parameters (optional):

  • rebate_amount [integer, default nil]: credit analysis fee deducted from lent amount. ex: rebate_amount=11234 (= R$ 112.34)

  • tags [list of strings, default nil]: list of strings for reference when searching for CreditNotes. ex: tags=[‘employees’, ‘monthly’]

Attributes (return-only):

  • id [string]: unique id returned when the CreditNote is created. ex: ‘5656565656565656’

  • amount [integer]: CreditNote value in cents. ex: 1234 (= R$ 12.34)

  • expiration [integer]: time interval in seconds between due date and expiration date. ex: 123456789

  • document_id [string]: ID of the signed document to execute this CreditNote. ex: ‘4545454545454545’

  • status [string]: current status of the CreditNote. ex: ‘canceled’, ‘created’, ‘expired’, ‘failed’, ‘processing’, ‘signed’, ‘success’

  • transaction_ids [list of strings]: ledger transaction ids linked to this CreditNote. ex: [‘19827356981273’]

  • workspace_id [string]: ID of the Workspace that generated this CreditNote. ex: ‘4545454545454545’

  • tax_amount [integer]: tax amount included in the CreditNote. ex: 100

  • interest [float]: yearly effective interest rate of the credit note, in percentage. ex: 12.5

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

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

Defined Under Namespace

Classes: Invoice, Log, Signer, Transfer

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Utils::SubResource

#inspect, #to_s

Constructor Details

#initialize(template_id:, name:, tax_id:, nominal_amount:, scheduled:, invoices:, payment:, signers:, external_id:, street_line_1:, street_line_2:, district:, city:, state_code:, zip_code:, payment_type: nil, rebate_amount: nil, tags: nil, id: nil, amount: nil, expiration: nil, document_id: nil, status: nil, transaction_ids: nil, workspace_id: nil, tax_amount: nil, interest: nil, created: nil, updated: nil) ⇒ CreditNote

Returns a new instance of CreditNote.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/creditnote/creditnote.rb', line 57

def initialize(
  template_id:, name:, tax_id:, nominal_amount:, scheduled:, invoices:, payment:,
  signers:, external_id:, street_line_1:, street_line_2:, district:, city:, state_code:, zip_code:,
  payment_type: nil, rebate_amount: nil, tags: nil, id: nil, amount: nil, expiration: nil,
  document_id: nil, status: nil, transaction_ids: nil, workspace_id: nil, tax_amount: nil, interest: nil,
  created: nil, updated: nil
)
  super(id)
  @template_id = template_id
  @name = name
  @tax_id = tax_id
  @nominal_amount = nominal_amount
  @scheduled = scheduled
  @invoices = CreditNote::Invoice.parse_invoices(invoices)
  @signers = CreditNote::Signer.parse_signers(signers)
  @external_id = external_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
  @rebate_amount = rebate_amount
  @tags = tags
  @amount = amount
  @expiration = expiration
  @document_id = document_id
  @status = status
  @transaction_ids = transaction_ids
  @workspace_id = workspace_id
  @tax_amount = tax_amount
  @interest = interest
  @created = StarkInfra::Utils::Checks.check_datetime(created)
  @updated = StarkInfra::Utils::Checks.check_datetime(updated)

  payment_info = CreditNote.parse_payment(payment, payment_type)
  @payment = payment_info['payment']
  @payment_type = payment_info['payment_type']
end

Instance Attribute Details

#amount ⇒ Object (readonly)

Returns the value of attribute amount.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def amount
  @amount
end

#city ⇒ Object (readonly)

Returns the value of attribute city.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def city
  @city
end

#created ⇒ Object (readonly)

Returns the value of attribute created.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def created
  @created
end

#district ⇒ Object (readonly)

Returns the value of attribute district.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def district
  @district
end

#document_id ⇒ Object (readonly)

Returns the value of attribute document_id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def document_id
  @document_id
end

#expiration ⇒ Object (readonly)

Returns the value of attribute expiration.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def expiration
  @expiration
end

#external_id ⇒ Object (readonly)

Returns the value of attribute external_id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def external_id
  @external_id
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def id
  @id
end

#interest ⇒ Object (readonly)

Returns the value of attribute interest.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def interest
  @interest
end

#invoices ⇒ Object (readonly)

Returns the value of attribute invoices.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def invoices
  @invoices
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def name
  @name
end

#nominal_amount ⇒ Object (readonly)

Returns the value of attribute nominal_amount.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def nominal_amount
  @nominal_amount
end

#payment ⇒ Object (readonly)

Returns the value of attribute payment.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def payment
  @payment
end

#payment_type ⇒ Object (readonly)

Returns the value of attribute payment_type.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def payment_type
  @payment_type
end

#rebate_amount ⇒ Object (readonly)

Returns the value of attribute rebate_amount.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def rebate_amount
  @rebate_amount
end

#scheduled ⇒ Object (readonly)

Returns the value of attribute scheduled.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def scheduled
  @scheduled
end

#signers ⇒ Object (readonly)

Returns the value of attribute signers.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def signers
  @signers
end

#state_code ⇒ Object (readonly)

Returns the value of attribute state_code.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def state_code
  @state_code
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def status
  @status
end

#street_line_1 ⇒ Object (readonly)

Returns the value of attribute street_line_1.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def street_line_1
  @street_line_1
end

#street_line_2 ⇒ Object (readonly)

Returns the value of attribute street_line_2.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def street_line_2
  @street_line_2
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def tags
  @tags
end

#tax_amount ⇒ Object (readonly)

Returns the value of attribute tax_amount.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def tax_amount
  @tax_amount
end

#tax_id ⇒ Object (readonly)

Returns the value of attribute tax_id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def tax_id
  @tax_id
end

#template_id ⇒ Object (readonly)

Returns the value of attribute template_id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def template_id
  @template_id
end

#transaction_ids ⇒ Object (readonly)

Returns the value of attribute transaction_ids.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def transaction_ids
  @transaction_ids
end

#updated ⇒ Object (readonly)

Returns the value of attribute updated.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def updated
  @updated
end

#workspace_id ⇒ Object (readonly)

Returns the value of attribute workspace_id.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def workspace_id
  @workspace_id
end

#zip_code ⇒ Object (readonly)

Returns the value of attribute zip_code.



53
54
55
 
# File 'lib/creditnote/creditnote.rb', line 53

def zip_code
  @zip_code
end

Class Method Details

.cancel(id, user: nil) ⇒ Object

# Cancel a specific CreditNote

Cancel a single CreditNote object previously created in the Stark Infra API by passing its id

## Parameters (required):

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

## Parameters (optional):

  • user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call

## Return:

  • canceled CreditNote object with updated attributes



205
206
207
 
# File 'lib/creditnote/creditnote.rb', line 205

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

.create(notes, user: nil) ⇒ Object

# Create CreditNotes

Send a list of CreditNote objects for creation in the Stark Infra API

## Parameters (required):

  • notes [list of CreditNote objects]: list of CreditNote objects to be created in the API

## Parameters (optional):

  • user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call

## Return:

  • list of CreditNote objects with updated attributes



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

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

.get(id, user: nil) ⇒ Object

# Retrieve a specific CreditNote

Receive a single CreditNote object previously created in the Stark Infra API by passing its id

## Parameters (required):

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

## Parameters (optional):

  • user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call

## Return:

  • CreditNote object with updated attributes



125
126
127
 
# File 'lib/creditnote/creditnote.rb', line 125

def self.get(id, user: nil)
  StarkInfra::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 CreditNotes

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

## Parameters (optional):

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

  • limit [integer, default 100]: maximum number of objects to be retrieved. Max = 100. ex: 35

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

  • before [Date 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, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call

## Return:

  • list of CreditNote objects with updated attributes

  • cursor to retrieve the next page of CreditNote objects



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

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

.parse_payment(payment, payment_type) ⇒ Object 



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/creditnote/creditnote.rb', line 209

def self.parse_payment(payment, payment_type)
  resource_map = { 'transfer' => Transfer.resource[:resource_maker] }
  if payment.is_a?(Hash)
    begin
      parsed_payment = StarkInfra::Utils::API.from_api_json(resource_map[payment_type], payment)
      return { 'payment' => parsed_payment, 'payment_type' => payment_type }
    rescue StandardError
      return { 'payment' => payment, 'payment_type' => payment_type }
    end
  end

  return { 'payment' => payment, 'payment_type' => payment_type} if payment_type
  if payment.class == StarkInfra::Transfer
    return { 'payment' => payment, 'payment_type' => 'transfer'}
  end
  raise 'payment must be either ' + 'a dictionary, ' \
        'a CreditNote.Transfer, but not a ' + payment.class.to_s
end

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

# Retrieve CreditNotes

Receive a generator of CreditNote objects previously created in the Stark Infra API

## Parameters (optional):

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

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

  • before [Date 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: ‘success’ or ‘failed’

  • 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, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call

## Return:

  • generator of CreditNote objects with updated attributes



144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/creditnote/creditnote.rb', line 144

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

.resource ⇒ Object 



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/creditnote/creditnote.rb', line 228

def self.resource
  {
    resource_name: 'CreditNote',
    resource_maker: proc { |json|
      CreditNote.new(
        id: json['id'],
        template_id: json['template_id'],
        name: json['name'],
        tax_id: json['tax_id'],
        nominal_amount: json['nominal_amount'],
        scheduled: json['scheduled'],
        invoices: json['invoices'],
        payment: json['payment'],
        signers: json['signers'],
        external_id: json['external_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'],
        payment_type: json['payment_type'],
        rebate_amount: json['rebate_amount'],
        tags: json['tags'],
        amount: json['amount'],
        expiration: json['expiration'],
        document_id: json['document_id'],
        status: json['status'],
        transaction_ids: json['transaction_ids'],
        workspace_id: json['workspace_id'],
        tax_amount: json['tax_amount'],
        interest: json['interest'],
        created: json['created'],
        updated: json['updated']
      )
    }
  }
end