NAV
JavaScript C# PHP

Overview

// Javascript samples are shown here on the right
// C# samples are shown here on the right
// PHP samples are shown here on the right

The OneFlow API is a RESTful HTTP based API. Where possible, we have exposed resource-oriented access using standard HTTP verbs and respond with standard HTTP status codes.

When communicating with the API directly, JSON will be returned in all responses including errors. If you are using one of our SDKs, the SDK will transform the JSON responses into language-specific OneFlow objects.

Any off-the-shelf HTTP client written in any language should be able to access the API easily.

TLS

Connect to the OneFlow REST API 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

Here is how to construct the Authorization request header:

// 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;
// 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
  $stringToSign = strtoupper($method) . ' ' . $path . ' ' . $timestamp;
  $signature = hash_hmac('sha1', $stringToSign, $secret);
  $authHeader = $token . ':' . $signature;
?>

Make sure to replace token and secret with your API token and secret keys

The OneFlow REST API uses 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 OneFlow Connect website and are issued with an access token and secret access 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 AWS 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

Orders

Overview

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":       "printcompanyx"
  },
  "orderData": {
    "sourceOrderId":        "41324132",
    "customerName":         "Customer Name",
    "extraData": { },
    "items": [
      {
        "description":          "Photo Book",
        "shipmentIndex":        0,
        "sourceItemId":         "ORDER-13243124",
        "sku":                  "SKU-CODE-X",
        "dispatchAlert":        "please wrap book 1 in blue paper",
        "quantity":             1,
        "unitWeight":           100,
        "barcode":              "13243124",
        "extraData":            { },
        "components": [
          {
            "sourceComponentId":  "ORDER-13243124-1",
            "code":               "text",
            "localFile":          false,
            "fetch":              true,
            "path":               "http://www.site.com/order/13243124/text.pdf",            
            "preflight":          true,
            "duplicate":          10,
            "barcode":            "13243124-1",
            "attributes": {
                "corners": "rounded"
            },
            "extraData": {}
          }
        ]        
      }
    ],
    "stockItems": [
     {
       "code": "coupon",
       "name": "Default Coupon",
       "quantity": 1,
       "shipmentIndex": 0,
       "unitPrice": 0.25
     }
    ],
    "shipments": [
      {
        "sourceShipmentId": "SHIPMENT-13243124-1",
        "shipmentIndex":  0,
        "shipByDate":     "2013-07-12",
        "slaDays":        1,
        "canShipEarly":   true,
        "shipTo":{
          "name":           "Peter Pan",
          "companyName":    "Disney Corporation",
          "address1":       "17 Disney Way",
          "address2":       "",
          "address3":       "",
          "town":           "Los Angeles",
          "postcode":       "34757",
          "state":          "California",
          "isoCountry":     "US",
          "country":        "United States of America",
          "email":          "peter@disney.com",
          "phone":          "+12345678910"
        },
        "returnAddress": {
          "name":           "Peter Pan",
          "companyName":    "Disney Corporation",
          "address1":       "17 Disney Way",
          "address2":       "",
          "address3":       "",
          "town":           "Los Angeles",
          "postcode":       "34757",
          "state":          "California",
          "isoCountry":     "US",
          "country":        "United States of America",
          "email":          "peter@disney.com"
        },
        "carrier": {
          "alias":      "CUSTOM_SHIPPING"
        },
        "attachments": [
          {
            "path":     "http://some.site.com/files/insert.pdf",
            "type":     "insert"
          }
        ]
      }
    ]
  }
}

A minimum order required for a single quantity sku product with a file would be as follows

{
  "destination": {
    "name": "printcompanyx"
  },
  "orderData": {
    "items": [
      {
        "sku": "SKU-CODE-X",
        "components": [
          {
            "code": "text",            
            "fetch": true,
            "path": "http://www.site.com/text.pdf"
          }
        ]
      }
    ],
    "shipments": [
      {
        "shipTo": {
          "name": "Peter Pan",
          "companyName": "Disney Corporation",
          "address1": "17 Disney Way",
          "town": "Los Angeles",
          "postcode": "34757",
          "isoCountry": "US"
        },
        "carrier":{
            "alias": "shipping"
        }
      }
    ]
  }
}

Here is the specifications for the fields that are defined on the right:

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

Field Required Default Options Description
code true Stock code for lookup
name false Item name
quantity false 1 Item Quantity, defaults to 1
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
unitPrice false 0 unitPrice (RRP) is the price the item has been sold to the end consumer for. It is sent to the carrier and is used for customs purposes.

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://pro.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:

