Can osCommerce Integrate With This?

May 22, 2009

We run a software program that is basiclly a a point of sale on steroids. We want to set-up a shopping cart on our web site that will integrate with our "NXT". When I asked about the integration the following is what they sent me. I have no idea if there is any way to get osComerce to work with NXT.

Here is what they sent....

Thanks!!

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

General Overview

You have a website and now you want to integrate it with NXT. Before you can do this, you must understand what level of integration is available and how the integration is performed.

As with any integration the communication is the most important aspect. All data transmitted will be in an XML format over an https connection. The communication itself will always be initiated by NXT.

There are numerous types of requests and responses that will occur. However, they all basically surround and support the invoicing process.

Technology Overview

The communication layer for transactions sent between NXT and the Web Server (server) will be XML over HTTPS (128-bit SSL). This will provide for a secure, expandable, industry standard interface that can easily be adapted to include future transactions or changes to transaction specifications. NXT will initiate the transaction by creating an XML request of this general type:

<?xml version='1.0' encoding=”ISO-8859-1”?>

<verb>someverb</verb>

<field1>somevalue</field1>

<field2>somevalue</field2>

…(etc)…

</entity1>

<entity2>somevalue</entity2>

…(etc)…

</request>

NXT will then post this transaction to an SSL secured URL, which is where the server will run. Example script for posting this request on the client using Microsoft’s XML DOM objects:

Set oHTTPConn = CreateObject("Msxml2.ServerXMLHTTP")

Set oXMLDoc = CreateObject("Msxml2.DOMDocument")

oHTTPConn.open("POST", "https://www.someurl.com/someapplication", False)

oXMLDoc.async = False

If (Not oXMLDoc.loadXML(xmlRequest) Or (oXMLDoc.parseError.errorCode <> 0)) Then

HandleError()

Else

oHTTPConn.send(oXMLDoc)

xmlResponse = oHTTPConn.responseXML.xml

End If

The server will receive the request, handle it based on the requested verb, and generate a response of this general type:

<?xml version="1.0"?>

<status>SUCCESS/FAILED</status>

<errormessage>if any, error message goes here</errormessage>

<field1>somevalue</field1>

<field2>somevalue</field2>

…(etc)…

</entity1>

<entity2>somevalue</entity2>

…(etc)…

</response>

On all transactions, a userid and password are required for authentication. These will be provided by you to NXT as needed.

Support Transactions

There are numerous transactions. We begin by covering all the transactions necessary for NXT to actually retrieve an invoice. I will refer to these transactions as support transactions.

1. Get Manufacturer List Transaction

Upon receiving a “mfglist” request the server will respond with a success/failure message. If successful the response will include a list of all manufacturers currently on the server, including name and code for each.

NXT will send this request when the user clicks on the “Get Suppliers From Web Order System” button. NXT uses the response to populate the Supplier Mapping section of the NXT System Preferences.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>mfglist</verb>

<dealerurl>DealerURL.com</dealerurl>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"? encoding=”ISO-8859-1”>

<status>SUCCESS</status>

<mfg>

<name>Honda</code>

</mfg>

<mfg>

<name>Yamaha</name>

</mfg>

</response>

OR

<?xml version="1.0"? encoding=”ISO-8859-1”>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

RESPONSE FIELD METADATA

Field Name Field Type

Code String(20)

Name String(20)

2. Get Tax Rates Transaction

Upon receiving a “taxrates” request the server will respond with a success/failure message. If successful the response will respond with the current tax rates as defined by the dealer.

NXT will send this request when the user clicks on the “Get Tax Categories From Web Order System” button. NXT uses the response to populate the Tax Mapping section of the NXT System Preferences.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>taxrates</verb>

<dealerurl>DealerURL.com</dealerurl>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

</taxrate>

</taxrate>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

RESPONSE FIELD METADATA

Field Name Field Type

State String(20)

Rate Float

3. Get Payment Types Transaction

Upon receiving a “paymenttypes” request the server will respond with a success/failure message. If successful the response will respond with the current payment types as defined by the dealer.

