Document Header - Create, Read & Update

Document Header API Requests

The “www.” subdomain prefix can included and excluded from the URL used for the API Request. Examples below:

https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details
https://aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details

Try excluding “www.” from the URL if your API request fails to pull data.

Create document

The following endpoint URL style is used:

https://{server}/{instance name}/wsapi/2.5/Documents/{summary view}/{details view}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details

Create document - API Request

XML

PUT https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details

Content-Type: application/xml

Body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <company name="REST Demo"/>
  <entity>
    <returnattribute name="Document Reference"/>
    <attribute name="Customer Code">MIC001</attribute>
    <attribute name="Document Date">01 Jul 2016</attribute>
    <attribute name="Due Date">15 Jul 2016</attribute>
  </entity>
  <subordinates>
    <returnattribute name="VAT Amount"/>
    <entity>
      <returnattribute name="Gross"/>
      <attribute name="Description">Inspect Googling Hatch</attribute>
      <attribute name="Units">Each</attribute>
      <attribute name="Qty">4</attribute>
      <attribute name="Unit Price">200</attribute>
      <attribute name="VAT Rate">Standard</attribute>
      <attribute name="Account">P2110</attribute>
    </entity>
    <entity>
      <returnattribute name="Gross"/>
      <attribute name="Description">Moisten Globule</attribute>
      <attribute name="Units">Each</attribute>
      <attribute name="Qty">12</attribute>
      <attribute name="Unit Price">55</attribute>
      <attribute name="VAT Rate">Standard</attribute>
      <attribute name="Account">P2110</attribute>
    </entity>
  </subordinates>
</dataentry>

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
    <entity sguid="8aBYZqDV5lSMXP6vjJCbAR25ME">
        <returnattribute ubk="1" name="Document Reference">INV_S000027</returnattribute>
        <attachments/>
    </entity>
    <subordinates>
        <entity sguid="MkPAkkzlI39oxwzniZD0D81AjY" id="1" sequence="1">
            <returnattribute name="VAT Amount">160.00</returnattribute>
            <returnattribute name="Gross">960.00</returnattribute>
            <attachments/>
        </entity>
        <entity sguid="E5OBY3BF7ErvBRlHpvJl6zDqr8" id="2" sequence="2">
            <returnattribute name="VAT Amount">132.00</returnattribute>
            <returnattribute name="Gross">792.00</returnattribute>
            <attachments/>
        </entity>
    </subordinates>
</dataentry>

Create document line

See: Create Document Line

Attach file to document header or line

See: Attachments

Read Document

Document Endpoints and URLs.

https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/DocumentType

An entity can be retrieved by stating its PUBK as the last element of the URL thus:

https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000025

An entity can be retrieved using its GUID thus:

https://www.aqilla.net/ InstanceName/wsapi/2.5/n3xv1A4d2VTXbM6rX7uLAXZrd6

Documents can be read from summary views - e.g. Sales Invoice (Services) - or detail views - e.g. Sales Invoice (Services) - Details.

API Request

Summary Views

XML

GET https://www.aqilla.net/InstancecName/wsapi/2.5/Documents/Sales Invoices (Services)

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataretrieval totalPages="1" pageSize="1000" page="1" callTimestamp="20160920151222688">
    <entities>
        <entity>
            <returnattribute ubk="1" name="Document Reference">INV_S000026</returnattribute>
            <returnattribute name="Document Date">20 Sep 2016</returnattribute>
            <returnattribute name="Customer Name">Merrill Page</returnattribute>
            <returnattribute name="Gross Value">565.20</returnattribute>
            <attachments/>
        </entity>
        <entity>
            <returnattribute ubk="1" name="Document Reference">INV_S000025</returnattribute>
            <returnattribute name="Document Date">20 Sep 2016</returnattribute>
            <returnattribute name="Customer Name">Micro Stone</returnattribute>
            <returnattribute name="Gross Value">350.68</returnattribute>
            <attachments/>
        </entity>
    </entities>
</dataretrieval>

