SwiftAPI Specification

Version

3

Overview

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

Operations

Operation Description
home A user visits the website's homepage.
product A user visits a product details page - a page that lists all information about a single product.
cart A user adds products to the shopping cart.
order A user successfully places an order on the website.
pastorder 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 A user submits their email address to join a newsletter using Magento's standard newsletter subscription feature.
viewmail A user accesses the website via a link in one of the Swift system's emails.
sendmail The Swift system has generated an email to be sent by a clients site.
unsubscribe A user unsubscribes from the Swift system.

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

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