TABLE OF CONTENTS

1 OVERVIEW


The Sync API Message Server facilitates communication between third party systems and Sync via a SOAP web service messaging layer. The service validates and processes request messages, executes the request in Sync and returns response messages to the caller.


To invoke an operation on the web service, a request message needs to be created containing the relevant criteria to query or persist data, depending on the requirement. The request message is made up of two parts: the header fields and the body field (MessageXml) which is serialized as an XML string.


The message server will always return a response message in correlation to a request. If the requested operation was successfully executed, a response message with a Resultflag of true and ResponseText of “OK” will be returned to the caller. An error will return a false Resultflag and a ReponseText containing the full details of the error, which may include exception details.


The API contains two methods, Login and Execute. The Login method is used to retrieve a Session Key. This session key will be used with each Execute method request. The session key will not expire with time, but each Login request will generate a new Session Key, invalidating all prior Session Keys. It is recommended that a new session key is requested before calling each Execute method.


The Execute method is used to retrieve or create objects from Sync. The Operation parameter in the Execute method is used to determine what object will be created or retrieved.




2 METHODS

2.1    LOGIN

Communication with the message server is authenticated by the Login method, which provides a response containing a Session Key, this Session Key is required for all further requests.


Request

FieldsData TypeNote
UsernamestringProvided by iSync
PasswordstringProvided by iSync



Response

FieldsData TypeNote
LoginResultstringSession Key to use when calling other methods




PHP Sample


$endpoint='http://integration.mydomain.co.za/SyncAPI/MessageService.svc?wsdl';

$user='webstore';

$pass='A05E63A';


$client=new SoapClient($endpoint, array('trace' => 1));


$loginObject = new stdClass();

$loginObject->username = $user;

$loginObject->password = $pass;


$loginResult = $client->Login($loginObject);

$session_token=$loginResult->LoginResult;



2.2    EXECUTE

Operations are invoked through the Execute method. The execute method requires a Request Message, where the structure is as follows:



Request

FieldsData TypeNote
MessageTypestringName of operation being invoked
Identifierstring
Sourcestring
PublishDatedatetime
Instancestring
ActionstringSpecifies the persistence action INSERT, UPDATE, DELETE, SELECT
SessionKeystringSession key provided by Login Method
MessageXMLstringSerialised XML Message



Response

FieldsData TypeNote
MessageTypestringSame as correlating request's MessageType
IdentifierstringSame as correlating request’s Identifier
SuccessFlagbooleanTrue if successful, false if not
ResponseTextstringResult message, “OK” when successful, error / exception message on failure
Sourcestring Same as correlating request's Source
PublishDatedatetimeSame as correlating request's PublishDate
InstancestringSame as correlating request's Instance
ActionstringSame as correlating request's Action
MessageXMLstringSerialised XML Message




PHP Sample


$Details = new stdClass();

$Details->Action = 'OTHER';

$Details->Identifier = '1';

$Details->Instance = '1';

$Details->MessageType = 'GetProductStockCatalogue';

$Details->MessageXml='<ProductStockCatalogueQueryCriteria xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><AddedDate>2016-06-01T00:00:00</AddedDate></ProductStockCatalogueQueryCriteria>';

$Details->PublishDate = (new DateTime())->format('c');

$Details->SessionKey = $session_token;

$Details->Source = 'Magento';


$Request = new stdClass();


$Request->request = $Details;


try {$result = $client->Execute($Request);} catch (SoapFault $exception) {

            var_dump($exception);

}




3 OPERATIONS

3.1    GETPRODUCTSTOCKCATALOGUE

This operation is used to retrieve a list of Sync SKUs including all the product fields published by the API. This method can use used to populate a catalogue on a website or to update SKU attributes. The operation will return SKUs that have had units change since the date given in the AddedDate parameter.



Request Criteria

NameTypeInputComment
ProductStockCatalogueQueryCriteria
AddedDateDateTimeRequiredShows SKUs updated after date time
AvailableUnitsbool?OptionalStock available to sell



Request XML Example

<ProductStockCatalogueQueryCriteria xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<AddedDate>2016-01-01T00:00:00</AddedDate>

</ProductStockCatalogueQueryCriteria>





3.2    GETPRODUCTSTOCKUNITS

This operation is used to retrieve a list of Sync SKUs, showing available stock figures. The operation will return SKUs that have had units change since the date given in the AddedDate parameter. This operation is a more lightweight version of the getProductStockCatalogue and will only return the ProductStockID, SKU and Units fields.



Request Criteria

