Intacct Ruby Gem

A Ruby gem for interacting with the Sage Intacct API.

Installation

Add this line to your application's Gemfile:

gem "intacct"

Requirements: Ruby 3.2 or higher.

Usage

Configuration

Configure the gem with your Intacct credentials:

Intacct.configure do |config|
  config.sender_id = ENV["INTACCT_SENDER_ID"]
  config.sender_password = ENV["INTACCT_SENDER_PASSWORD"]
end

Security Note: Never commit credentials to version control. Use environment variables or a secrets management system.

Making Requests

Query Records

Query Intacct objects with filters and sorting:

query = Intacct::Functions::Query.new(
  object: "CUSTOMER",
  select: ["CUSTOMERID", "NAME", "EMAIL", "STATUS"],
  filter: { "STATUS" => "active" },
  order: { "NAME" => "asc" }
)

request = Intacct::Request.new
request.use_credentials_authentication(
  user_id: ENV["INTACCT_USER_ID"],
  company_id: ENV["INTACCT_COMPANY_ID"],
  user_password: ENV["INTACCT_USER_PASSWORD"]
)
request.add_function(query, "query-001")

response = Intacct::Gateway.new.send_request(request)

if response.successful?
  result = response.get_function_result("query-001")
  if result.successful?
    customers = result.data
    customers.each do |customer|
      puts "#{customer['CUSTOMERID']}: #{customer['NAME']}"
    end
  else
    puts "Function error: #{result.errors.join(', ')}"
  end
else
  puts "Request failed"
end

Create Records

Create new records in Intacct:

create = Intacct::Functions::Create.new(
  object: "CUSTOMER",
  fields: {
    "CUSTOMERID" => "C-001",
    "NAME" => "Acme Corporation",
    "EMAIL" => "[email protected]",
    "STATUS" => "active"
  }
)

request = Intacct::Request.new
request.use_credentials_authentication(
  user_id: ENV["INTACCT_USER_ID"],
  company_id: ENV["INTACCT_COMPANY_ID"],
  user_password: ENV["INTACCT_USER_PASSWORD"]
)
request.add_function(create, "create-001")

response = Intacct::Gateway.new.send_request(request)

if response.successful?
  result = response.get_function_result("create-001")
  puts "Customer created!" if result.successful?
end

Update Records

Update existing records:

update = Intacct::Functions::Update.new(
  object: "CUSTOMER",
  keys: { "CUSTOMERID" => "C-001" },
  fields: {
    "EMAIL" => "[email protected]",
    "STATUS" => "inactive"
  }
)

request = Intacct::Request.new
request.use_credentials_authentication(
  user_id: ENV["INTACCT_USER_ID"],
  company_id: ENV["INTACCT_COMPANY_ID"],
  user_password: ENV["INTACCT_USER_PASSWORD"]
)
request.add_function(update, "update-001")

response = Intacct::Gateway.new.send_request(request)

Read by ID

Read a specific record by ID:

read = Intacct::Functions::Read.new(
  object: "CUSTOMER",
  keys: "C-001",
  fields: ["CUSTOMERID", "NAME", "EMAIL"]
)

request = Intacct::Request.new
request.use_credentials_authentication(
  user_id: ENV["INTACCT_USER_ID"],
  company_id: ENV["INTACCT_COMPANY_ID"],
  user_password: ENV["INTACCT_USER_PASSWORD"]
)
request.add_function(read, "read-001")

response = Intacct::Gateway.new.send_request(request)

Case-Insensitive Queries

Perform case-insensitive queries:

query = Intacct::Functions::Query.new(
  object: "CUSTOMER",
  select: ["CUSTOMERID", "NAME"],
  filter: { "NAME" => "acme" },
  case_insensitive: true
)

Error Handling

Always check response status and handle errors:

response = Intacct::Gateway.new.send_request(request)

if response.successful?
  result = response.get_function_result("my-control-id")
  if result.successful?
    puts "Success: #{result.data}"
  else
    puts "Function error: #{result.errors.join(', ')}"
  end
else
  puts "Request failed"
end

Session Authentication

Get an API session for subsequent requests:

get_session = Intacct::Functions::GetApiSession.new(location_id: "US")

request = Intacct::Request.new
request.use_credentials_authentication(
  user_id: ENV["INTACCT_USER_ID"],
  company_id: ENV["INTACCT_COMPANY_ID"],
  user_password: ENV["INTACCT_USER_PASSWORD"]
)
request.add_function(get_session, "session-001")

response = Intacct::Gateway.new.send_request(request)

if response.successful?
  result = response.get_function_result("session-001")
  if result.successful?
    session_id = result.data["sessionid"]
    # Use session_id for subsequent requests
  end
end

Available Functions

Query - Execute read queries with filters and sorting
Create - Create new records
Read - Read specific records by ID
Update - Update existing records
CreateArAdjustment - Create AR adjustments
GetApiSession - Get API session for authentication
RetrievePdf - Retrieve PDF documents
ReversePayment - Reverse payments

For detailed API documentation, see RubyDoc.

Development

After checking out the repo, run:

bundle install

Run tests:

bundle exec rake test

Run linter:

bundle exec rubocop

Generate documentation:

bundle exec yard doc
bundle exec yard server  # View docs at http://localhost:8808

To install this gem onto your local machine:

bundle exec rake install

To release a new version:

Update version in lib/intacct/version.rb
Update CHANGELOG.md
Commit changes
Run bundle exec rake release (creates tag and pushes to RubyGems)

Contributing

Fork it (https://github.com/dpaluy/intacct/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Please ensure:

Tests pass (bundle exec rake test)
Code follows style guide (bundle exec rubocop)
New features include tests and documentation

License

The gem is available as open source under the terms of the MIT License.