myob_acumatica 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13fbce76da83c644f946012fe508838d0b8a08eb2425202d6138c0dc389cbd4a
-  data.tar.gz: 7841a0ce98ce34f0ab35f71781a00e3e78000578f16c756d4cf90323355f2150
+  metadata.gz: e15a5861adfeb95df2fd9ba27fdcabdd38ddd7256e06114f4f24307c3f094429
+  data.tar.gz: b30cb9b7080780e7017572c24e886785c8ea6c7b136ac770396f36dada9f55b6
 SHA512:
-  metadata.gz: 4f95a2575dbf194e812c0c6aa82d6058dbdce2cde3f8baafae8a5de5c00c87414e46d015901ba41f4d899776849977832dee6a27401eaa14b09360e801b83010
-  data.tar.gz: ac46af5f83b581a64f55edf70aeb4a7887962cbebd880ead202ea5e2361ce4a2dfd3de95ed2e5e255a2dc8a8f52dfeef24c6cc283c250e13c5b9a8d499adb49e
+  metadata.gz: 8d505819ddac73957aa98a108f1f4a7d2ae9d8f21b9b0f5faa7f026fb61e2e52c16e45cdf8f04eab7e2d4b69f6c9b45d920a800060c5b896d997c00978e89bcc
+  data.tar.gz: 9d558ce25b14bc005aebe2c4693d3ca2c9e1192d36a1f6aaf4ff984d8e640a4590b453ea75276acd8a47eb28fcd5f46200d354319353e535886ba77249443257

data/CHANGELOG.md

@@ -1,5 +1,32 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-02-05
+## [0.1.4] - 2025-08-13
+### Added
+- **Tax API** support:
+  - `delete_by_id`
+  - `delete_by_keys`
+  - `get_ad_hoc_schema`
+  - `get_by_id`
+  - `get_by_keys`
+  - `get_list`
+  - `invoke_action`
+  - `put_entity`
+  - `put_file`
 
