Introduction
This document’s purpose is to outline the web services available for Managed Service Providers and Suppliers to integrate their workflows with the Claritum System.
Terminology
Throughout this document the term ‘server’ is used to describe the system providing a web service and the term ‘client’ is used to describe the system connecting to a web service.
Both terms can apply to either the Claritum System or the external server.
Methodology
All web services will be implemented as XML over HTTPS. The public interface is SOAP 1.1. compliant with WSDL.
Conventions
- All simple data type names and service names are camel-case (e.g. ‘myVariableName’). Complex data type names are camel-case but always begin with upper-case (e.g. ‘Customer’)
- All services should try to handle multiple records wherever possible and allow for updating existing as well as creating new (e.g. ‘setCustomers’ should allow the client to create 10 new customer records and update 450 customer records with only one call). They should also be named using the plural term.
- All services should present consistent properties in the same place.
- All dates handled by the Claritum System’s services will be in UTC format.
Versions
When incompatible changes are made to the API Claritum will release a new version of the service. The most recent version is currently 1.3. You can tell the version you are accessing by examining the endpoint URL - for example, this URL shows that you are using version 1.3 of the web service.
https://yourserver.claritum.com/system/ws/1.3/soap.php?wsdl
Claritum continue to support older versions of the web services for six months after a new version is released. Non-breaking changes, such as adding elements to data types, may not result in the new version.
Web Services Reference
...
Not all of these services are available to Service Providers and Suppliers alike; indicators show on each one as appropriate.
getAttachments
| Status | ||
|---|---|---|
|
| Status | ||||
|---|---|---|---|---|
|
...
Once you have called getPurchaseOrders to retrieve a list of production orders, each order contains a reference you can use to download file attachments accompanying the order.
getDeliveries
Status colour Green title msp Status colour Green title supplier
Returns an array of deliveries for jobs that are in progress and that have not been marked as exported. Once your system has processed the deliveries, call the markExported service with the UIDs of the items processed to prevent the same deliveries being returned in future calls.
getPurchaseInvoices
Status colour Green title msp Status colour Green title supplier
Returns an array of received supplier invoices that have not been marked as exported. Once your system has processed the invoices, call the markExported service with the UIDs of the items processed to prevent the same invoices being returned in future calls.
getPurchaseOrders
Status title msp Status colour Green title supplier
Returns an array authorised purchase orders that have not been marked exported. Once your system has processed the purchase orders, call the markExported service with the UIDs of the items processed to prevent the same POs being returned in future calls.
getSalesInvoices
Status colour Green title msp Status title supplier
Returns an array of issued customer invoices that have not been marked as exported.
Once your system has processed the invoices, call the markExported service with the UIDs of the items processed to prevent the same invoices being returned in future calls.
getSpecification
Status title msp Status colour Green title supplier
Once a set of purchase orders have been retrieved from the system, this service can be called to retrieve the detailed specification for each order.
getStockOrders
Status title msp Status colour Green title supplier
Returns a list of pending stock (fulfilment) orders pending for the supplier.
Once your system has processed the invoices, call the markExported service with the UIDs of the items processed to prevent the same invoices being returned in future calls.
markExported
Status colour Green title msp Status colour Green title supplier
...
Until an object has been marked exported it will continue to appear in the associated get[Type] operation. Call this method when the remote system has successfully processed the objects.
setCustomers
Status colour Green title msp Status title supplier
Creates/Updates customer records on the Claritum System. If any of the records cannot be processed for any reason then an error is returned.
setGoodsReceipts
Status colour Green title msp Status colour Green title supplier
Creates goods receipts on the Claritum System.
Note: the inbound goods receipts will contain the Claritum order reference with which the Claritum System will use to locate the order relating to these goods receipts. If there are multiple delivery addresses then the receipt quantity will be allocated across all of the delivery addresses. If a partial quantity is received then this will mean that latter delivery addresses will see no goods receipts until a balancing goods receipt is received.
setStockOrderStatus
Status title msp Status colour Green title supplier
Sets the 'despatched' status on the given orders.
setSuppliers
Status colour Green title msp Status title supplier
Creates/Updates supplier records on the Claritum System. If any of the records cannot be processed for any reason then an error is returned.
References
| W3C SOAP 1.1 Definition: | http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
| W3C SOAP 1.2 Definition: | http://www.w3.org/TR/soap12-part1 |
| WSDL Definition: | http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
| XML Schemas Data Types: | http://www.w3.org/TR/xmlschema-2/ |