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.4. 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.

Full documentation on the datatype properties for each service can be found be checking the service end point on your system. For instance, if you normally access the system via the URL https://yoursystem.claritum.com, you can view the documented services via the URL:

https://yoursystem.claritum.com/system/ws/1.4/soap.php

Not all of these services are available to Service Providers and Suppliers alike; indicators show on each one as appropriate.

getAttachments

MSP SUPPLIER

Returns attachments for a given part. 

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

MSP 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.

getPaperSpecification

MSP SUPPLIER

Once a set of purchase orders have been retrieved from the system, this service can be called to retrieve the detailed paper specification for each order.

getPaperSpecification

MSP SUPPLIER

Once a set of purchase orders have been retrieved from the system, this service can be called to retrieve the detailed paper specifications for each order.

getPurchaseInvoices

MSP 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

MSP 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

MSP 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

MSP 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.

getSpecifications

MSP SUPPLIER

Once a set of purchase orders have been retrieved from the system, this service can be called to retrieve the detailed specifications for each order.

getStockDespatches

MSP SUPPLIER

Returns a list of pending stock (fulfilment) orders awaiting packing by the supplier.
Once your system has processed the records, call the markExported service with the UIDs of the items processed to prevent the same records being returned in future calls. 

getStockOrders

MSP SUPPLIER

Returns a list of pending stock (fulfilment) orders pending for the supplier.
Once your system has retrieved these records, call the markExported service with the UIDs of the items processed to prevent the same records being returned in future calls. 

markExported

MSP SUPPLIER

Marks objects of given type as exported. The 'Type' parameter should match the name of the service called to get the results - for example 'Delivery', 'PurchaseInvoice', 'PurchaseOrder', 'SalesInvoice', 'StockDespatch', etc.

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.

markFailed

MSP SUPPLIER

When processing the retrieved records, if any of them fail your validation for any reason you can use this service to mark the records as FAILED. This causes Claritum to raise an alert with the account managers who can then resolve the issue.

The 'Type' parameter should match the name of the service called to get the results - for example 'Delivery', 'PurchaseInvoice', 'PurchaseOrder', 'SalesInvoice', 'StockDespatch', etc.

Until the object has been marked exported it will continue to appear in the associated get[Type] operation.

setCustomers

MSP SUPPLIER