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'). |