To use LedgerSync, you must carry out an
Operation. The operation will be ledger-specific and will require the
1. Create a client
Clients are responsible for the authentication and requests for a specific ledger. In this example, we will assume you are using the QuickBooks Online ledger.
client = LedgerSync::Ledgers::QuickBooksOnline::Client.new( access_token: access_token, # assuming this is defined client_id: ENV['QUICKBOOKS_ONLINE_CLIENT_ID'], client_secret: ENV['QUICKBOOKS_ONLINE_CLIENT_SECRET'], realm_id: ENV['QUICKBOOKS_ONLINE_REALM_ID'], refresh_token: refresh_token # assuming this is defined )
2. Create resource(s)
Create a resource on which to operate. Some resources have references to other resources. You can use
Util::ResourcesBuilder to create resources and relationships from a structured hash.
resource = LedgerSync::Ledgers::QuickBooksOnline::Customer.new( DisplayName: 'Sample Customer', external_id: customer_external_id # A unique ID from your platform )
3. Create an operation
resource from above, we can now create an
Operation. Operations are typically CRUD-like
methods, typically (though not always) only making a single request.
Operations automatically determine a
Deserializer. These serializers are used to translate to and
the from the ruby
Resource in the format required by the ledger.
operation = LedgerSync::Ledgers::QuickBooksOnline::Customer::Operations::Create.new( client: client, resource: resource )
4. Perform the operation
The next step is to perform the operation. You can do this by simply calling
result = operation.perform # Returns a LedgerSync::OperationResult
This method will return a
LedgerSync::OperationResult which is a special object allowing you to determine the success of the operation, access
responses values (serialized and deserialized), and investigate failures.
if result.success? resource = result.operation.resource # Do something with resource else # result.failure? raise result.error end
5. Save updates to authentication
Because QuickBooks Online uses Oauth 2, you must always be sure to save the access_token, refresh_token, and expirations as they can change with any API call. Operations will always save values back to the client.
Automatically update values in .env
If you have a
.env file present in the root directory of your project, the client will automatically comment out old values and update new
If you want to disable this functionality, you can do so by setting
false when instantiating the
client = LedgerSync::Ledgers::QuickBooksOnline::Client.new( access_token: access_token, # assuming this is defined client_id: ENV['QUICKBOOKS_ONLINE_CLIENT_ID'], client_secret: ENV['QUICKBOOKS_ONLINE_CLIENT_SECRET'], realm_id: ENV['QUICKBOOKS_ONLINE_REALM_ID'], refresh_token: refresh_token, # assuming this is defined update_dotenv: false )
Manually save values
result.operation.client.ledger_attributes_to_save.each do |key, value| # save values end
That’s it! Assuming proper authentication values and valid values on the resource, this will result in a new customer being created in QuickBooks Online.
There are many other resources and operations that can be performed in QuickBooks Online. For a complete guide of these and other ledgers, visit the Reference.