Generic XML-FTP Supplier Integration
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.
Print Job Item Assets
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
wherex
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
wherex
is the surface area merge reference. - A range of thumbnails, each with a naming convention of the form
thumbnail-x.png
wherex
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) | |
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.