The URL in this case can be qualified using:

page
pageSize

thus:

https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)?pageSize=1&Page=2

Read document - Detailed view

API Request

XML

GET https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S00002

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
    <entity sguid="n3xv1A4d2VTXbM6rX7uLAXZrd6">
        <returnattribute ubk="1" name="Invoice Reference">INV_S000025</returnattribute>
        <returnattribute name="Customer Code">MIC001</returnattribute>
        <returnattribute name="Customer Name">Micro Stone</returnattribute>
        <returnattribute name="Document Date">20 Sep 2016</returnattribute>
        <returnattribute name="Address Line 1">67 Great Eastern Street</returnattribute>
        <returnattribute name="Due Date">20 Oct 2016</returnattribute>
        <returnattribute name="Currency">GBP</returnattribute>
        <returnattribute name="Address Line 2">London</returnattribute>
        <returnattribute name="Gross Value">350.68</returnattribute>
        <returnattribute name="Rate">1.00</returnattribute>
        <returnattribute name="Currency Value">350.68</returnattribute>
        <returnattribute name="Post Code">EC2A 3HZ</returnattribute>
        <returnattribute name="Memorised">Not Memorised</returnattribute>
        <returnattribute name="Standard Text">Default text</returnattribute>
        <attachments/>
    </entity>
    <subordinates>
        <entity sguid="QVpqGLYBIw2JjEwaTaE8ERwOrl" id="1" sequence="1">
            <returnattribute name="Description">Thing</returnattribute>
            <returnattribute name="Units">Each</returnattribute>
            <returnattribute name="Qty">1.00</returnattribute>
            <returnattribute name="Unit Price">78.99</returnattribute>
            <returnattribute name="Net Price">78.99</returnattribute>
            <returnattribute name="VAT Rate">Standard</returnattribute>
            <returnattribute name="VAT Amount">15.80</returnattribute>
            <returnattribute name="Gross">94.79</returnattribute>
            <returnattribute name="Base Gross">94.79</returnattribute>
            <returnattribute name="Account">P1100(Direct Sales)</returnattribute>
            <attachments/>
        </entity>
        <entity sguid="rxKjr1lhwjbV5w7TNeG6MrbKBo" id="2" sequence="2">
            <returnattribute name="Description">Another Thing</returnattribute>
            <returnattribute name="Units">Each</returnattribute>
            <returnattribute name="Qty">12.00</returnattribute>
            <returnattribute name="Unit Price">17.77</returnattribute>
            <returnattribute name="Net Price">213.24</returnattribute>
            <returnattribute name="VAT Rate">Standard</returnattribute>
            <returnattribute name="VAT Amount">42.65</returnattribute>
            <returnattribute name="Gross">255.89</returnattribute>
            <returnattribute name="Base Gross">255.89</returnattribute>
            <returnattribute name="Account">P1100(Direct Sales)</returnattribute>
            <attachments/>
        </entity>
    </subordinates>
</dataentry>

Errors

The 404 Not Found error is returned if the requested entity is not found or the client lacks permissions to access it.

The 409 Conflict error is returned if more than one entity exists with the given PUBK.

Update Document

The following documents cannot be updated using the Aqilla API:

Payroll
Prepayment
Purchase Invoice Matching
Timesheets (Monthly)

The following endpoint URL styles are used:

https://{server}/{instance name}/wsapi/2.5/Documents/{summary view}/{details view}/{UBK}
e.g. https://www.aqilla.net/ InstanceName /wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000026
https://{server}/{instance name}/wsapi/2.5/{GUID}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/nkjsn88768gjx8733d

Update document - example

API REQUEST

XML

POST https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000027
Content-Type: application/xml

Body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <entity>
    <returnattribute name="Document Reference"/>
    <attribute name="Document Date">29 Sep 2016</attribute>
    <attribute name="Due Date">31 Oct 2016</attribute>
  </entity>
</dataentry>

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <entity sguid="8aBYZqDV5lSMXP6vjJCbAR25ME">
    <returnattribute ubk="1" name="Document Reference">INV_S000027</returnattribute>
    <attachments/>
  </entity>
