Class: StarkInfra::CreditNote

Inherits:
StarkCore::Utils::Resource
  • Object
show all
Defined in:
lib/credit_note/credit_note.rb,
lib/credit_note/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: ‘0123456789101112’

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

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

  • scheduled [DateTime, Date or string]: date of transfer execution. ex: 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: [Invoice.new(), Invoice.new()]

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

  • signers [list of CreditSigner objects]: signer’s name, contact and delivery method for the signature request. ex: [CreditSigner.new(), CreditSigner.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’

  • nominal_amount [integer]: CreditNote value in cents. The nominal_amount parameter is required when amount is not sent. ex: 1234 (= R$ 12.34)

  • amount [integer]: amount in cents transferred to the credit receiver, before deductions. The amount parameter is required when nominal_amount is not sent. ex: 1234 (= R$ 12.34)

## Parameters (optional):

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

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

  • expiration [integer, default 604800]: time interval in seconds between scheduled date and expiration date. ex: 123456789

## Attributes (return-only):

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

  • 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

  • nominal_interest [float]: yearly nominal interest rate of the CreditNote, in percentage. ex: 11.5

  • 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: Log

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of CreditNote.



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
96
97
98
99
100
101
 
# File 'lib/credit_note/credit_note.rb', line 62

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



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def amount
  @amount
end

#city ⇒ Object (readonly)

Returns the value of attribute city.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def city
  @city
end

#created ⇒ Object (readonly)

Returns the value of attribute created.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def created
  @created
end

#district ⇒ Object (readonly)

Returns the value of attribute district.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def district
  @district
end

#document_id ⇒ Object (readonly)

Returns the value of attribute document_id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def document_id
  @document_id
end

#expiration ⇒ Object (readonly)

Returns the value of attribute expiration.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def expiration
  @expiration
end

#external_id ⇒ Object (readonly)

Returns the value of attribute external_id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def external_id
  @external_id
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def id
  @id
end

#interest ⇒ Object (readonly)

Returns the value of attribute interest.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def interest
  @interest
end

#invoices ⇒ Object (readonly)

Returns the value of attribute invoices.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def invoices
  @invoices
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def name
  @name
end

#nominal_amount ⇒ Object (readonly)

Returns the value of attribute nominal_amount.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def nominal_amount
  @nominal_amount
end

#nominal_interest ⇒ Object (readonly)

Returns the value of attribute nominal_interest.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def nominal_interest
  @nominal_interest
end

#payment ⇒ Object (readonly)

Returns the value of attribute payment.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def payment
  @payment
end

#payment_type ⇒ Object (readonly)

Returns the value of attribute payment_type.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def payment_type
  @payment_type
end

#rebate_amount ⇒ Object (readonly)

Returns the value of attribute rebate_amount.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def rebate_amount
  @rebate_amount
end

#scheduled ⇒ Object (readonly)

Returns the value of attribute scheduled.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def scheduled
  @scheduled
end

#signers ⇒ Object (readonly)

Returns the value of attribute signers.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def signers
  @signers
end

#state_code ⇒ Object (readonly)

Returns the value of attribute state_code.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def state_code
  @state_code
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def status
  @status
end

#street_line_1 ⇒ Object (readonly)

Returns the value of attribute street_line_1.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def street_line_1
  @street_line_1
end

#street_line_2 ⇒ Object (readonly)

Returns the value of attribute street_line_2.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def street_line_2
  @street_line_2
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def tags
  @tags
end

#tax_amount ⇒ Object (readonly)

Returns the value of attribute tax_amount.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def tax_amount
  @tax_amount
end

#tax_id ⇒ Object (readonly)

Returns the value of attribute tax_id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def tax_id
  @tax_id
end

#template_id ⇒ Object (readonly)

Returns the value of attribute template_id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def template_id
  @template_id
end

#transaction_ids ⇒ Object (readonly)

Returns the value of attribute transaction_ids.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def transaction_ids
  @transaction_ids
end

#updated ⇒ Object (readonly)

Returns the value of attribute updated.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def updated
  @updated
end

#workspace_id ⇒ Object (readonly)

Returns the value of attribute workspace_id.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def workspace_id
  @workspace_id
end

#zip_code ⇒ Object (readonly)

Returns the value of attribute zip_code.



58
59
60
 
# File 'lib/credit_note/credit_note.rb', line 58

def zip_code
  @zip_code
end

Class Method Details

.cancel(id, user: nil) ⇒ Object

# Cancel a CreditNote entity

Cancel a CreditNote entity previously created in the Stark Infra API

## 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



211
212
213
 
# File 'lib/credit_note/credit_note.rb', line 211

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



115
116
117
 
# File 'lib/credit_note/credit_note.rb', line 115

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



131
132
133
 
# File 'lib/credit_note/credit_note.rb', line 131

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: [“canceled”, “created”, “expired”, “failed”, “processing”, “signed”, “success”]

  • 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



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/credit_note/credit_note.rb', line 183

def self.page(cursor: nil, limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
  after = StarkCore::Utils::Checks.check_date(after)
  before = StarkCore::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 



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/credit_note/credit_note.rb', line 215

def self.parse_payment(payment, payment_type)
  resource_maker = { 'transfer' => Transfer.resource[:resource_maker] }
  if payment.is_a?(Hash)
    begin
      parsed_payment = StarkCore::Utils::API.from_api_json(resource_maker[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: [“canceled”, “created”, “expired”, “failed”, “processing”, “signed”, “success”]

  • 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



150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/credit_note/credit_note.rb', line 150

def self.query(limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
  after = StarkCore::Utils::Checks.check_date(after)
  before = StarkCore::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 



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
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/credit_note/credit_note.rb', line 238

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'],
        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'],
        nominal_amount: json['nominal_amount'],
        amount: json['amount'],
        rebate_amount: json['rebate_amount'],
        tags: json['tags'],
        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'],
        nominal_interest: json['nominal_interest'],
        interest: json['interest'],
        created: json['created'],
        updated: json['updated']
      )
    }
  }
end