An application programming interface (API) allows other software and web applications to interact with Saasu. Just as humans do by creating, reading, updating and deleting transactions. Our API framework has been built in the REST style. All calls are conducted through unified HTTP methods: GET, POST, and DELETE. You’ll need a basic understanding of XML and Schema.

• Activities
• Entities
• HTTP Delete
• HTTP Get
• HTTP Post Tasks
• Known API Issues
• Reports
• REST Clients (MS .NET)

Development & Testing

Develop and test in a free file which have full WSAPI access to the Saasu online accounting engine. Any changes you make here will not affect your live files. Note that Transaction Data cannot be migrated from the test file to a live file. If you are not a current user of Saasu, then sign up for Saasu first. If you are a user of a Saasu subscription already, then you don’t have to sign up for a new subscription.

Sample code and a test file

Grab the open source Saasu REST Client and Sample Application. Sign up for a Saasu account if you haven’t got one. If you already have a Saasu account and want another free file for testing the API, you can create another free account by going to My Saasu > Manage Subscription > Upgrade and add another free file. If you need to test large volumes of data above the free file limit then upgrade to add a 3 month Saasu PRO or GLOBAL (multi-currency) file to do this.

Fair play limits

Saasu has the following fair play rules with respect to the use of the API per File:

• Maximum of 5 requests per second.
• Maximum of 2,000 requests per day.
• All synchronisation activities must rely on Last Modified where this is supported in the API.
• If you are making hundreds of requests at once, insert a minimum of 2 seconds delay for every 50 requests.
• When sending a multiple task request limit the number of tasks to a maximum of 50.

If Saasu observes excessive API requests above the limits, Saasu may temporarily disable API access until the request approach is altered or defects in your code are resolved by you.

Important note regarding API work to process payments

Ensure you workflow and development don’t breach PCI DSS compliance if you plan to process credit cards. Saasu isn’t responsible for what you do with this open source code as we have no control over it’s use.

Activating API Access for Your File

You will need a web service access key (WSAccessKey) and file id (FileUid) to access your file through the Web Service API. If you aren’t an admin person for your file you will need to request your admin person to give you access. We have made WSAccessKey’s specific to each user for security reasons. Business owners need accountability and compliance that ensures all API access can be pin-pointed to a specific API user access.

Enable API access for a user to a specific file

1. Sign in to the File you are setting up access to.
2. Go to Settings > Web Services.
3. Tick Turn on web services access for this file and click save.
4. The API credentials will be revealed after you click the save button.

Create a specific API user for API transactions

1. While signed into your Saasu file, click on My Saasu in the top menu.
2. If you don’t automatically go into the Manage Subscription Screen then click on the Manage Subscription link that relates to where you file resides
3. Pick an existing user as an API user for your file or create a separate user account (recommended).
4. Click on the user you want to give an API access key to.
5. In this Edit User screen tick the check box “This user has permission to connect via web services key”.
6. Click save to reveal the user specific API key.
7. Click close to go back to Manage Subscription screen.
8. Click on the file that you want to be made accessible via web service.
9. In this Edit File screen, tick the check box Allow access to this File via web services and permission the API user to access this file by giving it an appropriate access level.
10. Click Save to reveal the file id.

Enable a File for API access

1. Go into My Saasu screen by clicking on My Saasu link on the top right.
2. Click on the Subscription Name(folder icon) to go into Manage Subscription screen
3. Click on the edit icon(pencil) adjacent to the file name in the list of files.
4. When you are in Edit File screen, tick the check box “Allow access to this File via web services”, and click on Save. The Id of the file will now appear adjacent to the check box.

Find a Web Services Access Key for a user

1. Go into My Saasu screen by clicking on My Saasu link on the top right.
2. Click on the Subscription Name(folder icon) to go into Manage Subscription screen.
3. Click on the edit icon(pencil) adjacent to the name of the user in the list of users.
4. When you are in Edit User screen, tick the check box This user has permission to connect via web services key, and click on Save. This will generate and display your WS Access Key adjacent to the check box.

Web Services URLs

https://secure.saasu.com/webservices/rest/r1/Tasks?wsaccesskey={WSAccessKey}&FileUid={FileUid}

HTTP POST Examples

Data processing requests are submitted through HTTP POST request to Tasks resource. Multiple tasks can be submitted at once. The following example illustrates submitting three tasks in a single request:

• Task #1: update contact (updateContact).
• Task #2: insert a service sale with quick payment (insertInvoice).
• Task #3: insert an unpaid item sale (insertInvoice).

Sample request data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

