SwiftAPI Specification

Version

3

Overview

This document details the operations, transfer method, fields, and encryption scheme used to implement the SwiftAPI.

Operations

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.

Transfer Method

Requests to the API will be send via HTTPS POST.

POST Format

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.

Data Fields

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.
email 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.

Product Fields

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