TWD Inventory System - Developer API Reference
To set up the Developer API for use
- Log in as an admin, and go to settings.
- Set a unique API access key which your program will use to be granted access to the API
The Developer API allows the use of standard HTTP protocols to retrieve and store data. The API always returns a response in XML format.
Some notes to consider:
- All requests to the API must be made via HTTPS!
- You may send your requests as either GET or POST requests.
- Your api key must be sent with each request made to the API as a key/value pair.
- Each key/value pair sent to the API must be URL Encoded
To get inventory listings.
To get the first 50 Active results, only send your apikey to the API
Note: the <totalcount> tag is a count of whatever status you queried for.
Default status if none supplied is 'A' (Active)
https://my.server.com/pathtoapi/api.pl?apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>OK</statusmessage>
<totalcount>308</totalcount>
<totalstatus>A</totalstatus>
<item>
<stock_no>1423</stock_no>
<status>A</status>
<deptcode>FURN</deptcode>
<dept>Furnature</dept>
<brand>Ashley</brand>
<description>Desk, 9 Drawers</description>
<price>40</price>
</item>
... (will return multiple item sections)
</result>
To get the next 50 Active results, send a 'page' key/value pair.
https://my.server.com/pathtoapi/api.pl?page=2&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>OK</statusmessage>
<totalcount>308</totalcount>
<totalstatus>A</totalstatus>
<item>
<stock_no>884</stock_no>
<status>A</status>
<deptcode>FURN</deptcode>
<dept>Furnature</dept>
<brand>Lazyboy</brand>
<description>Love Seat, W/ Ottoman</description>
<qty>1</qty>
<price>60</price>
</item>
... (will return multiple item sections)
</result>
To get first 50 Held results, send a 'status=H' key/value pair.
https://my.server.com/pathtoapi/api.pl?status=H&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>OK</statusmessage>
<totalcount>9</totalcount>
<totalstatus>H</totalstatus>
<item>
<stock_no>1017</stock_no>
<status>H</status>
<deptcode>FURN</deptcode>
<dept>Furnature</dept>
<brand></brand>
<description>End Table, Dark Brown</description>
<qty>1</qty>
<price>10</price>
</item>
... (will return multiple item tags)
</result>
To search inventory listings.
To perform a search query, send a 'q=query' key/value pair. Be sure to URL-encode your query.
Example search query for a "Love Seat"
Specific queries still return a <totalcount> tag with a total of which status is queried for
https://my.server.com/pathtoapi/api.pl?q=Love+Seat&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>OK</statusmessage>
<totalcount>308</totalcount>
<totalstatus>A</totalstatus>
<item>
<stock_no>868</stock_no>
<status>A</status>
<deptcode>FURN</deptcode>
<dept>Furnature</dept>
<brand>Lazyboy</brand>
<description>Love Seat, Hide-a-bed</description>
<qty>1</qty>
<price>40</price>
</item>
... (will return multiple item sections)
</result>
To get a specific inventory item.
Example to retrieve stock no '1015'.
https://my.server.com/pathtoapi/api.pl?stock_no=1015&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>OK</statusmessage>
<item>
<stock_no>1015</stock_no>
<status>A</status>
<deptcode>BEDS</deptcode>
<dept>Beds</dept>
<brand>Serta</brand>
<description>Captains Bed, White</description>
<qty>1</qty>
<price>50</price>
</item>
</result>
To update a specific inventory item.
To update a specific inventory item, send any number of key/value pairs for field(s) you wish to update. Also send an 'action' key/value pair of "action=update" and a
"stock_no=[stock_no]" key/value pair to identify which item to update.
Example to set stock no 1015 to Sold status
https://my.server.com/pathtoapi/api.pl?stock_no=1015&action=update&status=S&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>UPDATE OK</statusmessage>
</result>
Example to set status for stock no 1015 to Held and set a note. Note says "Held for Greg Smith"
https://my.server.com/pathtoapi/api.pl?stock_no=1015&action=update&status=H¬es=Held+for+Greg+Smith&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>UPDATE OK</statusmessage>
</result>
Example to adjust inventory when an item is sold. This example reduces the qty count by 1
https://my.server.com/pathtoapi/api.pl?stock_no=1015&action=update&qtyadj=1&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>UPDATE OK</statusmessage>
</result>
Full table of keys that can be used to send updates
| status | Sets the item status. Valid codes are: A (Active), H (Held), P (Paid), S (Sold), O (Ordered), X (Deleted)
(Addons can define their own status codes as well.) |
| dept | Sets the department code |
| brand | Sets the brand field |
| description | Sets the item description |
| qty | Sets the item qty |
| qtyadj | Removes the specified qty from the current qty |
| price | Sets the item price |
| notes | Sets the item private notes |
To delete a specific inventory item.
To delete an item, set it's status code to 'X'. Example to delete stock no 1015
https://my.server.com/pathtoapi/api.pl?stock_no=1015&action=update&status=X&apikey=yourapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>1</statuscode>
<statusmessage>UPDATE OK</statusmessage>
</result>
Error handling.
When the API encounters an error, the API will return a <statuscode> of '0'
The <statusmessage> tag will give information as to the cause of the error.
Example error output for invalid API key
https://my.server.com/pathtoapi/api.pl?stock_no=1015&apikey=anotherapikey
Sample Result:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<statuscode>0</statuscode>
<statusmessage>The supplied API key is not valid!</statusmessage>
</result>
