Module: MyobAcumatica::Api::Tax

Defined in:
lib/myob_acumatica/api/tax.rb

Overview

Provides methods to interact with the Tax API endpoints.

Class Method Summary collapse

Class Method Details

.delete_by_id(access_token:, id:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Deletes a tax record by its session UUID.

Examples:

Delete a tax by ID

MyobAcumatica::Api::Tax.delete_by_id(
  access_token: access_token,
  id: tax['id'],
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • id (String) —

    Session UUID of the tax record.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil) 


26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/myob_acumatica/api/tax.rb', line 26

def delete_by_id(access_token:, id:,
                 instance_name: INSTANCE_NAME,
                 endpoint_name: ENDPOINT_NAME,
                 endpoint_version: ENDPOINT_VERSION,
                 logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :delete,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Tax/#{id}",
    logger: logger
  )
end

.delete_by_keys(access_token:, keys:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Deletes a tax record by composite keys.

Keys are ordered values of the record’s key fields. For Tax this is typically the TaxID (and if applicable, other key parts defined by the endpoint contract).

Examples:

Delete a tax by keys

MyobAcumatica::Api::Tax.delete_by_keys(
  access_token: access_token,
  keys: [tax['TaxID']['value']],
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • keys (Array<String>) —

    Key values identifying the tax record.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil) 


63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/myob_acumatica/api/tax.rb', line 63

def delete_by_keys(access_token:, keys:,
                   instance_name: INSTANCE_NAME,
                   endpoint_name: ENDPOINT_NAME,
                   endpoint_version: ENDPOINT_VERSION,
                   logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :delete,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Tax/#{keys.join('/')}",
    logger: logger
  )
end

.get_ad_hoc_schema(access_token:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves the ad-hoc schema (custom fields) for the Tax entity.

Examples:

Retrieve ad-hoc schema

MyobAcumatica::Api::Tax.get_ad_hoc_schema(
  access_token: access_token,
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    Ad-hoc schema payload.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/myob_acumatica/api/tax.rb', line 94

def get_ad_hoc_schema(access_token:,
                      instance_name: INSTANCE_NAME,
                      endpoint_name: ENDPOINT_NAME,
                      endpoint_version: ENDPOINT_VERSION,
                      logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Tax/$adHocSchema',
    logger: logger
  )
end

.get_by_id(access_token:, id:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves a tax record by its session UUID.

Examples:

Get tax by ID

MyobAcumatica::Api::Tax.get_by_id(
  access_token: access_token,
  id: tax['id'],
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • id (String) —

    Session UUID of the tax record.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $expand, $filter, $custom).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The tax record.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/myob_acumatica/api/tax.rb', line 129

def get_by_id(access_token:, id:, query_params: {},
              instance_name: INSTANCE_NAME,
              endpoint_name: ENDPOINT_NAME,
              endpoint_version: ENDPOINT_VERSION,
              logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Tax/#{id}",
    query_params: query_params,
    logger: logger
  )
end

.get_by_keys(access_token:, keys:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves a tax record by composite keys.

Examples:

Get tax by keys

MyobAcumatica::Api::Tax.get_by_keys(
  access_token: access_token,
  keys: [tax_id],
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • keys (Array<String>) —

    Key values identifying the tax record.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $expand, $filter, $custom).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The tax record.



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/myob_acumatica/api/tax.rb', line 165

def get_by_keys(access_token:, keys:, query_params: {},
                instance_name: INSTANCE_NAME,
                endpoint_name: ENDPOINT_NAME,
                endpoint_version: ENDPOINT_VERSION,
                logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Tax/#{keys.join('/')}",
    query_params: query_params,
    logger: logger
  )
end

.get_list(access_token:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Array<Hash>

Retrieves a list of tax records with optional filtering and paging.

Examples:

List tax records with a filter

MyobAcumatica::Api::Tax.get_list(
  access_token: access_token,
  query_params: { '$filter' => 'TaxType eq 'Sales'' },
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $expand, $filter, $custom, $skip, $top).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Array<Hash>) —

    List of tax records.



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/myob_acumatica/api/tax.rb', line 200

def get_list(access_token:, query_params: {},
             instance_name: INSTANCE_NAME,
             endpoint_name: ENDPOINT_NAME,
             endpoint_version: ENDPOINT_VERSION,
             logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Tax',
    query_params: query_params,
    logger: logger
  )
end

.invoke_action(access_token:, action_name:, entity:, parameters: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash?

Invokes a custom action on a tax record.

Examples:

Invoke a custom action

MyobAcumatica::Api::Tax.invoke_action(
  access_token: access_token,
  action_name: 'Recalculate',
  entity: { 'id' => tax['id'] },
  parameters: {},
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • action_name (String) —

    The action name to invoke.

  • entity (Hash) —

    Tax entity payload (e.g., { ‘id’ => uuid }).

  • parameters (Hash) (defaults to: {}) —

    Optional parameters for the action.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash, nil) —

    Action response or nil on 204.



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/myob_acumatica/api/tax.rb', line 238

def invoke_action(access_token:, action_name:, entity:, parameters: {},
                  instance_name: INSTANCE_NAME,
                  endpoint_name: ENDPOINT_NAME,
                  endpoint_version: ENDPOINT_VERSION,
                  logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :post,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Tax/#{action_name}",
    body: { 'entity' => entity, 'parameters' => parameters },
    logger: logger
  )
end

.put_entity(access_token:, entity:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Creates or updates a tax record.

Examples:

Create or update a tax

tax = MyobAcumatica::Api::Tax.put_entity(
  access_token: access_token,
  entity: {
    'TaxID' => { 'value' => 'GST' },
    'Description' => { 'value' => 'Goods and Services Tax' }
  },
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • entity (Hash) —

    Tax entity payload.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $expand, $filter, $custom).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The created or updated tax record.



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/myob_acumatica/api/tax.rb', line 277

def put_entity(access_token:, entity:, query_params: {},
               instance_name: INSTANCE_NAME,
               endpoint_name: ENDPOINT_NAME,
               endpoint_version: ENDPOINT_VERSION,
               logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :put,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Tax',
    body: entity,
    query_params: query_params,
    logger: logger
  )
end

.put_file(access_token:, keys:, file_path:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Attaches a file to a tax record. Uses the entity’s files:put link to construct the upload path, then uploads the binary content.

Examples:

Upload a file to a tax record

MyobAcumatica::Api::Tax.put_file(
  access_token: access_token,
  keys: [tax['TaxID']['value']],
  file_path: 'examples/rate-sheet.pdf',
  logger: logger
)

Parameters:

  • access_token (String) —

    OAuth2 access token.

  • keys (Array<String>) —

    Key values identifying the tax record.

  • file_path (String) —

    Absolute or relative path to the file.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil)

Raises:



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/myob_acumatica/api/tax.rb', line 316

def put_file(access_token:, keys:, file_path:,
             instance_name: INSTANCE_NAME,
             endpoint_name: ENDPOINT_NAME,
             endpoint_version: ENDPOINT_VERSION,
             logger: nil)
  entity = get_by_keys(
    access_token: access_token,
    keys: keys,
    instance_name: instance_name,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    logger: logger
  )

  put_template = entity.dig('_links', 'files:put')
  raise MyobAcumatica::Error, 'files:put link not found' unless put_template

  filename = File.basename(file_path)
  path = put_template.gsub('{filename}', filename)

  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :put,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: path,
    body: File.binread(file_path),
    content_type: 'application/octet-stream',
    logger: logger
  )
end