</dataentry>

Update document line

See Update Document Line

Promote Document

The following endpoint URL styles are used:

https://{server}/{instance name}/wsapi/2.5/Documents/{summary view}/{details view}/{UBK}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000025
https://{server}/{instance name}/wsapi/2.5/{GUID}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/nkjsn88768gjx8733d

Only a directly referenceable entity - i.e. one that can be addressed by a UBK or GUID - can be promoted.

Standard Aqilla promotion rules apply - e.g. you can't reject a document that has been posted

Entities are promoted by sending a POST request to a URL uniquely identifying the entity. If is is a container entity, subordinate entities are also promoted.

Promote document - example

API Request

XML

POST https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000025
Content-Type: application/xml

Body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <entity>
    <transitionchain>
      <transition name="Post">
        <param name="Period" value="Sep-15"/>
      </transition>
    </transitionchain>
    <returnattribute name="Document Date"/>
  </entity>
</dataentry>

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
    <entity sguid="n3xv1A4d2VTXbM6rX7uLAXZrd6">
        <returnattribute name="Document Date">20 Sep 2016</returnattribute>
        <attachments/>
    </entity>
</dataentry>

Promote document line

The following endpoint URL styles are used:

https://{server}/{instance name}/wsapi/2.5/Documents/{summary view}/{details view}/sub/{line number}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Expenses/Expenses - Details/EXP000001/sub/3
https://{server}/{instance name}/wsapi/2.5/{GUID}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/8sggg986s6787g786sts33ds/sub

The line number may not be obvious to you. If you enter two lines and delete them both the next line will be line 3. It's always safest to use GUID's.

Entities are promoted by sending a POST request to a URL uniquely identifying the entity.

Promote document line - example

API Request

CODE

POST https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Expenses/Expenses - Details/EXP000001/sub/3
Content-Type: application/xml

body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <entity>
    <transitionchain>
      <transition name="Reject">
      </transition>
    </transitionchain>
    <returnattribute name="Expense Date"/>
    <returnattribute name="Expense Type"/>
  </entity>
</dataentry>

Response

XML

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <entity sguid="wnqz4mlhr7jb5lrHNVdp410Alb" id="3" sequence="3">
    <returnattribute name="Expense Date">16 Dec 2013</returnattribute>
    <returnattribute name="Expense Type">Travel</returnattribute>
    <attachments/>
  </entity>
</dataentry>

Delete Document

The following endpoint URL styles are used:

https://{server}/{instance name}/wsapi/2.5/Documents/{summary view}/{details view}/{UBK}
e.g. https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000026
https://{server}/{instance name}/wsapi/2.5/{GUID}
e.g. https://www.aqilla.net/ InstanceName /wsapi/2.5/nkjsn88768gjx8733d

Entities are deleted by sending a DELETE request to a URL uniquely identifying the entity. If is is a container entity, subordinate entities are also deleted.

Only a directly referenceable entity - i.e. one that can be addressed by a UBK or GUID - can be deleted. Deletion of subordinate entities (such as document lines) is considered modification of their parent entity and this may be introduced in a future version. Contact your Aqilla consultant or account manager if you think you need this.

Standard Aqilla deletion rules apply - e.g. you can't delete a document that has been posted.

Entities are deleted by sending a DELETE request to a URL uniquely identifying the entity. If is is a container entity, subordinate entities are also deleted. Attachments are deleted together with the entities they were attached to.

If the entity was found and successfully deleted, 204 No Content is returned with no body. If the entity was found but could not be deleted (typically because of it being read only or the user lacking the necessary permissions) 409 Conflict is returned. If the entity was not found 404 Not Found is returned. In the two last cases the encoding of the response body is application/xml.

Delete document - example

API Request

XML

DELETE https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Sales Invoices (Services)/Sales Invoice (Services) - Details/INV_S000026

Response

XML

204 No Content

Delete document line

See: Delete Document Line