API Reference

To connect to our API’s, all requests must be authenticated. Please follow the guides below to authenticate against our API’s.

TLS

Connecting to OneFlow RESTful API’s will require at least TLS 1.1, but preferable TLS 1.2 for all HTTPS connections.

If you need help to ensure that your environment is ready for this you can follow one of these checks.

Authentication

OneFlow RESTful API’s use an HTTP Authorization header to pass authorization information. Under the OneFlow authorization scheme, the Authorization header has the following form:

x-oneflow-authorization: Token:Signature

OneFlow User accounts are created via the SiteFlow website and are issued with an access token and secret key. For request authorization, the Token element identifies the access key ID that was used to compute the signature and, indirectly, the user account making the request.

The Signature element is the RFC 2104HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the OneFlow secret access key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

In addition to the Authorization header the request must also contain a ‘x-oneflow-date’ header which contains the timestamp used in the Signature encryption. Below is an example of the headers used in the the request

x-oneflow-authorization: 124213431243214:1f32c4a3455b67a5d7

x-oneflow-date: 2014-03-10 17:16:18

Generating The Authorization Request Header

Below are some code examples which generate the `x-oneflow-authorization` header detailed above.

JavaScript

// We use the crypto NPM module for encryption of the signature
var crypto = require('crypto');
    
var stringToSign = method + " " + path + " " + timestamp;
var hmac = crypto.createHmac("SHA1", secret);
hmac.update(stringToSign);
var signature = hmac.digest("hex");
var authHeader = token + ":" + signature;

C#.

// Required for use HMACSHA1:
using System.Security.Cryptography;
    
string stringToSign = method + " " + path + " " + timestamp;
HMACSHA1 hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secret));
byte[] signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign));
string signature = BitConverter.ToString(signatureBytes).Replace("-", "").ToLower();
string authHeader = token + ":" + signature;

PHP

<?php
   $stringToSign = strtoupper($method) . ' ' . $path . ' ' . $timestamp;
   $signature = hash_hmac('sha1', $stringToSign, $secret);
   $authHeader = $token . ':' . $signature;
?>

Orders

The basic JSON order structure is shown below

{
  "destination":  { },
  "orderData": {
    "items": [
      {
        "components":[ ]
      }
    ],
    "shipments": [
      {
        "shipTo": { },
        "returnAddress": { },
        "carrier": { }
      }
    ]
  }
}

Orders are submitted using a predefined JSON structure, any additional fields or child elements in the structure will be ignored.

The key objects in the order data structure include:

Object Description
destination Destination account for the order, for example the site where the order will be fulfilled.
orderData Contains the main order data, detailed below.
items An array of the items objects contained within the order. At least 1 item is required.
components An array of components that are contained within the order item, for example text or cover
shipments An array of shipments (destinations). These are referenced by each order item, using the shipmentIndex field. At least 1 shipment is required

Order Structure

Below is an example of a full order structure including fields that have default values.
It is not necessary to include all of these fields in the order.

{
  "destination": {
    "name": "oneflow-lite"
  },
  "orderData": {
    "sourceOrderId": "order123",
    "customerName": "",
    "items": [
      {
        "sku": "Flyer",
        "quantity": 1,
        "sourceItemId": "getting-started-item",
        "components": [
          {
            "code": "Content",
            "path": "https://s3-eu-west-1.amazonaws.com/oneflow-public/Connect/Flyer.pdf",
            "fetch": true,
            "attributes": {
              "finish": "Gloss"
            }
          }
        ]
      }
    ],
    "shipments": [
      {
        "shipTo": {
          "name": "Oneflow Systems",
          "address1": "1 Primrose Street",
          "town": "London",
          "isoCountry": "GB",
          "country": "United Kingdom",
          "postcode": "EC2A 2EX"
        },
        "carrier": {
          "alias": "express"
        },
        "slaDays": 3
      }
    ]
  }
}

Below are field specifications:

Destination

Field Required Default Options Description
name true     The account name that is order is to be sent to

OrderData

Field Required Default Options Description
sourceOrderId true     Must be set by the sender and represents their internal order id
customerName false     Customer Name
extraData false     Optional. An object that can be used to store structured data that can be included in postbacks

OrderData.Items

Field Required Default Options Description
description false     Optional. Can provide a description for the order item. Different to the configured product description
shipmentIndex false 0   An integer that corresponds to one of the items in the shipment array, it will default to the first one so should be ignored for single shipment orders
sourceItemId true     Unique within the order. Represents the internal item ID
sku true     This must be a valid SKU code which has been previously set up in the destination account
dispatchAlert false     This message will show at dispatch when the item is scanned.
quantity false 1   Item Quantity, defaults to 1
unitWeight false     unitWeight is the weight of the item. This can override what has been configured on the product.
barcode false     Customer specified barcode, can be used if the barcode is already on the artwork provided by the customer
extraData false     An object that can be used to store structured data that can be included in postbacks

OrderData.Items.Component

Field Required Default Options Description
code true     Used to map this object to the corresponding component in the OneFlow product
path true     The artwork for the component. You must set either ‘fetch’ to true or ‘localFile’ to true
fetch True if localFile is false false   If true, the file will be fetched from a URL (in the above ‘path’ field) into OneFlow’s cloud storage
localFile True if fetch is false false   If true, the file won’t be fetched and must already exist on site at the print company
preflight false false   Tells OneFlow whether to preflight the submitted artwork. This is false if localFile = true
sourceComponentId false     Provides a field for customer specified component ID
duplicate false 1   Number of duplications to make of the component. 1 means no duplication.
barcode false     The barcode for the component
attributes false     A dictionary of key-value pairs that specify attributes that define this component that have been configured in the destination account
extraData false     Optional. An object that can be used to store structured data that can be included in postbacks

