Overview

This page is targeted towards suppliers who wish to integrate with Custom Gateway’s SupplierLink order fulfilment system using a combination of XML and FTP.

Order fulfilment using XML and FTP has four different steps:

  • A XML file is created by SupplierLink on an FTP account provided by Custom Gateway that contains one or more orders.
  • The supplier then downloads any pending XML order files from the FTP account.
  • The supplier should then upload an acknowledgement XML file to state that they have received the order information.
  • Once the supplier has finished production and dispatched the order, a shipping confirmation XML file to state that the order(s) have been dispatched to the customer.

Requirements

  • A Custom Gateway provided FTP account specifically for a retailer-supplier combination.

The Orders XML File

SupplierLink will periodically create an XML file in the /orders directory of the FTP account for any new orders. If the /orders directory does not exist then it will be automatically created by SupplierLink.

The XML file may contain multiple orders and items. Below is an ‘'’example’’’ XML file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?xml version="1.0" encoding="UTF-8"?>
<orders>
   <order>
      <id>123456</id>
      <company_ref_id>99999</company_ref_id>
      <ref>abcdefghi</ref>
      <shipping_address_1 />
      <shipping_address_2 />
      <shipping_address_3 />
      <shipping_address_4 />
      <shipping_address_5 />
      <shipping_postcode />
      <shipping_country>GB</shipping_country>
      <shipping_country_code>GB</shipping_country_code>
      <billing_address_1 />
      <billing_address_2 />
      <billing_address_3 />
      <billing_address_4 />
      <billing_address_5 />
      <billing_postcode />
      <billing_country>GB</billing_country>
      <customer_name>James Ball</customer_name>
      <external_ref>100000001</external_ref>
      <shipping_method>Fixed</shipping_method>
      <customer_email>example@example.com</customer_email>
      <shipping_carrier>Flat Rate</shipping_carrier>
      <items>
         <item>
            <id>123456</id>
            <type>1</type>
            <external_ref>100000001-1</external_ref>
            <ref>abcdefghij</ref>
            <sku>MY-SKU</sku>
            <description>Product Description</description>
            <quantity>1</quantity>
            <assets>
               ...
            </assets>
            <attributes>
               <attribute name="bundle" value="MY-SKU-001" />
            </attributes>
         </item>
      </items>
   </order>
</orders>

Once the supplier has retrieved an XML order file, the supplier is then required to move the file to the /archive directory of the FTP account. The supplier is also required to upload an acknowledgement file when they are ready to process the order.

The Item Element

The <item> element will include the same fields as the item object described in the Order-iT integration guide.

In addition to the standard fields, the item element will also include <assets> and <attributes>.

The <assets> element will include a series of child <asset> tags for each piece of artwork associated with an item. Each <asset> has a <name>, <url> and optional <description> child elements. The quantity of <asset> elements will depend primarily upon the item’s type.

A print job item will include an <asset> element for:

  • Each surface area output in each available image format. The naming convention for the asset will be in the form output-x.ext where x is the surface area number.
  • Each surface area merge output in each available image format. The naming convention for the asset will in the form output-merge-x.ext where x is the surface area merge reference.
  • A range of thumbnails, each with a naming convention of the form thumbnail-x.png where x identifies the view or angle from which the thumbnail was taken.

The available image formats depend upon which output type is enabled for the company to which the order belongs.

Output Type Formats
Raster (Default) PNG, JPG, PDF (output.pdf contains a page for each surface area)
Vector (PDF) PDF
Vector (SVG) SVG

Print Job item assets will also include a <description> tag which contains the surface area name (i.e. ‘Front’, ‘Back’, etc.).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
...
<assets>
  <asset>
    <name>output-1.png</name>
    <url>http://example.com/...</url>
    <description>Front</description>
  </asset>
  <asset>
    <name>output-1.jpg</name>
    <url>http://example.com/...</url>
    <description>Front</description>
  </asset>
  <asset>
    <name>output.pdf</name>
    <url>http://example.com/...</url>
    <description>PDF</description>
  </asset>
  <asset>
    <name>thumbnail.png</name>
    <url>http://example.com/...</url>
    <description>Default Thumbnail</description>
  </asset>
  <asset>
    <name>thumbnail-front.png</name>
    <url>http://example.com/...</url>
    <description>Thumbnail Front</description>
  </asset>
  <asset>
    <name>thumbnail-back.png</name>
    <url>http://example.com/...</url>
    <description>Thumbnail Back</description>
  </asset>
  <asset>
    <name>thumbnail-top.png</name>
    <url>http://example.com/...</url>
    <description>Thumbnail Top</description>
  </asset>
  <asset>
    <name>thumbnail-bottom.png</name>
    <url>http://example.com/...</url>
    <description>Thumbnail Bottom</description>
  </asset>
</assets>
...

External URL Item Assets

An External URL item will only include a single <asset> element containing the file name and URL of the external artwork file.

1
2
3
4
5
6
7
8
...
<assets>
  <asset>
    <name>filename.ext</name>
    <url>http://example.com/filename.ext</url>
  </asset>
</assets>
...

Note External URL items will also have a external_url element which may be used instead of iterating over the <assets> element.

The Acknowledgement XML File

The supplier is required to upload an acknowledgement file to the /acknowledgements directory of the FTP account which SupplierLink will then take as confirmation that the supplier is ready and happy to process the order.

The acknowledgement XML file can contain multiple orders and is structured as follows:

1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<orders>
   <order>
      <id>123456</id>
   </order>
</orders>

The ID field must correlate to an order that the supplier has received via the orders XML file (described in the above section). The supplier may not send an acknowledgement for an order that was never sent to it begin with.

Once the file has been processed by SupplierLink, it will be moved into the /archive directory. Therefore it is important that the file is given a unique name.

The Shipment XML File

Once the order has been completed and dispatched to the customer, the supplier should upload a shipment file to the /shipments directory.

The shipment file follows exactly the same structure as the acknowledgement file and the same principles should be used in its creation.