NameTypeInputComment
ProductStockUnitsQueryCriteria
AddedDateDateTimeRequiredShows SKUs updated after date time
AvailableUnitsbool?OptionalStock available to sell
ThirdPartyBarcodestringoptionalProduct Stock item barcodes (pipe delimited)



Request XML Example

<ProductStockCatalogueUnitsCriteria xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<AddedDate>2016-01-01T00:00:00</AddedDate>

</ProductStockUnitsQueryCriteria>



3.3    PERSISTWEBSALESORDER

This operation is used to create a Sales Order in Sync.


Request Criteria

NameTypeRequiredComment
WebSalesOrder
CommentsstringNo
DeliveryDetailAddressDetailYes
DeliveryMethodIDintNoi.e. Overnight express, Economy road freight
IsGiftboolNoDefault = false
LineItemsWebSalesOrderDetail[]YesArray of sales order line items
PONumberstringYesOrder # from website
PaymentMethodIDintNo
PrintInvoiceBoolNoDefault = true
RequiredDateDateTimeYes
SpecialInstructionsstringNo
StatusIDintYesSales order header status code
1 - Pending
3 - Approved
TrackNostringYesWeb customer's website database ID




AddressDetail


AddressLine1stringYes
AddressLine2stringNo
AltNumberstringNo
CitystringNo
CompanystringNo
CountrystringNo
EmailstringNo
FullNamestringNo
MobilestringNo
PhonestringNo
PostCodestringNo
ProvincestringNo




WebSalesOrderDetail


CNTypeIDintYes0 for stock item, > 0 for non-stock item
DiscountdecimalNoLine Item Percentage Discount
DueDateDateTimeNoDefaults to current system date
ExRatedecimalYesMust be >= 0
SellingPricedecimalYesMust be >= 0
StatusIDintYesSales order line item status code
1 - Pending
3 - Approved
ThirdPartyBarcodestringYes
UnitsintYes



Request XML Example

<WebSalesOrder xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Comments/>

<DeliveryDetail>

<AddressLine1>10 Downing Street</AddressLine1>

<AddressLine2>Westminster</AddressLine2>

<AltNumber>08358798897</AltNumber>

<City>London</City>

<Company/>

<Country>England</Country>

<Email>[email protected]</Email>

<FullName>John Doe</FullName>

<Mobile>08358798897</Mobile>

<Phone>08358798897</Phone>

<PostCode>0007</PostCode>

<Province>-</Province>

</DeliveryDetail>

<IsGift>false</IsGift>

<LineItems>

<WebSalesOrderDetail>

<CNTypeID>0</CNTypeID>

<Discount>0.00</Discount>

<ExRate>1</ExRate>

<SellingPrice>200</SellingPrice>

<StatusID>3</StatusID>

<ThirdPartyBarcode>ABSCLS2110_00000000000621</ThirdPartyBarcode>

<Units>1</Units>

</WebSalesOrderDetail>

</LineItems>

<PONumber>1000124</PONumber>

<PaymentMethodID>0</PaymentMethodID>

<PrintInvoice>true</PrintInvoice>

<RequiredDate>2014-04-09T17:38:42</RequiredDate>

<SpecialInstructions/>

<StatusID>3</StatusID>

<TrackNo>A1567516</TrackNo>

</WebSalesOrder>



3.4    GETWEBSALESORDER

This operation is used to retrieve a single sales order created via the API. Orders can be retrieved by using the PO Number as a parameter



Request Criteria

NameTypeInputComment
WebSalesOrderQueryCriteria
PONumberstringRequiredSpecifies the PO Number of the sales order to lookup



Request XML Example

<WebSalesOrderQueryCriteria

xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<PONumber>081341987533</PONumber>

</WebSalesOrderQueryCriteria>



Response XML Example

<WebSalesOrder

xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Comments/>

<DeliveryDetail>

<AddressDetailID>28701</AddressDetailID>

<AddressLine1>10 Downing Street</AddressLine1>

<AddressLine2>Westminster</AddressLine2>

<AltNumber/>

<City>London</City>

<Company/>

<Country/>

<Email>[email protected]</Email>

<FullName>John Doe</FullName>

<Mobile/>

<Phone>08358798897</Phone>

<PostCode>0007</PostCode>

<Province>-</Province>

<WarehouseID i:nil="true"/>

</DeliveryDetail>

<DeliveryMethodID>1</DeliveryMethodID>

<EntitlementID>0</EntitlementID>

<IsGift>true</IsGift>

<IsXStock>true</IsXStock>

<LineItems>

<WebSalesOrderDetail>