-- Initial release
+## [0.1.3] - 2025-08-10
+### Added
+- **Payment API** support:
+  - `delete_by_id`
+  - `delete_by_keys`
+  - `get_ad_hoc_schema`
+  - `get_by_id`
+  - `get_by_keys`
+  - `get_list`
+  - `put_entity`
+  - `put_file`
+  - `invoke_action`
+  - `capture_credit_card_payment`
+  - `card_operation`
+  - `release_payment`
+  - `void_card_payment`
+  - `void_payment`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    myob_acumatica (0.1.0)
+    myob_acumatica (0.1.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,8 +1,6 @@
-# Ruby library for the MYOB Acumatica API
+# Myob Acumatica
 
-A lightweight Ruby client for accessing the MYOB Acumatica REST API via OAuth2.
-
----
+A simple to use Ruby library for integrating with the MYOB Acumatica REST API via OAuth2.
 
 ## Installation
 
@@ -18,38 +16,84 @@ Without Bundler:
 gem install myob_acumatica
 ```
 
----
+## Configuration
 
-## Setup
+Provide configuration via **environment variables** and **explicitly per call**.
 
-Set the following environment variables in your host application:
+**Note**: explicit parameters always override environment variables.
 
-```bash
-MYOB_ACUMATICA_INSTANCE_NAME=your-instance.myob.com
-MYOB_ACUMATICA_CLIENT_ID=your-client-id
-MYOB_ACUMATICA_CLIENT_SECRET=your-client-secret
+### Environment variables
+
+```env
+MYOB_ACUMATICA_INSTANCE_NAME=example.myobadvanced.com
+MYOB_ACUMATICA_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx@Company
+MYOB_ACUMATICA_CLIENT_SECRET=xxxxxxxxxx_x_xxxxxxxxx
 MYOB_ACUMATICA_REDIRECT_URI=http://localhost:4567/oauth2/callback
 MYOB_ACUMATICA_SCOPE=api offline_access
 MYOB_ACUMATICA_ENDPOINT_NAME=Default
-MYOB_ACUMATICA_ENDPOINT_VERSION=22.200.001
+MYOB_ACUMATICA_ENDPOINT_VERSION=20.200.001
 ```
 
----
+```ruby
+MyobAcumatica::Api::Customer.get_list(
+  access_token: token["access_token"],
+  query_params: { '$filter' => "Status eq 'Active'" }
+)
+```
+
+### Explicit parameters
+
+```ruby
+MyobAcumatica::Api::Customer.get_list(
+  access_token: token["access_token"],
+  instance_name: "example.myobadvanced.com",
+  endpoint_name: "Default",
+  endpoint_version: "20.200.001",
+  query_params: { '$filter' => "Status eq 'Active'" }
+)
+```
+
+## Authorization
+
+Allow a client application to obtain an access token on behalf of a user, using an authorization code granted by the user after consent.
 
-## OAuth2 Flow
+### Generate authorization request URL
 
-Get the authorization URL to initiate login:
+Redirect the user to the authorization endpoint to initiate the consent flow.
 
 ```ruby
-MyobAcumatica::OAuth2::Token.authorize_url
+MyobAcumatica::OAuth2::Token.authorize_url(
+  instance_name: 'example.myobadvanced.com',
+  redirect_uri: 'https://example.myobadvanced.com/oauth2/callback',
+  client_id: 'abc123',
+  scope: 'api offline_access'
+)
+```
+
+This returns a URL like:
+
+```
+https://example.myobadvanced.com/identity/connect/authorize?response_type=code&client_id=abc123&redirect_uri=https%3A%2F%2Fexample.myobadvanced.com%2Foauth2%2Fcallback&scope=api+offline_access
 ```
 
-Exchange the code for an access token and a refresh token
+Send users to this URL to initiate the authorization code grant flow.
+
+### Exchange authorization code for access token
+
+After the user grants consent, Acumatica will redirect to your callback URL with a `code` parameter. Exchange it for an access token:
 
 ```ruby
-token = MyobAcumatica::OAuth2::Token.authorize(code: params[:code])
+token = MyobAcumatica::OAuth2::Token.authorize(
+  code: params[:code],
+  instance_name: 'example.myobadvanced.com',
+  redirect_uri: 'https://example.myobadvanced.com/oauth2/callback',
+  client_id: 'abc123',
+  client_secret: 'secret123'
+)
 ```
 
+Example response:
+
 ```ruby
 {
   "access_token" => "...",
@@ -60,21 +104,34 @@ token = MyobAcumatica::OAuth2::Token.authorize(code: params[:code])
 }
 ```
 
-Refresh the access token when expired:
+### Refresh access token
+
+When the access token expires, use the `refresh_token` to obtain a new one without prompting the user again.
 
 ```ruby
-token = MyobAcumatica::OAuth2::Token.refresh(refresh_token: token["refresh_token"])
+token = MyobAcumatica::OAuth2::Token.refresh(
+  refresh_token: token["refresh_token"],
+  instance_name: 'example.myobadvanced.com',
+  client_id: 'abc123',
+  client_secret: 'secret123'
+)
 ```
 
----
+This returns a fresh token object with the same structure.
 
-## Customer Examples
+
+## Usage
+
+### Customers
 
 Create or update a customer:
 
 ```ruby
 MyobAcumatica::Api::Customer.put_entity(
-  access_token: token["access_token"],
+  access_token: token['access_token'],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   entity: {
     'CustomerID' => { 'value' => 'JOHNGOOD' },
     'CustomerName' => { 'value' => 'John Good' },
@@ -87,7 +144,10 @@ List customers:
 
 ```ruby
 MyobAcumatica::Api::Customer.get_list(
-  access_token: token["access_token"],
+  access_token: token['access_token'],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   query_params: { '$filter' => "Status eq 'Active'" }
 )
 ```
@@ -96,7 +156,10 @@ Get customer by keys:
 
 ```ruby
 MyobAcumatica::Api::Customer.get_by_keys(
-  access_token: token["access_token"],
+  access_token: token['access_token'],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   keys: ['JOHNGOOD']
 )
 ```
@@ -105,20 +168,24 @@ Delete a customer:
 
 ```ruby
 MyobAcumatica::Api::Customer.delete_by_keys(
-  access_token: token["access_token"],
+  access_token: token['access_token'],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   keys: ['JOHNGOOD']
 )
 ```
 
----
-
-## Invoice Examples
+### Invoices
 
 Create an invoice:
 
 ```ruby
 MyobAcumatica::Api::Invoice.put_entity(
   access_token: token["access_token"],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   entity: {
     'CustomerID' => { 'value' => 'JOHNGOOD' },
     'Date' => { 'value' => '2025-06-06' },
@@ -138,6 +205,9 @@ List invoices:
 ```ruby
 MyobAcumatica::Api::Invoice.get_list(
   access_token: token["access_token"],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   query_params: {
     '$filter' => "Status eq 'Open'",
     '$top' => 10,
@@ -151,6 +221,9 @@ Get invoice by ID:
 ```ruby
 MyobAcumatica::Api::Invoice.get_by_id(
   access_token: token["access_token"],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   id: '00000000-0000-0000-0000-000000000000'
 )
 ```
@@ -160,18 +233,17 @@ Delete an invoice:
 ```ruby
 MyobAcumatica::Api::Invoice.delete_by_id(
   access_token: token["access_token"],
+  instance_name: 'example.myobadvanced.com',
+  endpoint_name: 'Default',
+  endpoint_version: '20.200.001',
   id: '00000000-0000-0000-0000-000000000000'
 )
 ```
 
----
-
 ## Documentation
 
 See full API reference and usage examples: [rubydoc.info/gems/myob_acumatica](https://www.rubydoc.info/gems/myob_acumatica)
 
----
-
 ## Development
 
 ### 1. Clone the repo
@@ -185,7 +257,7 @@ bundle install
 ### 2. Create a `.env` file
 
 ```env
-MYOB_ACUMATICA_INSTANCE_NAME=your-instance.myob.com
+MYOB_ACUMATICA_INSTANCE_NAME=example.myob.com
 MYOB_ACUMATICA_CLIENT_ID=your-client-id
 MYOB_ACUMATICA_CLIENT_SECRET=your-client-secret
 MYOB_ACUMATICA_REDIRECT_URI=http://localhost:4567/oauth2/callback
@@ -219,8 +291,6 @@ Try this command with your token:
 MyobAcumatica::Api::Customer.get_list(access_token: token["access_token"])
 ```
 
----
-
 ## Contributing
 
 Bug reports and pull requests are welcome at:
@@ -229,8 +299,6 @@ https://github.com/fast-programmer/myob_acumatica
 Please follow the code of conduct:
 https://github.com/fast-programmer/myob_acumatica/blob/master/CODE_OF_CONDUCT.md
 
----
-
 ## License
 
 MIT — see the LICENSE

data/examples/invoice.rb

@@ -18,18 +18,26 @@ invoice1 = MyobAcumatica::Api::Invoice.put_entity(
   access_token: access_token,
   entity: {
     'Customer' => { 'value' => 'JOHNGOOD1' },
-    'CustomerID' => { 'value' => 'JOHNGOOD1' },
     'Date' => { 'value' => Date.today.strftime('%Y-%m-%d') },
     'DueDate' => { 'value' => (Date.today + 30).strftime('%Y-%m-%d') },
     'Terms' => { 'value' => 'NET14DAYS' },
     'Type' => { 'value' => 'Invoice' },
     'Hold' => { 'value' => false },
+    'PostPeriod' => { 'value' => '08-2025' },
     'BillingAddressOverride' => { 'value' => true },
     'BillingAddress' => {
       'AddressLine1' => { 'value' => 'Fillmore Str' },
       'City' => { 'value' => 'San Francisco' },
       'State' => { 'value' => 'CA' }
     },
+    'Description' => { 'value' => 'Test stock item' },
+    'Details' => [
+      {
+        'Description' => { 'value' => 'Pair of sneakers' },
+        'Quantity' => { 'value' => 1 },
+        'UnitPrice' => { 'value' => 100.00 }
+      }
+    ],
     'custom' => {
       'Document' => {
         'DiscDate' => { 'value' => (Date.today + 10).strftime('%Y-%m-%dT00:00:00+00:00') }
@@ -39,6 +47,14 @@ invoice1 = MyobAcumatica::Api::Invoice.put_entity(
   logger: logger
 )
 
+MyobAcumatica::Api::Invoice.release(
+  access_token: access_token,
+  entity: {
+    'id' => invoice1['id']
+  },
+  logger: logger
+)
+
 MyobAcumatica::Api::Invoice.get_by_id(
   access_token: access_token,
   id: invoice1['id'],
@@ -54,11 +70,55 @@ MyobAcumatica::Api::Invoice.get_by_keys(
 MyobAcumatica::Api::Invoice.get_list(
   access_token: access_token,
   query_params: {
+    '$filter' => "Type eq 'Invoice'"
     # '$filter' => "Status eq 'Open' and "\
     #   "LastModifiedDateTime gt datetimeoffset'2020-08-18T23:59:59.999+04:00'",
     # '$expand' => 'Invoices',
-    '$skip' => 1,
-    '$top' => 4
+    # '$skip' => 1,
+    # '$top' => 4
+  },
+  logger: logger
+)
+
+credit_memo1 = MyobAcumatica::Api::Invoice.put_entity(
+  access_token: access_token,
+  entity: {
+    'Customer' => { 'value' => 'JOHNGOOD1' },
+    'CustomerID' => { 'value' => 'JOHNGOOD1' },
+    'Date' => { 'value' => Date.today.strftime('%Y-%m-%d') },
+    'DueDate' => { 'value' => (Date.today + 30).strftime('%Y-%m-%d') },
+    'Terms' => { 'value' => 'NET14DAYS' },
+    'Type' => { 'value' => 'Credit Memo' },
+    'Hold' => { 'value' => false },
+    'PostPeriod' => { 'value' => '08-2025' },
+    'BillingAddressOverride' => { 'value' => true },
+    'BillingAddress' => {
+      'AddressLine1' => { 'value' => 'Fillmore Str' },
+      'City' => { 'value' => 'San Francisco' },
+      'State' => { 'value' => 'CA' }
+    },
+    'custom' => {
+      'Document' => {
+        'DiscDate' => { 'value' => (Date.today + 10).strftime('%Y-%m-%dT00:00:00+00:00') }
+      }
+    }
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.release(
+  access_token: access_token,
+  entity: {
+    'Type' => credit_memo1['Type'],
+    'ReferenceNbr' => credit_memo1['ReferenceNbr']
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.get_list(
+  access_token: access_token,
+  query_params: {
+    '$filter' => "Type eq 'Credit Memo'"
   },
   logger: logger
 )
@@ -77,12 +137,6 @@ MyobAcumatica::Api::Invoice.invoke_action(
   logger: logger
 )
 
-# MyobAcumatica::Api::Invoice.release(
-#   access_token: access_token,
-#   entity: { 'id' => invoice1['id'] },
-#   logger: logger
-# )
-
 MyobAcumatica::Api::Invoice.delete_by_keys(
   access_token: access_token,
   keys: [invoice1['Type']['value'], invoice1['ReferenceNbr']['value']],
@@ -99,6 +153,7 @@ invoice2 = MyobAcumatica::Api::Invoice.put_entity(
     'Terms' => { 'value' => 'NET14DAYS' },
     'Type' => { 'value' => 'Invoice' },
     'Hold' => { 'value' => false },
+    'PostPeriod' => { 'value' => '08-2025' },
     'BillingAddressOverride' => { 'value' => true },
     'BillingAddress' => {
       'AddressLine1' => { 'value' => 'Fillmore Str' },