3
This document details the operations, transfer method, fields, and encryption scheme used to implement the SwiftAPI.
Operation | Incoming / Outgoing to Plugin Operation | Description |
---|---|---|
home | outgoing | A user visits the website's homepage. |
product | outgoing | A user visits a product details page - a page that lists all information about a single product. |
cart | outgoing | A user adds products to the shopping cart. |
order | outgoing | A user successfully places an order on the website. |
pastorder | outgoing | When a client first sets up the plugin on their website it will send all historical order data to the Swift system, unless the client decides to opt out. |
subscription | outgoing | A user submits their email address to join a newsletter using Magento's standard newsletter subscription feature. |
viewmail | n/a | A user accesses the website via a link in one of the SwiftERM system's emails. |
unsubscribe | n/a | A user unsubscribes from the SwiftERM system the system will not send them anymore emails. |
emailpackage | incoming | The SwiftERM system has generated a series of emails to be sent by a client's site. |
sendmail | incoming via emailpackage | The Swift system has generated an email to be sent by a client's site. |
ping | outgoing | Upon registration, it tells SwiftERM that the plugin is ready to send data. |
Requests to the API will be send via HTTPS POST.
Key | Data Type | Description |
---|---|---|
version | Integer | The API version number. |
domain | String | The domain name of the SwiftERM clients site. |
data | String | A base64 encoded string containing an AES-256 initialization vector followed by a AES-256 encrypted JSON object comprised of the Data Fields listed below. |
Field | Data Type | Required for Operations | Optional for Operations | Description |
---|---|---|---|---|
domain | String | ALL | The domain name of the SwiftERM clients site. (This is required to be duplicated in the data section to prevent forged requests.) | |
date | String - ISO 8601 Date | ALL | An ISO Date when the request was generated in the format YYYY-MM-DDThh:mm e.g. 2007-04-05T14:30 | |
operation | String - SwiftAPI Operation ID | ALL | One of the SwiftAPI operation ID's | |
user | String - UUID | ALL | A universally unique identifier generated by the SwiftERM client site/plugin used to identify a user over the duration of their visit to a site. | |
url | String | home | The URL of the page where the API request was triggered. | |
String | order, pastorder, subscription, viewmail, sendmail, unsubscribe | home, product, cart | The users email address. | |
forename | String | order, pastorder | The users forename. | |
surname | String | order, pastorder | The users surname. | |
product | String | product, viewmail | A site specific product identifier (Should correspond to ID's provided in the sites 'product XML file'). | |
products | Array | cart, order, pastorder | An array of JSON objects containing Product Fields. | |
subject | String | sendmail | Message subject for a swift email. | |
body | String | sendmail | Message content for a swift email. | |
orderId | String | order, pastorder | The client system's unique order identifier, typically an order Id | |
orderStatus | String | order, pastorder | The client system order's current status of an order | |
emailId | String | viewmail, sendmail | The system identifier to identify what email was clicked on. | |
monitor | String | sendmail | If present, the client site shall also send an email to the email address specified in the field. | |
key | String | ping | The Site Key that the SwiftERM has generated. | |
emailPackage | String | emailpackage | Contains a collection of sendmail packages that were sent from the SwiftERM system. | |
site | String | emailpackage | Contains a site unique identifier in the SwiftERM system. | |
is_mail_function | String | emailpackage | Tells the plugin to use mail function rather than smtp, if present. |
Field | Data Type | Description |
---|---|---|
product | String | A site specific product identifier (Should correspond to ID's provided in the sites 'product XML file'). |
quantity | Integer | The number of products in the order. |
price | String | The product price (May potentially differ from the value specified in the sites 'product XML file'). |