<?xml version="1.0" encoding="utf-8"?>
<tasks>
  <updateContact>
    <contact uid="23985" lastUpdatedUid="AD3872E=">
      <salutation>Mrs.</salutation>
      <givenName>Mary</givenName>
      <familyName>Smith</familyName>
      <organisationName>ACME Pty Ltd</organisationName>
      <organisataionAbn>11 111 111 111</organisationAbn>
      <contactID>223</contactID>
      <organisationWebsite>www.acme.com</organisationWebsite>
      <mobilePhone>0666 666 666</mobilePhone>
      <homePhone> 02 8888 8888</homePhone>
      <tags>Prospect, IT</tags>
      <postalAddress>
        <street>11/111 ABC Av</street>
        <city>Sydney</city>
        <state>NSW</state>
      </postalAddress>
      <otherAddress/>
      <isActive>true</isActive>
   </contact>
 </updateContact>
<insertInvoice emailToContact="false">
  <invoice uid="0">
    <transactionType>S</transactionType>
    <date>2005-09-30</date>
    <contactUid>23986</contactUid>
    <tags>Online Sales, XYZ</tags>
    <summary>Test POST sale</summary>
    <notes>From REST</notes>
    <requiresFollowUp>false</requiresFollowUp>
    <dueOrExpiryDate>2005-12-01</dueOrExpiryDate>
    <layout>S</layout>
    <status>I</status>
    <invoiceNumber><Auto Number></invoiceNumber>
    <purchaseOrderNumber>PO222</purchaseOrderNumber>
    <invoiceItems>
      <serviceInvoiceItem>
        <description>Design and Development of REST WS</description>
        <accountUid>24502</accountUid>
        <taxCode>G1</taxCode>
        <totalAmountInclTax>2132.51</totalAmountInclTax>
      </serviceInvoiceItem>
      <serviceInvoiceItem>
        <description>Subscription to XYZ</description>
        <accountUid>24504</accountUid>
        <taxCode>G1</taxCode>
        <totalAmountInclTax>11.22</totalAmountInclTax>
      </serviceInvoiceItem>
    </invoiceItems>
    <quickPayment>
      <datePaid>2005-09-30</datePaid>
      <dateCleared />0001-01-01</dateCleared>
      <bankedToAccountUid>24509</bankedToAccountUid>
      <amount>100</amount>
      <reference>CASH</reference>
      <summary>Quick payment from Westpac.</summary>
    </quickPayment>
    <isSent>false</isSent>
  </invoice>
</insertInvoice>
<insertInvoice emailToContact="true">
  <invoice uid="0">
    <transactionType>S</transactionType>
    <date>2005-10-06</date>
    <contactUid>23987</contactUid>
    <tags>Online Sales, ABC123</tags>
    <summary>Test Insert Item Sale</summary>
    <notes>From REST</notes>
    <requiresFollowUp>false</requiresFollowUp>
    <dueOrExpiryDate>2005-11-06</dueOrExpiryDate>
    <layout>I</layout>
    <status>I</status>
    <invoiceNumber><Auto Number></invoiceNumber>
    <purchaseOrderNumber>PO333</purchaseOrderNumber>
    <invoiceItems>
      <itemInvoiceItem>
        <quantity>2</quantity>
        <inventoryItemUid>4822</inventoryItemUid>
        <description>Seagate HDD - 300G</description>
        <taxCode>G1</taxCode>
        <unitPriceInclTax>120.75</unitPriceInclTax>
      </itemInvoiceItem>
      <itemInvoiceItem>
        <quantity>5.125</quantity>
        <inventoryItemUid>4821</inventoryItemUid>
        <description>Cat 5 Cable (in meter)</description>
        <taxCode>G1</taxCode>
        <unitPriceInclTax>2.555</unitPriceInclTax>
        </itemInvoiceItem>
      </invoiceItems>
      <quickPayment>
        <datePaid>0001-01-01</datePaid>
        <dateCleared>0001-01-01</dateCleared>
        <bankedToAccountUid>0</bankedToAccountUid>
        <amount>0</amount>
      </quickPayment>
      <isSent>false</isSent>
    </invoice>
    <createAsAdjustmentNote>false</createAsAdjustmentNote>
    <emailMessage>
      <from>test@acme.com.au</from>
      <to>smith@acme.com.au</to>
      <subject>Invoice</subject>
      <body>Thanks for shopping with us. Attached is a PDF invoice for your record.</body>
    </emailMessage>
  </insertInvoice>
</tasks>

Sample Response (Success):

1
2
3
4
5
6

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse>
    <updateContactResult updatedEntityUid="23985" LastUpdatedUid="1AB72C=" />
    <insertInvoiceResult insertedEntityUid="253490" LastUpdatedUid="90DFDA=" sentToContact="false" generatedInvoiceNumber="A0101"  />
    <insertInvoiceResult insertedEntityUid="253492" LastUpdatedUid="379A9ACD=" sentToContact="true" />
  </tasksResponse>