OrderData.Shipments

Field Required Default Options Description
sourceShipmentId false     Optional field to specify a reference number for the sender’s shipment
shipmentIndex false     The index of this shipment (referenced by items.shipmentIndex)
shipByDate false     Date that it needs to be shipped, in the format “yyyy-mm-dd”
slaDays false     slaDays can be used to override what has been configured on the SKU. PSPs can set a min SLA that will ensure that the item is given an agreed minimum amount of time to be produced.
canShipEarly false true   Whether the shipment can be shipped earlier than shipByDate or not
shipTo.name true     Shipping Name
shipTo.companyName false     Optional. Company Name
shipTo.address1 true     Line 1 of Address
shipTo.address2 false     Line 2 of Address
shipTo.address3 false     Line 3 of Address
shipTo.town true     City / Town
shipTo.postcode true     Postcode or Zip code
shipTo.state false     Optional. State of address
shipTo.isoCountry true     2 Character ISO Country code
shipTo.phone false     Phone number for Address. Required for some carriers i.e. Fedex
returnAddress.name true     Shipping Name
returnAddress.companyName false     Optional. Company Name
returnAddress.address1 true     Line 1 of Address
returnAddress.address2 false     Line 2 of Address
returnAddress.address3 false     Line 3 of Address
returnAddress.town true     City / Town
returnAddress.postcode true     Postcode or Zip code
returnAddress.state false     Optional. State of address
returnAddress.isoCountry true     2 Character ISO Country code
carrier.alias true     The alias for the shipping service being used to ship the order
attachments false     Allows the attachment of additional files (fetch only) such as packing slips

Postbacks

Postbacks are handled through the OneFlow trigger system. These are set up within OneFlow and allow the postbacks to be sent to a variety of destinations in a multitude of different formats (using the templating system).

Order Received

When an order has been received by OneFlow and is ready to undergo the necessary processing steps to prepare it for production.

Order Errored

When one or more of the files failed to be fetched/processed or fails preflighting.

Order Cancelled

When an order has been cancelled, either via the API or by a user.

Order Print Ready

When all the files in an order have been successfully fetched, processed and optionally preflighted. The order then goes into Print Ready status, which means the PSP is able to begin production when they are ready.

Shipment Shipped

When a shipment within an order has been produced, assembled, and finally dispatched.

Order Submission Error

Due to the asynchronous nature of the process, errors won’t be available in the response of the order submission request.

Errors will be posted to the system and shown in a new area inside the Production UI (https://connect.oneflowcloud.com/#/order-submission-errors/list).

PSPs have access to see these errors and brands have access to this via Brand Center.

Within this area, you are able to edit the order data and then resubmit it.

N.B. do not keep resubmitting the order from this page if an error is not returned as it may create a new order with duplicated barcodes.

It is also possible to configure a ‘submission error’ trigger which will post back the error message once the order has been processed. This will contain a simple error message on why the order has errored. Example postback template:

{
 "TimeStamp": "",
 "OrderId": "",
 "status": "Order submission error",
 "errorsClean":  [
       ": Unknown error - At path "
   ]
} 

Create Order

This endpoint submits an order into OneFlow for immediate processing.

HTTP Request

POST https://orders.oneflow.io/api/order

The body of the request should be the order structure in JSON format.

HTTP Response

Submission process

The submission request will be stored in a persistent storage location and will be processed asynchronously.

Response

The response to the caller will happen right after the order request has been stored correctly. This response will be shown, regardless of whether the order is valid or not. The response body will include the following fields:

{
	"_id": "5910757 faab8ec6f60127999",
	"url": "https://s3.amazonaws.com/order/5910757faab8ec6f60127999",
	"timestamp": "2017-04-08T13:41:19.998Z",
	"sourceAccountId": "51 bb2fc71745777ba63f3f11"
}
Field Description
_id The order identifier. The system will keep this identifier and will save it within the new order
url Url to the stored original order content
timestamp Date and time of the order submission request
sourceAccountId Requester’s account id

The new API is designed to scale up and down depending on the current demand. The API will limit the number of request it accepts during the time it is scaling up. This will require the requesters to handle the possible 5XX responses trying to resubmit the request after a few seconds, the time the system requires to finish the provision of new instances.

Get All Orders

This endpoint retrieves all orders (by page). They are sorted by most recent first.

HTTP Request

GET https://pro-api.oneflowcloud.com/api/order?page=2&pagesize=3

Query Parameters

Parameter Default Description
pagesize 10 Optional. The size of the page (number of orders) to return
page 1 Optional. Which page to return

Get an Order

This endpoint retrieves a specific order.

HTTP Request

GET https://pro-api.oneflowcloud.com/api/order/<ID>

HTTP Response

If the order was found, the response body is existing order (in JSON format).

URL Parameters

Parameter Description
ID The ID of the order to retrieve (will be a 24-character hex string)

Cancel an Order (by source ID)

This endpoint allows you to cancel a specific order, using the source account name and ID.

HTTP Request

PUT https://pro-api.oneflowcloud.com/api/order/<sourceAccountName>/<sourceOrderId>/cancel

No request body is necessary.

HTTP Response

If the order was found and wasn’t already cancelled, the response body is the cancelled order (in JSON format).

URL Parameters

Parameter Description
sourceAccountName The name of the source account that the order originated from
sourceOrderId The source order ID, specified when the order was submitted