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 Invoice 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.

Step1 : ServiceTrade - Creating the External System

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

1. While logged in as an Account Admin, open your Account Settings.
2. On the right-hand side of the settings screen, click Add an External System.
   
3. External IDs require a system name and a system label. Enter a System Name and System Label.
   • Note: In this example we entered 'peachtree' as the internal system name and 'Peachtree' as the display name.
     
4. Click to expand the Integrations accordion.
5. Click on the Configure External System: [System Label] button.
   
6. In the configuration screen, check the Can Be Sent Invoices.
7. Click the Save Configuration button.
   
8. This configuration causes the 'Send to Accounting System' button to appear on all invoices in ServiceTrade. See the next section

Step 2: ServiceTrade - Sending an Invoice to your External Account System

1. After you have completed the steps above. Create an invoice in ServiceTrade.
2. On the invoice page, click the Send to Accounting System button.
   
3. Choose the relevant Accounting System in the list of popup window that appears
4. Click Submit.
   
5. This workflow changes the status of the invoice to pending_accounting.

  Step 3: 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 the external accounting system. 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 the external account system.
4. For each invoice that is successfully imported into the external accounting system, update the invoice status in ServiceTrade by PUTing to that invoice with a status of processed.
5. Optionally, if the external accounting system 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 the external accounting system, 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).