Sample Response (Error in executing a task):

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse> 
    <updateContactResult updatedEntityUid="24001" LastUpdatedUid="A37CA998" />
    <insertInvoiceResult sentToContact="false">
      <errors>
        <error>
          <type>InvalidReferenceException</type>
          <message>The referenced Contact does not exist.</message>
        </error>
      </errors>
    </insertInvoiceResult><br />
    <insertInvoiceResult insertedEntityUid="253501" LastUpdatedUid="78273DA=" sentToContact="true" />
  </tasksResponse>

Sample Response (Error – invalid task submitted or the XML submitted does not conform to schema):

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
  <tasksResponse>
    <errors>
      <error>
        <type>SchemaValidationException</type>
        <message>The element "tasks" has invalid content. An error occurred at , (3, 4).</message>
      </error>
    </errors>
  </tasksResponse>

HTTP GET Examples

The following is an example of retrieving a purchase order with uid 253502. Sample request URI:

https://secure.saasu.com/webservices/rest/r1/Invoice?wsaccesskey=TEST-888-888&FileUid=888&uid=253502

Sample return (No errors):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<?xml version="1.0" encoding="utf-8"?>
  <invoiceResponse>
    <invoice uid="253502">
      <transactionType>P</transactionType>
      <date>2005-11-24</date>
      <contactUid>24012</contactUid>
      <summary>Test POST Purchase</summary>
      <notes>From REST</notes>
      <requiresFollowUp>false</requiresFollowUp>
      <dueOrExpiryDate>2005-12-24</dueOrExpiryDate>
      <status>O</status>
      <invoiceNumber />
      <purchaseOrderNumber><Auto Number></purchaseOrderNumber>
      <invoiceItems>
        <serviceInvoiceItem>
          <description>Purchase - Line Item 1</description>
          <accountUid>24662</accountUid>
          <taxCode>G11</taxCode>
          <totalAmountInclTax>123.4500</totalAmountInclTax>
        </serviceInvoiceItem>
        <serviceInvoiceItem>
          <description>Purchase - Line Item 2</description>
          <accountUid>24664</accountUid>
          <taxCode>G11,G15</taxCode>
          <totalAmountInclTax>678.9000</totalAmountInclTax>
        </serviceInvoiceItem>
      </invoiceItems>
      <isSent>false</isSent>
    </invoice>
  </invoiceResponse>

Sample return (with errors):

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8"?>
  <invoiceResponse>
    <errors>
      <error>
         <type>RecordNotFoundException</type>
         <message>The requested Invoice is not found.</message>
      </error>
    </errors>
  </invoiceResponse >

HTTP DELETE Examples

For deleting an entity. The following sample illustrates deleting an invoice given the invoice uid. Sample request URI:

https://secure.saasu.com/webservices/rest/r1/Invoice?wsaccesskey=TEST-888-888&FileUid=888&uid=251362

Sample return (No errors):

1
2
3
4

<?xml version="1.0" encoding="utf-8">
  <invoiceResponse>
    <deleteResult uid="251362" />
  </invoiceResponse>

List of entities versus a single entity
Requests to “GET List” instead of “GET ” will result in a List of entities instead of a single Entity being returned.
Example: To retrieve a single contact, the query should be sent to:

https://…/webservices/rest/r1/Contact?wsaccesskey={YourWSAccessKey}&fileuid={YourFileUid}&uid={ContactUid}

Note that it’s “Contact” not “ContactList”. To retrieve a list of contacts matching certain criteria, make a GET request to ContactList, passing the supported criteria through query string.

If you are using our .NET RestClient Wrapper to make the call, you need to use the “GetByUid” method instead of the “Find” method.
To retrieve a single contact:
CrudProxy proxy = new ContactProxy();
ContactDto jim = (ContactDto) proxy.GetByUid(99999);

Terminology

• API: Application Programming Interface.
• CRUD: Create, read, update, and delete operations.
• DTO: Data Transfer Object
• Entity: Refers to things such as Contact, Account, Bank Account, etc.
• OLA: Stands for Online Accounting. Used throughout the document to refer to Saasu Online Accounting system.
• REST: Representational State Transfer.
• Transaction: More specialised form of entity. E.g. Invoice, InvoicePayment, Bank Transfer, Inventory Adjustment.
• UID: Unique Identifier.
• WS: Web Service.
• WSAccessKey: Web Service Access Key, which is required to access Saasu Web Services.
• WSAPI: Web Services Application Programming Interface.