Project

myob_acumatica

0.0
The project is in a healthy, maintained state
myob_acumaticafast-programmer/myob_acumaticaHomepageDocumentationSource CodeBug Tracker
Ruby client for MYOB Acumatica
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
1,395
Stars
0
Forks
0
Watchers
1
 Releases
Current version
0.1.6
Total releases
7
First release
2025-02-07
Latest release
2025-09-17
 Issues
Open Issues
0
Closed Issues
1
Total Issues
1
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
1
Merged Pull Requests
6
Pull Request Acceptance Rate
85%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-05-16
Reverse Dependencies
0

 Dependencies

Development

yard
~> 0.9
byebug
~> 11.1
dotenv
~> 3.1
pry
~> 0.15
puma
~> 6.6
rackup
~> 2.2
rerun
~> 0.14
rubocop
~> 1.71
sinatra
~> 4.1
 Project Readme

Myob Acumatica

A simple to use Ruby library for integrating with the MYOB Acumatica REST API via OAuth2.

Installation

Using Bundler:

bundle add myob_acumatica

Without Bundler:

gem install myob_acumatica

Configuration

Provide via environment variables or explicit arguments.

Environment variables

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=20.200.001
MyobAcumatica::Api::Customer.get_list(
  access_token: token["access_token"],
  query_params: { '$filter' => "Status eq 'Active'" }
)

Explicit arguments

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'" }
)

Note: explicit arguments override environment variables.

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.

Generate authorization request URL

Redirect the user to the authorization endpoint to initiate the consent flow.

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

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:

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:

{
  "access_token" => "...",
  "expires_in" => 3600,
  "token_type" => "Bearer",
  "refresh_token" => "...",
  "scope" => "api offline_access"
}

Refresh access token

When the access token expires, use the refresh_token to obtain a new one without prompting the user again.

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.

Usage

Customers

Create or update a customer:

MyobAcumatica::Api::Customer.put_entity(
  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' },
    'CustomerClass' => { 'value' => 'CUSTDFT' }
  }
)

List customers:

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'" }
)

Get customer by keys:

MyobAcumatica::Api::Customer.get_by_keys(
  access_token: token['access_token'],
  instance_name: 'example.myobadvanced.com',
  endpoint_name: 'Default',
  endpoint_version: '20.200.001',
  keys: ['JOHNGOOD']
)

Delete a customer:

MyobAcumatica::Api::Customer.delete_by_keys(
  access_token: token['access_token'],
  instance_name: 'example.myobadvanced.com',
  endpoint_name: 'Default',
  endpoint_version: '20.200.001',
  keys: ['JOHNGOOD']
)

Invoices

Create an invoice:

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' },
    'Details' => [
      {
        'InventoryID' => { 'value' => 'CONSULTING' },
        'Quantity' => { 'value' => 2 },
        'UnitPrice' => { 'value' => 150.0 }
      }
    ]
  }
)

List invoices:

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,
    '$select' => 'InvoiceNbr,CustomerID,Status,Date'
  }
)

Get invoice by ID:

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'
)

Delete an invoice:

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

Development

1. Clone the repo

git clone https://github.com/fast-programmer/myob_acumatica.git
cd myob_acumatica
bundle install

2. Create a .env file

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
MYOB_ACUMATICA_SCOPE=api offline_access
MYOB_ACUMATICA_ENDPOINT_NAME=Default
MYOB_ACUMATICA_ENDPOINT_VERSION=22.200.001

3. Run the Sinatra example app

This test app helps acquire an OAuth token and inspect customer data.

bundle exec ruby examples/app.rb

Visit in your browser:

4. Open an interactive shell

bin/console

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: https://github.com/fast-programmer/myob_acumatica

License

MIT — see the LICENSE https://opensource.org/licenses/MIT