Module: MyobAcumatica::Api::Invoice

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

Overview

Provides methods to interact with the Invoice 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 an invoice by ID.

Examples:

Delete an invoice by ID

MyobAcumatica::Api::Invoice.delete_by_id(
  access_token: '...',
  id: '00000000-0000-4000-8000-000000000000',
  instance_name: 'example.myobadvanced.com',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The unique ID of the invoice.

  • 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 for logging the request process.

Returns:

  • (nil) —

    Always nil.



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

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: "Invoice/#{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 an invoice by composite keys.

Examples:

Delete an invoice by keys

MyobAcumatica::Api::Invoice.delete_by_keys(
  access_token: '...',
  keys: ['AR', 'INV000123'],
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    An array of keys that uniquely identify the invoice.

  • 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 for logging the request process.

Returns:

  • (nil) —

    Always nil.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/myob_acumatica/api/invoice.rb', line 54

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: "Invoice/#{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 for the invoice endpoint.

Examples:

Retrieve the ad-hoc schema

MyobAcumatica::Api::Invoice.get_ad_hoc_schema(
  access_token: '...',
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The 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 for logging the request process.

Returns:

  • (Hash) —

    The ad hoc schema



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/myob_acumatica/api/invoice.rb', line 82

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: 'Invoice/$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 an invoice by unique ID.

Examples:

Retrieve an invoice by ID

MyobAcumatica::Api::Invoice.get_by_id(
  access_token: '...',
  id: 'b8c01a2d-ff7f-4f0f-bba5-abc123456789',
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The unique invoice ID (UUID).

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

    Optional query parameters for the request.

  • 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 for HTTP debugging.

Returns:

  • (Hash) —

    The invoice with the given ID.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/myob_acumatica/api/invoice.rb', line 146

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: "Invoice/#{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 an invoice by keys.

Examples:

Retrieve an invoice by keys

MyobAcumatica::Api::Invoice.get_by_keys(
  access_token: '...',
  keys: ['AR', 'INV000123'],
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    An array of keys that uniquely identify the invoice.

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

    Additional query parameters for the request.

  • 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 for logging the request process.

Returns:

  • (Hash) —

    The invoice.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/myob_acumatica/api/invoice.rb', line 113

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: "Invoice/#{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 invoices.

Examples:

Retrieve a list of invoices

MyobAcumatica::Api::Invoice.get_list(
  access_token: '...',
  query_params: { '$top' => 10 },
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

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

    Additional query parameters for the request.

  • 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 for logging the request process.

Returns:

  • (Array<Hash>) —

    A list of invoices.



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

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: 'Invoice',
    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 the Invoice entity.

Examples:

Apply a payment or custom action

MyobAcumatica::Api::Invoice.invoke_action(
  access_token: '...',
  action_name: 'ReleaseInvoice',
  entity: { 'Type' => { 'value' => 'Invoice' }, 'InvoiceNbr' => { 'value' => 'INV000123' } },
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • action_name (String) —

    The name of the action to invoke.

  • entity (Hash) —

    The invoice entity on which to invoke the action.

  • 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 for HTTP debugging.

Returns:

  • (Hash, nil) —

    The response from the action.



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/myob_acumatica/api/invoice.rb', line 299

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: "Invoice/#{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 an invoice entity.

Examples:

Create or update an invoice

MyobAcumatica::Api::Invoice.put_entity(
  access_token: '...',
  entity: {
    'CustomerID' => { 'value' => 'JOHNGOOD' },
    'Type' => { 'value' => 'Invoice' },
    'InvoiceNbr' => { 'value' => 'INV000123' }
  },
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • entity (Hash) —

    The invoice entity to create or update.

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

    Additional query parameters for the request.

  • 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 for logging the request process.

Returns:

  • (Hash) —

    The updated or created invoice.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/myob_acumatica/api/invoice.rb', line 213

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: 'Invoice',
    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

Uploads a file to a specific invoice record by resolving the files:put link.

Examples:

Upload a PDF to an invoice

MyobAcumatica::Api::Invoice.put_file(
  access_token: '...',
  keys: ['AR', 'INV000123'],
  file_path: 'examples/invoice.pdf',
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    Key(s) identifying the invoice record.

  • file_path (String) —

    Full path to the file to be uploaded.

  • 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 for HTTP debugging.

Returns:

  • (nil) —

    Returns nil if successful.

Raises:



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
277
278
 
# File 'lib/myob_acumatica/api/invoice.rb', line 249

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

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

  filename = File.basename(file_path)
  path = put_url_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

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

Releases an invoice.

Examples:

Release an invoice

MyobAcumatica::Api::Invoice.release(
  access_token: '...',
  entity: {
    'Type' => { 'value' => 'Invoice' },
    'InvoiceNbr' => { 'value' => 'INV000123' }
  },
  instance_name: 'example.myobadvanced.com'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • entity (Hash) —

    The entity.

  • parameters (Hash) (defaults to: nil) —

    The parameters.

  • 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 for HTTP debugging.

Returns:

  • (Hash) —

    The response from the release action.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/myob_acumatica/api/invoice.rb', line 336

def release(access_token:, entity:, parameters: nil,
            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: 'Invoice/ReleaseInvoice',
    body: { 'entity' => entity, 'parameters' => parameters },
    logger: logger
  )
end