RESTful APIs – V6 Invoices

RESTful APIs - V6 Invoices

This document is to provide an instruction to access v6 Invoice APIs

The following are available APIs interfaces. Customers will be provided with an API key in order to access the APIs; also, each API key is associated with a valid v6 CUSTOMER_SERVICE or CUSTOMER-ROLE user.

Retrieve invoice by date range

Description

This API interface can be used to retrieve invoices created within a date range in v6.

Protocol

URL: 

{domain_name}/v6-api/rest/invoices?fromDate=ddMMyyyy&toDate=ddMMyyyy

Method: GET

Authentication Api Key, embedded in the request header. In details, the request header must contain a key value pair for the authorization; in which the key should be "Authorization" and value is "ApiKey {provided-api-key}" for example "ApiKey rGzwXXurMoOd9ooSrOZ4UO2izAXHfzVU"

Jason request response in order to get all invoices within a date range, users need to submit the required parameters which are fromDate and toDate; missing one of the 2 fields will result in Bad Request response (http code: 400)

JSON Response:

The response will be returned in JSON format. The following are the list of some common responses. Please note that some information of invoices may not be available (have no data), and they will not be in the JSON response. For all fields which potentially returned in JSON response please see appendix A.

Successful request will return list of invoices within the given data range, for example:

[
   {
   "businessName": "OMNIX PTY LTD",
   "invoiceDate": "2018-01-24",
   "taxAmount": 0.91,
   "fileType": "I",
   "customerCode": "001",
   "address1": "80 JEPHSON STREET",
   "lines": [

     {
          "amount": 10, "price": 10,
          "gstAmount": 0.91,
          "quantity": 1,
          "departmentCode": "BRI",
          "glCode": "23", 
   }
   ],

   "postcode": "4006",
   "invoiceNo": "LT001",
   "grossEntry": true,
   "city": "TOOWONG",
   },
{

   "businessName": "OMNIX PTY LTD",
   "invoiceDate": "2018-01-25",
   "taxAmount": 1.82,
   "fileType": "I",
   "customerCode": "001",
   "address1": "80 JEPHSON STREET",
   "lines": [
      {
           "amount": 20, 
           "price": 20,
           "gstAmount": 1.82,
           "quantity": 1,
           "departmentCode": "BRI", 
           "glCode": "23",
     }
 ], 
    "postcode": "4006", 
    "invoiceNo": "LT002", 
    "grossEntry": true,
    "city": "TOOWONG" 
    }
]

Authentication problem: no API key found in the "Authorization" in request header, or wrong API key. This may provide different warning messages.

{
   "httpStatusCode": 401,, "msg": "Unauthorised: Cannot find API key in the header or the API key is not correct. Make sure the API key is embedded in the request header, under Authorization property. E.x. Authorization: apikey provided-API-key
}

{
   "httpStatusCode": 401, "msg": "Invalid API Key,
}

Violating data constraints

There are some constraints that submitted data must follow, for example, some malformed data error but not all:

  • Missing required fields,
  • Unrecognized fields,
  • String value exceed maximum length or shorter than maximum length,
  • Number is smaller than maximum value larger than maximum value
  • and some other logical constraints (e.g. pick up date must be before delivery date)

All the requests breaking these rules will result in Breaking Request (400). The corresponding responses will also contain intuitive error messages informing which fields do not follow which rule. To see rules, please see appendix A.

The format of bad request response should look like the following JSON

{
     "httpStatusCode": 400, "msg": "Bad Request", "violations": {
     //a list of violations [ {fileName} - {error} - {suggestions}. ... ]
}

Example of Bad Request response:

{
     "violations": [ "fromDate - required field - must exist and must not be empty", "fromDate, toDate - invalid date range - fromDate data has to be before toDate", "toDate - required 
     field - must exist and must not be empty", ], "httpStatusCode": 400, "msg": "Bad Request",
}

Appendix A: All fields that are potentially returned when querying invoices by date range

JSON supported fields     Content Data-Type Constraints Notes
businessName     string    
invoiceDate     string   Format: dd-MM-yyyy, e.g. 23-01-2018
dueDate     string   Format: dd-MM-yyyy, e.g. 24-01-2018
taxAmount     Number    
fileType     string   One of the following 3 values: C, D, I

  • C for Credit Memo
  • D for Debit Memo
  • I for Invoice
customerCode     string   V6 customer code
address1     string    
postcode     string    
grossEntry     boolean    
city     string    
creditReason     Object    
  creditReasonCode   string   Credit reason v6 code
  description   string   Description of the credit reason
lines     array    
  amount   Number    
  price   Number    
  gstAmount   Number    
  quantity   Number    
  departmentCode   Number    
  glCode   Number