NXT currently is not using this transaction but will in upcoming release.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>paymenttypes</verb>

<dealerurl>DealerURL.com</dealerurl>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

<paymenttype>MasterCard</paymenttype>

<paymenttype>Discover</paymenttype>

<paymenttype>Yamaha Credit</paymenttype>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

RESPONSE FIELD METADATA

Field Name Field Type

PaymentType String(40)

Invoice Transactions

1. Get Order Count Transaction

Upon receiving a “getorders” request with the optional “countonly” flag set the server will respond with a success/failure message. If successful the response will return a count of the number of orders that are available since the “lastpull” date.

Each NXT client will send this request every 30 seconds if the parts Invoicing window is open. This is the primary mechanism that NXT uses to notify the user that there are pending invoices to download.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>getorders</verb>

<dealerurl>DealerURL.com</dealerurl>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

RESPONSE FIELD METADATA

Field Name Field Type

OrderCount Integer

2. Get Orders Transaction

Upon receiving a “getorders” request the server will respond with a success/failure message. If successful the response will return all orders that are available since the “lastpull” date. The server should update its internal lastpull date at this time.

NXT will only send this request when the user clicks on the “Get Web Orders button”. NXT uses the response to populate the Web Orders grid with all new invoices.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>getorders</verb>

<dealerurl>DealerURL.com</dealerurl>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

<order>

<lastname>Schmo</lastname>

<address1>123 Main Street</address1>

<email>[email protected]</email>

</billing>

<lastname>Schmo</lastname>

<address1>345 Oak Lawn Drive</address1>

<city>San Francisco</city>

</shipping>

</expires>

</payment>

<comments>Please make delivery by Christmas</comments>

<mfg>

<name>Honda</name>

</mfg>

<itemdescription>Leather Gloves</itemdescription>

<comment>This is a comment</comment>

</lineitem>

<mfg>

<name>Yamaha</name>

</mfg>

<itemdescription>Leather Jacket</itemdescription>

<comment>This is a comment</comment>

</lineitem>

</lineitems>

<shipmethod>-Overnight</shipmethod>

</invoice>

</order>

<order>

…etc….

</order>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

RESPONSE FIELD METADATA

Field Name Field Type

OrderNumber String(20)

DatePlaced String mm/dd/yyyy hh:mm:ss AMPM

Billing

Shipping

Payment

Invoice

RESPONSE FIELD METADATA - Billing

Field Name Field Type

FirstName String(45)

LastName String(45)

MiddleInitial String(1)

Address1 String(40)

Address2 String(40)

City String(25)

State String(10)

Country String(50)

PostalCode String(10)

Workphone String(20)

Email String(60)

RESPONSE FIELD METADATA - Shipping

Field Name Field Type

FirstName String(45)

LastName String(45)

MiddleInitial String(1)

Address1 String(40)

Address2 String(40)

City String(25)

State String(10)

Country String(50)

PostalCode String(10)

Workphone String(20)

Email String(60)

PickUpAtStore String(1)

RESPONSE FIELD METADATA - Payment

Field Name Field Type

CCType String(20)

CCNumber String(20)

CCIn String(10)

CustomerServicePhone String(20)

Expires

RESPONSE FIELD METADATA - Expires

Field Name Field Type

Month Integer

Year Integer

RESPONSE FIELD METADATA - Invoice

Field Name Field Type

LineItems - LineItem

Tax Currency

ShipCost Currency

ShipVendor String(25)

ShipMethod String(30)

Total Currency

BackorderTax Currency

BackorderShipCost Currency

BackorderTotal Currency

RESPONSE FIELD METADATA - LineItem

Field Name Field Type

Mfg

ItemCode String(20)

ItemDescription String(30)

Quantity Double

UnitCost Currency

BackOrderedQuantity Double

Comment String(50)

3. Update Order Transaction

The update of an order will consist of NXT generating a “updateorder” XML request and passing it to the server for processing. This will allow the Server and NXT to remain in sync with regards to the data on the order. NXT may change anything on the order and post it back to the server, including changes to billing, shipment, payment information, shipping cost, taxes, prices, as well as add/remove/replacement of line items on the order.

