API Notifications
From Developer's API
(Difference between revisions)
| (29 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | The | + | <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 | + | <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> | + | # 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 | + | # 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 | + | # 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 | + | # 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: | ||
| + | * 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.
Diagram Explained
- When a new event1 is generated in your merchant account a notification token is prepared and sent over https to your notification URL
- 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
- 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 send the prepared data back over https to the API wrapper
- 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
- 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>