API Notifications

From Developer's API

(Difference between revisions)
 
(32 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
The 1ShoppingCart notification system sends messages via https of new events<sup>[[#1]]</sup> that have taken place on your 1ShoppingCart merchant account. A message is created in XML and sent to a user configurable URL. The notification data can then be used to call the API and retrieve specific information, such as the details of a new order.
+
<p>The notification system sends messages via http of new events<sup>1</sup> that have taken place on your merchant account. A message is created in XML and sent to a [http://api.1shoppingcart.com/index.php?title=Notification_URL user configurable URL]. The notification data can then be used to call the API and retrieve specific information, such as the details of a new order.</p>
 +
 
 +
<p>The API notifications are sent reliably, meaning that the message will be retried until a http response 200/OK is received from your notification url. Please note that the time between each attempt will be doubled, for example, first attempt immediately, second attempt at 1 minute, third attempt at 2 minutes, fourth attempt at 4 minutes etc.</p>
  
 
===API Notifications Overview===
 
===API Notifications Overview===
−
<p>The following diagram shows the typical flow of data when the 1ShoppingCart API sends new event notification.</p>
+
<p>The following diagram shows the typical flow of data when the API sends a new event notification.</p>
 +
 
 
[[image:ApiNotificationProcess.jpg]]
 
[[image:ApiNotificationProcess.jpg]]
  
 
=====Diagram Explained=====
 
=====Diagram Explained=====
−
# When a new event<sup>[[#1]]</sup> is generated in your merchant account a notification token is prepared and sent over https to your notification url
+
# When a new event<sup>1</sup> is generated in your merchant account a notification token is prepared and sent over https to your [http://api.1shoppingcart.com/index.php?title=Notification_URL notification URL]
−
# The notification request sent from the 1ShoppingCart API contains XML in the request body and holds the event type and token within its nodes
+
# The notification request sent from the API contains XML in the request body and holds the event type and token within its nodes
 
# Parse the event type and token values from the XML then call the API wrapper method corresponding to the event type to retrieve the detailed information
 
# Parse the event type and token values from the XML then call the API wrapper method corresponding to the event type to retrieve the detailed information
−
# The API wrapper will prepare the request to the 1ShoppingCart API and send the request over http
+
# The API wrapper will prepare the request to the API and send the request over https
 
# The API will parse out the merchant id, merchant key and token value from the request and prepare the requested data.
 
# The API will parse out the merchant id, merchant key and token value from the request and prepare the requested data.
 
# The API will send the prepared data back over https to the API wrapper
 
# The API will send the prepared data back over https to the API wrapper
−
# The API wrapper received the requested data back from the API as XML
+
# The API wrapper receives the requested data back from the API as XML
 
# The notification listener receives the XML data from the API wrapper where it can verify the success attribute of the response node
 
# The notification listener receives the XML data from the API wrapper where it can verify the success attribute of the response node
 
# Add functionality to support your business processes. for example you can parse the ShippingInfo node and prepare shipping labels.
 
# Add functionality to support your business processes. for example you can parse the ShippingInfo node and prepare shipping labels.
−
 
  
 
<sup>1</sup> Currently the following events support API notification:
 
<sup>1</sup> Currently the following events support API notification:
−
* New orders
+
* Test Notifications
 +
* New Orders
 +
 
 +
===Test Notifications===
 +
A Test Notification is sent when a you call the [https://www.mcssl.com/API/118303/Notifications/TEST?key=0&doc=1 Test Notification] API Method. Use this feature to verify that your Notification Listener is functional.
 +
 
 +
The data contained in a Test Notification is as follows:
 +
 
 +
<Test>Test notification queued at 2008-12-03 14:26:30</Test>
  
 
===New Orders===
 
===New Orders===
 +
New Order Notification is sent when a new order has been placed for your merchant account.
 +
 +
The data contained in a New Order Notification is as follows:
 +
 +
<NewOrder><Token>{Token Value}</Token></NewOrder>

Latest revision as of 20:16, 16 May 2014

The notification system sends messages via http of new events1 that have taken place on your merchant account. A message is created in XML and sent to a user configurable URL. The notification data can then be used to call the API and retrieve specific information, such as the details of a new order.

The API notifications are sent reliably, meaning that the message will be retried until a http response 200/OK is received from your notification url. Please note that the time between each attempt will be doubled, for example, first attempt immediately, second attempt at 1 minute, third attempt at 2 minutes, fourth attempt at 4 minutes etc.

Contents

API Notifications Overview

The following diagram shows the typical flow of data when the API sends a new event notification.

ApiNotificationProcess.jpg

Diagram Explained
  1. When a new event1 is generated in your merchant account a notification token is prepared and sent over https to your notification URL
  2. The notification request sent from the API contains XML in the request body and holds the event type and token within its nodes
  3. Parse the event type and token values from the XML then call the API wrapper method corresponding to the event type to retrieve the detailed information
  4. The API wrapper will prepare the request to the API and send the request over https
  5. The API will parse out the merchant id, merchant key and token value from the request and prepare the requested data.
  6. The API will send the prepared data back over https to the API wrapper
  7. The API wrapper receives the requested data back from the API as XML
  8. The notification listener receives the XML data from the API wrapper where it can verify the success attribute of the response node
  9. Add functionality to support your business processes. for example you can parse the ShippingInfo node and prepare shipping labels.

1 Currently the following events support API notification:

  • Test Notifications
  • New Orders

Test Notifications

A Test Notification is sent when a you call the Test Notification API Method. Use this feature to verify that your Notification Listener is functional.

The data contained in a Test Notification is as follows:

<Test>Test notification queued at 2008-12-03 14:26:30</Test>

New Orders

New Order Notification is sent when a new order has been placed for your merchant account.

The data contained in a New Order Notification is as follows:

<NewOrder><Token>{Token Value}</Token></NewOrder>

Retrieved from "http://api.1shoppingcart.com/index.php?title=API_Notifications"