Js { “TimeStamp”: “{{timestamp}}“, “OrderId”: “{{data.body}}“, “status”: “Order submission error”, “errorsClean”: [{{#each data.errorList}} “{{#if name}}{{ name }}: {{/if}}{{#if message}}{{ message }}{{else}}Unknown error{{/if}}{{#if path}} - At path {{ path }}{{/if}}” {{/each}}] }

Validate Order

This endpoint validates an order structure and returns whether it is suitable for submission or not.

HTTP Request

POST https://pro-api.oneflowcloud.com/api/order/validate

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

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 - 08 T13: 41: 19.998 Z",
    "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

Piazza Orders

Orders can reference Piazza products on submission rather than including all product information like components. See below for JSON structure differences.

Overview

The basic JSON order structure is shown below

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

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

Piazza Order Structure

The main differences to regular orders are: * Each item must contain sourceProductId, that references a Title previously setup in Piazza * Each item must not contain the components list, because the components for a Title are taken from Piazza

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": "printcompanyx"
  },
  "orderData": {
    "sourceOrderId": "41324132",
    "customerName": "Customer Name",
    "extraData": {},
    "items": [
      {
        "sourceItemId": "ORDER-13243124",
        "sourceProductId": "9781718901438",
        "quantity": 1,
        "description": "Photo Book",
        "shipmentIndex": 0
      }
    ],
    "shipments": [
      {
        "sourceShipmentId": "SHIPMENT-13243124-1",
        "shipmentIndex": 0,
        "shipByDate": "2013-07-12",
        "slaDays": 1,
        "canShipEarly": true,
        "shipTo": {
          "name": "Peter Pan",
          "companyName": "Disney Corporation",
          "address1": "17 Disney Way",
          "address2": "",
          "address3": "",
          "town": "Los Angeles",
          "postcode": "34757",
          "state": "California",
          "isoCountry": "US",
          "country": "United States of America",
          "email": "peter@disney.com",
          "phone": "+12345678910"
        },
        "returnAddress": {
          "name": "Peter Pan",
          "companyName": "Disney Corporation",
          "address1": "17 Disney Way",
          "address2": "",
          "address3": "",
          "town": "Los Angeles",
          "postcode": "34757",
          "state": "California",
          "isoCountry": "US",
          "country": "United States of America",
          "email": "peter@disney.com"
        },
        "carrier": {
          "alias": "CUSTOM_SHIPPING"
        },
        "attachments": [
          {
            "path": "http://some.site.com/files/insert.pdf",
            "type": "insert"
          }
        ]
      }
    ]
  }
}

Shipments

Overview

The basic JSON order structure is shown below

{
  "shipmentIndex" : 0,
  "sourceOrderId" : "...",
  "items" : [ ],
  "shipTo": { },
  "returnAddress": { },
  "carrier": { }
}

Shipments are created by the API during the initial order submission.

The key objects in the order data structure include:

Object Description
shipmentIndex The index of the shipment within the submitted order
sourceOrderId Contains the source order reference ID
items An array of the items objects contained within the shipment.
shipTo The address to send the shipment to
returnAddress The address to return the shipment to if delivery failed
carrier The carrier service and code to use for the delivery

Update

This endpoint allows you to amend the shipTo address on a shipment.

HTTP Request

PUT /api/shipment/<sourceOrderId>/<shipmentIndex>/shipping

Request Body

{
  "shipTo": {
    "name":           "Peter Pan",
    "companyName":    "Disney Corporation",
    "address1":       "17 Disney Way",
    "address2":       "",
    "address3":       "",
    "town":           "Los Angeles",
    "postcode":       "34757",
    "state":          "California",
    "isoCountry":     "US",    
    "email":          "peter@disney.com",
    "phone":          "+12345678910"
  },
  "carrier": {
    "code": "",
    "service": ""
  },
  "trackingNumber": "12345678"
}

HTTP Response

If the update was successful, the updated shipment will be returned.

URL Parameters

Parameter Description
sourceOrderId The source order ID, specified when the order was submitted
shipmentIndex The index of the shipment, as specified when submitting the order

Errors

For 400 errors, the error response will be in a JSON structure as shown below

{
  "success": false,
  "error": {
    "message": "Couldn't find a thing with that ID",
    "name": "NotFound",
    "code": 404
  }
}

The OneFlow API returns a JSON error along with one of the following error codes:

Error Code Meaning
400 Bad Request – Your request had an error. OneFlow will usually return the reason for the 400.
401 Unauthorized – Your API key is wrong
403 Forbidden – Your API key doesn’t allow access to this resource
404 Not Found – The specified resource could not be found
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintanance. Please try again later.

SDKs

The OneFlow API can be also consumed using one of our existing SDKs:

Language Url
.NET https://www.nuget.org/packages/OneFlowSDK/
Javascript https://github.com/Oneflow/oneflow-sdk-js
PHP https://github.com/Oneflow/oneflow-sdk-php
Ruby https://github.com/Oneflow/oneflow-sdk-ruby