Module: MyobAcumatica::Api::Customer

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

Overview

Provides methods to interact with the Customer 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 customer by ID.

Examples:

Delete a customer by ID

MyobAcumatica::Api::Customer.delete_by_id(
  access_token: '...',
  id: '00000000-0000-4000-8000-000000000000',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The unique ID of the customer.

  • 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.



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

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: "Customer/#{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 customer by composite keys.

Examples:

Delete a customer by keys

MyobAcumatica::Api::Customer.delete_by_keys(
  access_token: '...',
  keys: ['JOHNGOOD'],
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    An array of keys that uniquely identify the customer.

  • 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.



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

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: "Customer/#{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 customer endpoint.

Examples:

Retrieve the ad-hoc schema

MyobAcumatica::Api::Customer.get_ad_hoc_schema(
  access_token: '...',
  logger: Logger.new($stdout)
)

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



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

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: 'Customer/$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 customer by ID.

Examples:

Retrieve a customer by ID

MyobAcumatica::Api::Customer.get_by_id(
  access_token: '...',
  id: '00000000-0000-4000-8000-000000000000',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The unique ID of the customer.

  • 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 customer



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

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: "Customer/#{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 customer by keys.

Examples:

Retrieve a customer by keys

MyobAcumatica::Api::Customer.get_by_keys(
  access_token: '...',
  keys: ['JOHNGOOD'],
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    An array of keys that uniquely identify the customer.

  • 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 customer



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

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: "Customer/#{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 customers.

Examples:

Retrieve a list of customers

MyobAcumatica::Api::Customer.get_list(
  access_token: '...',
  query_params: { '$top' => 10 },
  logger: Logger.new($stdout)
)

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 customers.



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

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

Examples:

Invoke the ‘CreateContactFromCustomer’ action

MyobAcumatica::Api::Customer.invoke_action(
  access_token: '...',
  action_name: 'CreateContactFromCustomer',
  entity: { 'CustomerID' => { 'value' => 'JOHNGOOD' } },
  parameters: {
    'FirstName' => { 'value' => 'John' },
    'LastName' => { 'value' => 'Smith' }
  },
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • action_name (String) —

    The name of the action to invoke (e.g., ‘CreateContactFromCustomer’).

  • entity (Hash) —

    The entity payload 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, if any.



304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/myob_acumatica/api/customer.rb', line 304

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: "Customer/#{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

Updates or creates a customer entity.

Examples:

Update or create a customer entity with detailed information

MyobAcumatica::Api::Customer.put_entity(
  access_token: '...',
  instance_name: 'example.myobadvanced.com',
  entity: {
    'CustomerID' => { 'value' => 'JOHNGOOD' },
    'CustomerName' => { 'value' => 'John Good' },
    'CustomerClass' => { 'value' => 'CUSTDFT' }
  }
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • entity (Hash) —

    The customer entity.

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

    Optional query parameters.

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

    The name of the instance.

  • 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 request debugging.

Returns:

  • (Hash) —

    The response from the server.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/myob_acumatica/api/customer.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: 'Customer',
    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 customer record by resolving the ‘files:put` link.

Examples:

Upload a PDF to a customer record

MyobAcumatica::Api::Customer.put_file(
  access_token: '...',
  instance_name: 'example.myobadvanced.com',
  keys: ['JOHNGOOD'],
  file_path: 'examples/sample.pdf'
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    Key(s) identifying the customer record.

  • file_path (String) —

    Full path to the file to be uploaded.

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

    The name of the instance.

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



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
279
 
# File 'lib/myob_acumatica/api/customer.rb', line 250

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

  put_url_template = customer.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