Technical Guide to Invoicing Integrations

ServiceTrade offers built-in invoicing integrations to several accounting systems, including QuickBooks Online and QuickBooks Desktop. However, customers who use other accounting systems may wish to create their own integrations, or use integrations developed by third-party vendors.

This technical guide provides best practices for developing a third-party integration between an accounting system and ServiceTrade.

Key ServiceTrade features:

• External IDs: ServiceTrade's External IDs feature, which enables users to associate records in ServiceTrade (jobs, locations, customers, etc) with corresponding records in another system, such as an accounting system.
• Invoice comments: ServiceTrade's Comment API allows API consumers to add comments to invoices.
• Invoice statuses: ServiceTrade's Invoice API allows API consumers to search for invoices in a given status, and to update the status of a given invoice. 
• The following invoice statuses should be used:

• pending_accounting: This status indicates that the invoice is ready to be retrieved and delivered to the accounting system.
• processed: This status indicates that the invoice has been successfully delivered to the accounting system.
• failed: This status indicates that the invoice could not be successfully delivered to the accounting system.

This example uses Peachtree, a legacy accounting system product, to demonstrate how an accounting system integration might be developed using those features.

ServiceTrade: Creating the external system

1. As a user with account administrator permissions, click on the user avatar in the upper right corner of the page and select 'Account Settings'

2. On the Account Settings page, click 'Add an External System' in the menu on the right:

3. In the form that appears, choose 'Standard' as the type, then enter 'peachtree' as the internal system name and 'Peachtree' as the display name, then click 'Submit'.

4. Open the 'Integrations' section and click on the green 'Configure External System: Peachtree' button.

5. In the configuration screen, check the 'Can Be Sent Invoices' box and click 'Save Configuration'.

This configuration causes the 'Send to Accounting System' button to appear on all invoices in ServiceTrade.

ServiceTrade: Sending an Invoice to Peachtree

1. Create an invoice in ServiceTrade.

2. Click 'Send to Accounting System'.

3. Choose 'Peachtree' in the list of popup window that appears, and click 'Submit'.

This workflow changes the status of the invoice to pending_accounting.

Third-Party Integration: Retrieving and Processing Invoices

The third-party integration system should perform the following actions:

1. On a periodic basis, retrieve all invoices in pending_accounting status, by issuing an API request such as GET /api/invoice?status=pending_accounting. (Alternatively, the integration system could listen for webhooks and act on any updated invoices whose status is now pending_accounting.)
2. Apply business logic necessary to convert the ServiceTrade invoice record into the format required by Peachtree. Optionally, the integration system can leverage the ServiceTrade Accounting Connector to apply business rules and formatting requirements.
3. Attempt to insert each invoice record into Peachtree.
4. For each invoice that is successfully imported into Peachtree, update the invoice status in ServiceTrade by PUTing to that invoice with a status of processed.
5. Optionally, if Peachtree is configured to assign invoice numbers to newly created invoices, the invoice number of the invoice in ServiceTrade can be updated accordingly by including the invoice number in the PUT request.
6. For each invoice that could not be successfully imported into Peachtree, update the invoice status in ServiceTrade by PUTing to that invoice with a status of failed. POST a comment to the invoice with details of the failure reason, using private visibility  (visibility property should be an empty array).