NXT will send this request every time a web order is cashiered.

SAMPLE REQUEST:

<?xml version="1.0"?>

<verb>updateorder</verb>

<dealerurl>DealerURL.com</dealerurl

<order>

<lastname>Schmo</lastname>

<address1>123 Main Street</address1>

<email>[email protected]</email>

</billing>

<lastname>Schmo</lastname>

<address1>345 Oak Lawn Drive</address1>

<city>San Francisco</city>

</shipping>

</expires>

</payment>

<comments>Please make delivery by Christmas</comments>

<dealercomments>Replaced ATX gloves with Honda</dealercomments>

<mfg>

<name>Honda</name>

</mfg>

<itemdescription>Leather Gloves</itemdescription>

<comment>This is a comment</comment>

</lineitem>

<mfg>

<name>Yamaha</name>

</mfg>

<itemdescription>Leather Jacket</itemdescription>

</lineitem>

</lineitems>

<shipmethod>-Overnight</shipmethod>

</invoice>

</order>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

4. Status Update Transaction

The status update of an order will consist of NXT generating a “statusupdate” XML request and passing it to the server for processing. The XML request will consist of the ordernumber as it exists on the server, data to define the type of status change and any data elements associate with that status change. Current status change types are “shipped”, “cancelled” and “productremoved”.

For “shipped” status, a “shipment” entity may be included that will contain information on the shipment, such as the items shipped and their quantity, the shipping vendor, cost and tracking number.

The “productsremoved” status handles situations where NXT removes products from the order due to situations where backordered products have taken too long to ship, and the customer indicates they do not wish to receive the products anymore. Including in this transaction are “lineitem” entities defining the products to be removed. The “updateorder” transaction should still be used for most adjustments to an invoice. This “productremoved” status update transaction is provided for voiding items on orders that are further along in processing.

“shipvendor” values that begin with “FedEx”, “UPS”, “USPS”, and “DHL” that include a tracking number, will enable a hyperlink in customer order status to the appropriate website for shipment tracking.

NXT will send this request every time a web order is cashiered.

SAMPLE REQUEST:

<?xml version='1.0'?>

<verb>statusupdate</verb>

<dealerurl>DealerURL.com</dealerurl

<order>

<newstatus>shipped</newstatus>

<mfg>

<name>Yamaha</name>

</mfg>

</lineitem>

<mfg>

<name>Yamaha</name>

</mfg>

</lineitem>

</lineitems>

</shipment>

</order>

</request>

OR

<?xml version='1.0'?>

<verb>statusupdate</verb>

<dealerurl>DealerURL.com</dealerurl>

<order>

<newstatus>cancelled</newstatus>

</order>

</request>

OR

<?xml version='1.0'?>

<verb>statusupdate</verb>

<dealerurl>DealerURL.com</dealerurl>

<order>

<newstatus>productsremoved</newstatus>

</lineitem>

</lineitem>

</lineitems>

</order>

</request>

SAMPLE RESPONSE:

<?xml version="1.0"?>

<status>SUCCESS</status>

</response>

OR

<?xml version="1.0"?>

<status>FAILED</status>

<errormessage>This is some error message</errormessage>

</response>

Frequently Asked Questions:

Question:

Why does Lightspeed think nothing is being returned, even though I can clearly see my XML is there?

Answer:

The content-type is not set to “text/xml”.

Question:

In Lightspeed should I include the full URL?

Answer:

Yes, it should include https://www.yourwebsite.com/lightspeed.php (or whatever) your site is.

Question:

Do my suppliers have to be mapped (in System Preferences ~ Supplier Mapping)?

Answer:

Yes, Lightspeed will not accept the shopping cart invoice unless the suppliers are mapped.

Question:

Do you have to have a username and password?

Answer:

Yes, or Lightspeed will not work properly, it does consider the username and password as mandatory.

Can osCommerce Integrate With This?

Recommended Posts

Guest

Link to comment

Share on other sites

Archived

Browse

Activity