Native Web Store Template
This is a webservice implementation for developers wishing to modify a proprietary web store server to work with the Acctivate Web Store Sync. For more information see the docs page.
Before a web store administrator can sync their webstore, they must create a web store configuration in Acctivate, and enter a few pieces of information. They must provide a URL, Username, and Password which are needed to construct GET and POST requests to the web server.
Note: The example URLs indicate PHP, but any languages are supported that can accept and process XML requests.
Example of a web store configuration:
URL: https://www.example.com/api.php
Username: admin
Password: abc123
Last order number downloaded: 10
This information is then used to generate a web request by Web Store Sync to download orders. For example, the constructed Request URL for Sales Order 1052305 would be:
GET https://www.example.com/api.php?Request=QueryOrder&WebOrderNumber=1052305&Username=admin&Password=abc123
The XML Response from the above Sales Order Request (i.e. QueryOrder) is parsed to create new Acctivate Sales Orders, including the ID for the Customer Record in the Web Store database. The Customer data will be retrieved with a secondary Customer Request.
Acctivate Webservice Requests
Acctivate processes XML returned by a webservice with XPath-style parsing. Element sequence does not matter, and an omitted element is treated the same as an empty element. Tags are case-sensitive. Empty space outside of value elements is ignored.
All queries must return valid XML. If a web service returns non-XML (e.g. HTML or plain text), it is assumed that there was a communication failure and the web store sync process is canceled.
A web service should parse XML posted to it and ignore any elements it does not recognize. New elements may be added inside <Request> tag as updates to this specification are made, however the sequence of existing tags will remain the same for backwards compatibility.
Elements in the <Request> tag marked as N/A in the comments are fields specific to Acctivate whose values are not likely to be available from the web store. The web store administrator may set default values for those fields in the web store template in Acctivate.
Values returned by the web service may be mapped and converted to Acctivate values. For example, a common conversion would be for the Method of Payment field from web-store specific values to their equivalents in Acctivate.
Sales Order Request
GET http(s)://www.example.com/api.php?Request=QueryOrder&WebOrderNumber=1052305&Username=admin&Password=abc123
Sales Orders are downloaded consecutively until a query returns no order data. Therefore, order numbers should be integers and should be created by the web store consecutively without any skipped orders. Any orders that shouldn’t be imported because they have been invalidated, canceled, or deleted should be marked as Deleted (more info below).
Tax Categories are codes for tax rates specific to a customer location (e.g. DAL, FW for Dallas and Fort Worth, respectively). Tax Codes are product specific. In the U.S. edition of Acctivate, the default tax codes available are Tax and Non.
Sales Order Response
The Sales Order Response should contain only the Single Sales Order requested for the <WebOrderNumber>. Acctivate will maintain the Last Web Order Number in the Acctivate Web Store template and continue requesting orders until no more sales orders are found.
An example Sales Order Response is listed below. Please download the full Sales Order Response schema for all fields and detailed comments.
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
<Order>
<WebOrderNumber>1052305</WebOrderNumber>
<OrderDate>2015-09-14</OrderDate>
<Type>O</Type>
<OrderStatus>S</OrderStatus>
<WebCustomerID>2531235</WebCustomerID>
<ShipToDescription>Downtown</ShipToDescription>
<ShipToAttention>Bill Jones</ShipToAttention>
<ShipToAddress1>Abercrombie and Smith</ShipToAddress1>
<ShipToAddress2>123 Main Street</ShipToAddress2>
<ShipToCity>Fort Worth</ShipToCity>
<ShipToState>TX</ShipToState>
<ShipToZip>76102</ShipToZip>
<ShipToCountry>US</ShipToCountry>
<SoldToName>Abercrombie</SoldToName>
<SoldToAddress1>Abercrombie and Smith</SoldToAddress1>
<SoldToAddress2>450 North Main St</SoldToAddress2>
<SoldToCity>Fort Worth</SoldToCity>
<SoldToState>TX</SoldToState>
<SoldToZip>76102</SoldToZip>
<SoldToCountry>US</SoldToCountry>
<ContactFirstName>Kristi</ContactFirstName>
<ContactLastName>Abercrombie</ContactLastName>
<ContactName>Kristi Abercrombie</ContactName>
<ContactEMailAddress>kristi@abersmith.example.com</ContactEMailAddress>
<ContactPhoneNumber>817-555-6579</ContactPhoneNumber>
<ContactFax>817-555-4253</ContactFax>
<ShippingInstructions>Deliver to Bill at front entrance</ShippingInstructions>
<SpecialInstructions>Pack binders separately from paper</SpecialInstructions>
<PendingShippingCharges>25.95</PendingShippingCharges>
<TaxCode>Tax</TaxCode>
<TaxCategoryID>FW</TaxCategoryID>
<ShipVia>Ground</ShipVia>
<Carrier>UPS</Carrier>
<CarrierService>Ground</CarrierService>
<MethodOfPayment>Credit Card</MethodOfPayment>
<CheckOrCreditCardNumber>4111111111111111</CheckOrCreditCardNumber>
<CreditCardExpirationDate>05/2013</CreditCardExpirationDate>
<CreditCardExpirationMonth>5</CreditCardExpirationMonth>
<CreditCardExpirationYear>13</CreditCardExpirationYear>
<CreditCardName>Kristi Abercrombie</CreditCardName>
<CreditCardAddress>450 North Main</CreditCardAddress>
<CreditCardPostalCode>76102</CreditCardPostalCode>
<AmtPaid>100.43</AmtPaid>
<TotalAmount>100.43</TotalAmount>
<DiscountAndCharges>
<Discount>
<Amount>10.00</Amount>
</Discount>
<Charge>
<Amount>5.00</Amount>
</Charge>
</DiscountAndCharges>
<OrderLines>
<OrderLine>
<LineID>1</LineID>
<VendorProductID>B10</VendorProductID>
<DisplayQtyOrdered>20</DisplayQtyOrdered>
<DisplayUnit>Ea</DisplayUnit>
<BasePrice>2.87</BasePrice>
<SpecialInstructions>Please remove inserts from binders</SpecialInstructions>
</OrderLine>
<OrderLine>
<LineID>2</LineID>
<VendorProductID>CP2003</VendorProductID>
<DisplayQtyOrdered>5</DisplayQtyOrdered>
<DisplayUnit>Ea</DisplayUnit>
<BasePrice>3.95</BasePrice>
</OrderLine>
</OrderLines>
</Order>
</Result>
Response if Sales Order was Deleted or Canceled
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
<Order>
<WebOrderNumber>1052305</WebOrderNumber>
<!-- ... Other fields are ignored ... -->
<Deleted>True</Deleted>
</Order>
</Result>
Respond with Status = Success only if no sales order was found for the given Order Number. This will end the Web Store Sync progress successfully and the Last Web Order Number will be updated for this Web Store in the Acctivate database.
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
</Result>
NOTE: Acctivate will assume an unexpected failure has occurred if no Status is included in the Sales Order Response.
The Acctivate Web Store Sync can display a message if an Invalid Request or an unexpected error has occurred. The Last Web Order Number will not be updated in this case.
Any Status other than “Success” will be displayed in the Web Store Sync user interface. The Status message should include information required to troubleshoot the problem(s). A full exception log including the request and response will be available in the Acctivate Log directory on the Acctivate server.
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Invalid request / Out of memory / etc</Status>
</Result>
Customer Request
The Acctivate Web Store Sync will optionally download information for new customers found in the Sales Order Response. The Web Customer ID is provided in the QueryCustomer request.
GET http(s)://www.example.com/api.php?Request=QueryCustomer&WebCustomerID=2531235&Username=admin&Password=abc123
Customer Response
A new customer record will be created in Acctivate with the provided information in the Response. These customer records will also be synchronized to QuickBooks. Therefore, we recommend using the Customer Name or Email Address as the primary Customer ID/Name since QuickBooks doesn’t support a separate Customer ID and Name.
Customers in Acctivate have a single billing address and multiple shipping address records. All addresses are structured in the four-line address block format also found in QuickBooks. The first address line (i.e., <Address>) is typically the customer’s business or contact name.
| Address Field | Example 1 | Example 2 | Example 3 |
|---|---|---|---|
| <Address> | Abercrombie and Smith | Abercrombie and Smith | Kristi Abercrombie |
| <Address2> | 450 North Main St | Kristi Abercrombie | 450 Main St |
| <Address3> | Third Floor | 450 North Main St | Third Floor |
| <Address4> | Third Floor | ||
| <City> | Fort Worth | Fort Worth | Fort Worth |
| <State> | TX | TX | TX |
| <Zip> | 76102 | 76102 | 76102 |
| <Country> | US | US | US |
Acctivate requires that one shipping address be defined as the Preferred Shipping Address. Set the <ShipTo>/<Default> value to true or <Customer>/<DefaultShipToLocationID> to a specific LocationID if multiple shipping addresses are provided.
Another approach is to map all addresses to the <ShipTo> elements. If one of the addresses is a billing address, set <Customer>/<DefaultSoldToLocationID> to the appropriate LocationID and leave the customer billing address fields (<Address>, <Address2>, etc) in the <Customer> element empty.
An example Customer Response is listed below. Please download the full Customer Response schema for all fields.
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
<Customer>
<WebCustomerID>2531235</WebCustomerID>
<CompanyName>Abercrombie and Smith</CompanyName>
<Name>Abercrombie</Name>
<Address>Abercrombie and Smith</Address>
<Address2>450 North Main St</Address2>
<City>Fort Worth</City>
<State>TX</State>
<Zip>76102</Zip>
<Country>US</Country>
<Phone>817-555-6579</Phone>
<PhoneDesc>Main Phone</PhoneDesc>
<Fax>817-555-4253</Fax>
<Email>kristi@abersmith.example.com</Email>
<EmailDesc>Kristi Abercrombie</EmailDesc>
<AltPhone>817-555-2244</AltPhone>
<AltPhoneDesc>Kristi's personal</AltPhoneDesc>
<FirstName>Kristi</FirstName>
<LastName>Abercrombie</LastName>
<SalespersonId>JDJ</SalespersonId>
<TaxCode>Tax</TaxCode>
<CustomerType>Customer</CustomerType>
<TermsCode>Net 30</TermsCode>
<DateOpened>2012-02-01</DateOpened>
<Login>Abercrombie</Login>
<Password>Kristi</Password>
<ShipTos>
<ShipTo>
<LocationID>Downtown</LocationID>
<LocationName>Downtown Office</LocationName>
<Address1>Abercrombie and Smith</Address1>
<Address2>123 Main Street</Address2>
<City>Fort Worth</City>
<State>TX</State>
<Zip>76102</Zip>
<Country>US</Country>
<Status>True</Status>
<Default>True</Default>
<SpecialInstructions>All packages MUST be marked with PO Number</SpecialInstructions>
<ShippingInstructions>Deliver to loading dock on 2nd Street</ShippingInstructions>
</ShipTo>
<ShipTo>
<LocationID>Main</LocationID>
<LocationName>Main Office</LocationName>
<Address1>Abercrombie and Smith</Address1>
<Address2>1023 Exchange</Address2>
<City>Fort Worth</City>
<State>TX</State>
<Zip>76000</Zip>
<Country>US</Country>
<Status>True</Status>
<Default>False</Default>
<Comment></Comment>
</ShipTo>
</ShipTos>
<Contacts>
<Contact>
<ContactID>Bill</ContactID>
<FullName>Bill Jackson</FullName>
<Title>CFO</Title>
<Phone>888-555-1215</Phone>
<Email>bill@abersmith.example.com</Email>
</Contact>
<Contact>
<ContactID>Fred</ContactID>
<FullName>Fred Abercrombie</FullName>
<Title>Sales Manager</Title>
<Phone>888-555-1212</Phone>
</Contact>
</Contacts>
</Customer>
</Result>
Response if no customer was found:
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
</Result>
Update Inventory Request
Web Store Sync sends inventory qtys for all products in Acctivate. Unknown product ids should be ignored and the status should still return Success in that case.
POST http(s)://www.example.com/api.php?Request=UpdateInventory&Username=admin&Password=abc123
Example Inventory Request for Product B10, based on a quantity available of 50 Ea.
<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Inventory>
<Product>
<VendorProductID>B10</VendorProductID>
<QtyAvailable>50</QtyAvailable>
</Product>
<!-- ... Additional Products ... -->
</Inventory>
</Request>
Update Inventory Response
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
</Result>
Update Tracking Numbers Request
Tracking number update should replace all tracking numbers in the web store with the numbers in the Update Inventory request for each order.
POST http(s)://www.example.com/api.php?Request=UpdateTrackingNumbers&Username=admin&Password=abc123
Example Request to update Status and add Tracking Numbers for Web Order 1052305:
<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<TrackingNumbers>
<Order>
<WebOrderNumber>1052305</WebOrderNumber>
<Package>
<TrackingNumber>1Z9999999999999998</TrackingNumber>
<Carrier>UPS</Carrier>
<CarrierService>Ground</CarrierService>
<Items>
<Item>
<LineID>1</LineID> <!-- LineID from order detail -->
<Qty>4</Qty> <!-- In stocking units -->
</Item>
<Item>
<LineID>2</LineID>
<Qty>6</Qty>
</Item>
<!-- Additional Items -->
</Items>
</Package>
<!-- Additional Packages -->
</Order>
<!-- Additional Orders -->
</TrackingNumbers>
</Request>
Update Tracking Numbers Response
<?xml version="1.0" encoding="utf-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.acctivate.com/xmlschema/">
<Status>Success</Status>
</Result>
NOTE: Please note that <Carrier> and <CarrierService> values are user-defined. However, the Carrier Service list typically matches the standards for each carrier. The Carrier Service list is maintained in Acctivate Configuration Management in the Sales Orders section.