Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.
Errors are returned via the standard SOAP Fault element with the ‘faultcode’, ‘faultstring’, and ‘faultactor’ sub elements as defined by the standard.


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

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.3/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.

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.

getStockOrders

MSP 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

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 'Deliveries', 'PurchaseInvoices', 'PurchaseOrders', 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.

setCustomers

MSP 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

MSP SUPPLIER

Creates goods receipts on the Claritum System.

Notethe 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

MSP SUPPLIER

Sets the 'despatched' status on the given orders. 

setSuppliers

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


  • No labels