<CNTypeID>0</CNTypeID>

<Comment/>

<Commission>10.00</Commission>

<Discount>0.00</Discount>

<DueDate>2018-09-01T00:00:00</DueDate>

<ExRate>1.0000</ExRate>

<InvoiceDate i:nil="true"/>

<InvoiceNumber/>

<InvoiceReference/>

<InvoiceSubCustomer>false</InvoiceSubCustomer>

<InvoiceUnits>0.00</InvoiceUnits>

<ProductStockID>0</ProductStockID>

<Reference/>

<SODetailID>136141</SODetailID>

<SalesOrderID>33534</SalesOrderID>

<SellingPrice>16.36</SellingPrice>

<StatusID>11</StatusID>

<ThirdPartyBarcode>999999999999</ThirdPartyBarcode>

<Units>4.00</Units>

</WebSalesOrderDetail>

</LineItems>

<PONumber>081341987533</PONumber>

<PaymentMethodID>3</PaymentMethodID>

<PrintInvoice>true</PrintInvoice>

<RequiredDate>2018-09-01T00:00:00</RequiredDate>

<SalesOrderID>33534</SalesOrderID>

<SpecialInstructions/>

<StatusID>11</StatusID>

<TrackNo>TRACK</TrackNo>

<WebCustomerName>John Doe</WebCustomerName>

<WebSale>true</WebSale>

</WebSalesOrder>



3.5    CREATEWEBCREDITNOTE

This operation is used to create Pending Credit Notes in Sync.



Request Criteria

NameTypeRequiredComment
WebCreditNote
CommentsstringRequiredCredit note header comment
LineItemsArrayOfWebCreditNoteDeail[]
Array of credit note line items
PONumberstringRequiredPO Number of the Sales Order
Referencestring
Create note header reference
SalesOrderNumberstringRequiredNumber of the Sales Order
TrackNostringRequiredTracking Number of the Customer




WebCreditNoteDetail


CNTypeIDintRequired0 for stock item, >0 for non-stock item
Commentstring
Line item comment
Discountdecimal
Line item discount percentage
ExRatedecimalRequiredMust be > 0
RatedecimalRequiredMust be > 0
Referencestring

SellingPricedecimalRequiredMust be > 0
ThirdPartyBarcodestringRequired
UnitsdecimalRequired



Request XML Example

<WebCreditNote xmlns:i="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO">

<Comments>other</Comments>

<LineItems>

<WebCreditNoteDetail>

<CNTypeID>0</CNTypeID>

<Comment/>

<Discount>0.00</Discount>

<ExRate>1</ExRate>

<Reference/>

<SellingPrice>29.95</SellingPrice>

<ThirdPartyBarcode>123123123123</ThirdPartyBarcode>

<Units>1</Units>

</WebCreditNoteDetail>

<WebCreditNoteDetail>

<CNTypeID>4</CNTypeID>

<Comment/>

<Discount>0</Discount>

<ExRate>1</ExRate>

<Reference/>

<SellingPrice>1.25</SellingPrice>

<ThirdPartyBarcode/>

<Units>1</Units>

</WebCreditNoteDetail>

</LineItems>

<PONumber>ON/21838</PONumber>

<Reference>ST002087231-7899</Reference>

<SalesOrderNumber>SO-00026552</SalesOrderNumber>

<TrackNo>WEBCUSTOMER</TrackNo>

</WebCreditNote>




Response XML Example

<WebCreditNote xmlns="http://schemas.datacontract.org/2004/07/iSync.EAI.DTO"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<Comments>other</Comments>

<LineItems>

<WebCreditNoteDetail>

<CNTypeID>0</CNTypeID>

<Comment/>

<Discount>0.00</Discount>

<ExRate>1</ExRate>

<Reference/>

<SellingPrice>29.95</SellingPrice>

<ThirdPartyBarcode>123123123123</ThirdPartyBarcode>

<Units>1</Units>

</WebCreditNoteDetail>

<WebCreditNoteDetail>

<CNTypeID>4</CNTypeID>

<Comment/>

<Discount>0</Discount>

<ExRate>1</ExRate>

<Reference/>

<SellingPrice>1.25</SellingPrice>

<ThirdPartyBarcode/>

<Units>1</Units>

</WebCreditNoteDetail>

</LineItems>

<PONumber>ON/21838</PONumber>

<Reference>ST002087231-7899</Reference>

<SalesOrderNumber>SO-00026552</SalesOrderNumber>

<TrackNo>WEBCUSTOMER</TrackNo>

</WebCreditNote>