Next | Order & Stock Management | Integration Guide - XML

Next | Order & Stock Management | Integration Guide - XML

 

 

 


Next Integration Guide 

XML File Data Exchange Over SFTP

 

 

 

Welcome to the Kornit X Platform

Kornit X is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for fulfillment by third party suppliers. 

This document describes the integration specification for a supplier to integrate to the Kornit X Platform for the Direct Dispatch or Personalised Model.


Details are supplied for order and stock management using XML file data exchange over SFTP.



Managing Orders via XML

Kornit X have created a standard XML format that we can generate and push over SFTP to an accessible location for suppliers to then connect and read the files, importing the orders into their own production systems. The same SFTP can then be used to pass back acknowledgement of the order and dispatch confirmation, again in a standard XML format. 



Set Up

SFTP Hosting

To enable us to generate and pass these files we would need the following SFTP Credentials: 
- Host
- Username
- Password
- Port

If you do not have access to an SFTP server yourself, we can set up a location for these files through our Architects team and provide you with the above credentials.

We can also authenticate through a key pair which if needed we can generate and provide you with.

Integration Configuration

Your Kornit X Representative will configure the integration and confirm once this is done and ready for testing.
In the event of any errors with the integration/file format, you will receive an email notification.
Please confirm the email address that these errors should be sent to. 

Receiving Orders via XML

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

The integration will run every 10 minutes (approx).

You will receive one XML file per order - This file contains all details required to complete the order split into sections: 

 

> Order 

> Item 

> Assets 

> Attributes 


 Order Elements

The order elements of the XML contains all of the order specific details such as: 

  1. Order Number
  2. Shipping Address 
  3. Billing Address 
  4. Customer Details (name, email etc) 
  5. Shipping details (Method and Carrier) 

The <orders> object then contains an <items> array of which there can be multiple <item> objects - In more general terms, an order can contain multiple items. 

 
Item Elements
The <item> element will include the same fields as the item object described in the Order-iT integration guide available at https://developers-v2.custom-gateway.net/ 

 

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. 

 

Each <item> will contain <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. 



 




Example File Format

Below is an example of an anonymised XML file. 

 

<orders> 

<order> 

<id>16128737</id> 

<company_ref_id>18698</company_ref_id> 

<secondary_company_ref_id>18878</secondary_company_ref_id> 

<ref>F87B1B135F7EF784</ref> 

<status>516</status> 

<shipping_company/> 

<shipping_address_1>43 TEST STREET</shipping_address_1> 

<shipping_address_2/> 

<shipping_address_3/> 

<shipping_address_4>TEST</shipping_address_4> 

<shipping_address_5>TEST</shipping_address_5> 

<shipping_postcode>J34 2JF</shipping_postcode> 

<shipping_country>United Kingdom</shipping_country> 

<shipping_country_code>GB</shipping_country_code> 

<billing_company/> 

<billing_address_1/> 

<billing_address_2/> 

<billing_address_3/> 

<billing_address_4/> 

<billing_address_5/> 

<billing_postcode/> 

<billing_country>United Kingdom</billing_country> 

<customer_name>MISS A TESTER</customer_name> 

<customer_telephone/> 

<customer_telephone_mobile/> 

<sale_datetime>2020-10-08 00:00:00</sale_datetime> 

<external_ref>2766692200</external_ref> 

<has_been_completed/> 

<completion_datetime>0000-00-00 00:00:00</completion_datetime> 

<has_pdf_been_queued/> 

<has_pdf_been_completed/> 

<shipping_method>5 Days</shipping_method> 

<customer_email>ATESTER@YAHOO.CO.UK</customer_email> 

<shipping_carrier> OwnCarrier</shipping_carrier> 

<shipping_tracking/> 

<shipping_note_url/> 

<payment_trans_id>12345</payment_trans_id> 

<payment_type/> 

<has_initial_confirmation_email_been_sent/> 

<has_shipping_confirmation_email_been_sent/> 

<creation_datetime>2020-10-08 11:27:00</creation_datetime> 

<additional_info>DQ695212</additional_info> 

<has_error/> 

<error_message/> 

<required_dispatch_date>2020-10-14</required_dispatch_date> 

<is_status_callback_pending/> 

<stock_request_id>0</stock_request_id> 

<status_callback_attempts>0</status_callback_attempts> 

<status_callback_next_retry>0000-00-00 00:00:00</status_callback_next_retry> 

<consolidate/> 

<has_been_invoiced/> 

<billing_customer_name/> 

<billing_customer_email/> 

<billing_customer_telephone/> 

<shipping_price>0</shipping_price> 

<shipping_price_inc_tax>0</shipping_price_inc_tax> 

<shipping_tax_rate>0</shipping_tax_rate> 

<is_urgent/> 

<tag/> 

<pos_user_id/> 

<coupon_code/> 

<currency_code>GBP</currency_code> 

<is_free_of_charge/> 

<status_name>Received by shipper</status_name> 

<company_external_ref/> 

<items> 

<item> 

<id>34328128</id> 

<sale_vat_rate>0</sale_vat_rate> 

<external_ref>2799366</external_ref> 

<ref>n6xrl213tp</ref> 

<order_id>16128737</order_id> 

<sku>291169</sku> 

<mapped_sku>291169</mapped_sku> 

<description>P Snta Stop Strt Sgn</description> 

<colour/> 

<size>ONE</size> 

<quantity>1</quantity> 

<type>2</type> 

<print_job_id>43816626</print_job_id> 

<print_job_promise_ref/> 

<external_url/> 

<external_thumbnail_url/> 

<status>1</status> 

<print_on_demand_ref/> 

<plain_stock_item_ref/> 

<license/> 

<license_percentage/> 

<unit_sale_price>18</unit_sale_price> 

<unit_sale_price_inc_tax>18</unit_sale_price_inc_tax> 

<unit_cost_price>0</unit_cost_price> 

<shipping_price>0</shipping_price> 

<shipping_price_inc_tax>0</shipping_price_inc_tax> 

<bundle_ref/> 

<textual_product_id>1690160</textual_product_id> 

<product_variant_id/> 

<quantity_batched>1</quantity_batched> 

<quantity_dispatched>0</quantity_dispatched> 

<stock_request_id/> 

<artwork_barcode>43816626</artwork_barcode> 

<quantity_consolidated>0</quantity_consolidated> 

<product_state_id/> 

<status_name>Received</status_name> 

<print_job_ref>5A45179F665F74BF52</print_job_ref> 

<assets> 

<asset> 

<name>output-1.jpg</name> 

<url>https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/print-job/5A45179F665F74BF52/print-artwork-vector/single-1.pdf</url> 

<description>Santa Stop Sign</description> 

</asset> 

<asset> 

<name>thumbnail.png</name> 

<url>https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18878_43816626.png</url> 

<description>Default Thumbnail</description> 

</asset> 

<asset> 

<name>thumbnail-288386.png</name> 

<url>https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18878_43816626_288386.png</url> 

<description>Thumbnail Santa Stop Here Sign</description> 

</asset> 

</assets> 

<attributes> 

<attribute> 

<name>Colour</name> 

<value>Aqua</value> 

</attribute> 

<attribute> 

<name>Postcode for map</name> 

<value>OL25TG</value> 

</attribute> 

<attribute> 

<name>House Number or Name</name> 

<value>8</value> 

</attribute> 

<attribute> 

<name>Street</name> 

<value>Kirkdale Drive</value> 

</attribute> 

<attribute> 

<name>Town</name> 

<value>Royton</value> 

</attribute> 

<attribute> 

<name>Names</name> 

<value>The Sencicle Home</value> 

</attribute> 

</attributes> 

</item> 

</items> 

<pdfs> 

<pdf> 

<type>1</type> 

<url>http://generated-assets-gateway3d-com.s3-website-eu-west-1.amazonaws.com/misc/html2pdf/1db18d5b6a8ae3b0467a0b0te86bff58.pdf</url> 

</pdf> 

</pdfs> 

</order> 

</orders> 

 

Example File Format (Annotated)

The below one has some amendments in bold to clarify fields where the contents is not obvious. 


<orders> 

<order> 

<id>KORNITX UNIQUE ORDER ID</id> 

<company_ref_id>KORNITX ID REFERENCE FOR NEXT </company_ref_id> 

<secondary_company_ref_id>KORNITX SUPPLIER ID</secondary_company_ref_id> 

<ref>KORNITX ORDER REFERENCE</ref> 

<status>516</status> 

<shipping_company/> 

<shipping_address_1>43 TEST STREET</shipping_address_1> 

<shipping_address_2/> 

<shipping_address_3/> 

<shipping_address_4>TEST</shipping_address_4> 

<shipping_address_5>TEST</shipping_address_5> 

<shipping_postcode>J34 2JF</shipping_postcode> 

<shipping_country>United Kingdom</shipping_country> 

<shipping_country_code>GB</shipping_country_code> 

<billing_company/> 

<billing_address_1/> 

<billing_address_2/> 

<billing_address_3/> 

<billing_address_4/> 

<billing_address_5/> 

<billing_postcode/> 

<billing_country>United Kingdom</billing_country> 

<customer_name>MISS A TESTER</customer_name> 

<customer_telephone/> 

<customer_telephone_mobile/> 

<sale_datetime>TIMESTAMP ON THE ORDER FROM NEXT</sale_datetime> 

<external_ref> KORNIT X ORDER REFERENCE</external_ref> 

<has_been_completed/> 

<completion_datetime>0000-00-00 00:00:00</completion_datetime> 

<has_pdf_been_queued/> 

<has_pdf_been_completed/> 

<shipping_method> NEXT EXPECTED LEAD TIME</shipping_method> 

<customer_email>ATESTER@YAHOO.CO.UK</customer_email> 

<shipping_carrier> OwnCarrier</shipping_carrier> 

<shipping_tracking/> 

<shipping_note_url/> 

<payment_trans_id>NEXT INVOICE NUMBER</payment_trans_id> 

<payment_type/> 

<has_initial_confirmation_email_been_sent/> 

<has_shipping_confirmation_email_been_sent/> 

<creation_datetime>2020-10-08 11:27:00</creation_datetime> 

<additional_info>DQ695212</additional_info> 

<has_error/> 

<error_message/> 

<required_dispatch_date>2020-10-14</required_dispatch_date> 

<is_status_callback_pending/> 

<stock_request_id>0</stock_request_id> 

<status_callback_attempts>0</status_callback_attempts> 

<status_callback_next_retry>0000-00-00 00:00:00</status_callback_next_retry> 

<consolidate/> 

<has_been_invoiced/> 

<billing_customer_name/> 

<billing_customer_email/> 

<billing_customer_telephone/> 

<shipping_price>0</shipping_price> 

<shipping_price_inc_tax>0</shipping_price_inc_tax> 

<shipping_tax_rate>0</shipping_tax_rate> 

<is_urgent/> 

<tag/> 

<pos_user_id/> 

<coupon_code/> 

<currency_code>GBP</currency_code> 

<is_free_of_charge/> 

<status_name>Received by shipper</status_name> 

<company_external_ref/> 

<items> 

<item> 

<id>34328128</id> 

<sale_vat_rate>0</sale_vat_rate> 

<external_ref>2799366</external_ref> 

<ref>n6xrl213tp</ref> 

<order_id>16128737</order_id> 

<sku>NEXT ITEM NUMBER</sku> 

<mapped_sku>MANUFACTURER SKU</mapped_sku> 

<description>P Snta Stop Strt Sgn</description> 

<colour/> 

<size>ONE</size> 

<quantity>1</quantity> 

<type>2</type> 

<print_job_id>43816626</print_job_id> 

<print_job_promise_ref/> 

<external_url/> 

<external_thumbnail_url/> 

<status>1</status> 

<print_on_demand_ref/> 

<plain_stock_item_ref/> 

<license/> 

<license_percentage/> 

<unit_sale_price>18</unit_sale_price> 

<unit_sale_price_inc_tax>18</unit_sale_price_inc_tax> 

<unit_cost_price>0</unit_cost_price> 

<shipping_price>0</shipping_price> 

<shipping_price_inc_tax>0</shipping_price_inc_tax> 

<bundle_ref/> 

<textual_product_id>1690160</textual_product_id> 

<product_variant_id/> 

<quantity_batched>1</quantity_batched> 

<quantity_dispatched>0</quantity_dispatched> 

<stock_request_id/> 

<artwork_barcode>43816626</artwork_barcode> 

<quantity_consolidated>0</quantity_consolidated> 

<product_state_id/> 

<status_name>Received</status_name> 

<print_job_ref>5A45179F665F74BF52</print_job_ref> 

<assets> 

<asset> 

<name>output-1.jpg</name> 

<url>https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/print-job/5A45179F665F74BF52/print-artwork-vector/single-1.pdf</url> 

<description>Santa Stop Sign</description> 

</asset> 

<asset> 

<name>thumbnail.png</name> 

<url>https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18878_43816626.png</url> 

<description>Default Thumbnail</description> 

</asset> 

<asset> 

<name>thumbnail-288386.png</name> 

<url>https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18878_43816626_288386.png</url> 

<description>Thumbnail Santa Stop Here Sign</description> 

</asset> 

</assets> 

<attributes> 

<attribute> 

<name>Colour</name> 

<value>Aqua</value> 

</attribute> 

<attribute> 

<name>Postcode for map</name> 

<value>OL25TG</value> 

</attribute> 

<attribute> 

<name>House Number or Name</name> 

<value>8</value> 

</attribute> 

<attribute> 

<name>Street</name> 

<value>Kirkdale Drive</value> 

</attribute> 

<attribute> 

<name>Town</name> 

<value>Royton</value> 

</attribute> 

<attribute> 

<name>Names</name> 

<value>The Sencicle Home</value> 

</attribute> 

</attributes> 

</item> 

</items> 

<pdfs> 

<pdf> 

<type>1</type> 

<url>URL FOR DISPATCH NOTE FOR DOWNLOAD AND PRINT</url> 

</pdf> 

</pdfs> 

</order> 

</orders> 


Personalisation

It is possible for us to send text based personalisation in the XML  where there is no requirement for the supplier to receive print ready artwork from the platform. 

This is a setting on the integration which your Kornit X contact can enable for you. 

These fields are added to the <attributes> element 




Order Consolidation 

As standard, orders will be passed as individual order lines and the supplier can consolidate at the packing stage if desired.   
For example, if a customer orders 2 products from Next in 1 transaction, two individual orders with unique order references will be passed to the supplier. 

 

 

 

 However, there are systemic solutions available - these should be discussed and agreed with the Next team directly. 

Branded Dispatch Notes

A branded A4 Dispatch Note must be included within each order. It contains information which is vital for the Customer Returns process.    

An example Dispatch Note can be viewed here. 

The Dispatch Note is available to download and print from the platform. 

If you are integrating directly with the platform, a URL will be included with the data where you will be able to access and print the Dispatch Note. 


Dispatch / Delivery Date 

Please note that the <required_dispatch_date> is the date that the customer is expecting the product to be delivered to them, therefore you should be dispatching before this date with enough time to include your delivery. 


Acknowledging Orders via XML

The supplier is required to upload an acknowledgement file to the /acknowledgements directory of the SFTP account which Kornit X will then take as confirmation that the supplier is ready and happy to process the order - there is no specific file naming convention.

Acknowledgements are expected within 1 hour of order receipt.

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

Once the file has been processed by Kornit X, it will be deleted. 


Example File Format

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





Shipping Orders via XML

Once the order has been completed and dispatched to the customer, the supplier should upload a shipment file to the /shipments directory - there is no specific file naming convention.

The shipment file follows exactly the same structure as the acknowledgement file and the same principles should be used in its creation. The only addition is that the shipping file can contain a tracking link / reference. 

Once processed by Kornit X the shipments XML files will be deleted. 

Please note, a Shipment file will only be accepted by the integration once an order has been successfully acknowledged.

Example File Format



Cancelling Orders via XML

If a supplier is unable to fulfill an order, the order can be cancelled via the XML. To do so, XML should be placed in the /shipments directory on your SFTP - there is no specific file naming convention.
Once the file has been processed by Kornit X, it will be deleted. 

Example File Format

Below is an example of how this needs to appear within the XML.  

  

<cancellations xmlns:c="https://custom-gateway.net/sl/proxy2/generic-fs/cancellation" xmlns:ci="https://custom-gateway.net/sl/proxy2/generic-fs/cancellation-item">  

  

  <c:cancellation>  

   <c:items>  

     <ci:item>  

      <ci:order_item_id>43463373</ci:order_item_id>  

     </ci:item>  

    </c:items>  

</c:cancellation>  

</cancellations> 

 

Where:
      <ci:order_item_id> = <id> taken from items array

Managing Inventory via XML

Stock values can be provided based on either a ring-fenced or shared stock pool. Where the stock is ring-fenced, the frequency with which the data is provided is less critical.  However, if stock is part of a shared stock pool, stock updates are required frequently, based on stock position changes, in order to mitigate issues with fulfilment.

On the SFTP these XML files should be placed in a directory called /inventory in the root - there is no specific file naming convention.
Once the file has been processed by Kornit X, it will be deleted. 

The main stock file (full feed) is to be received by Kornit X daily, at a designated time.
There is an option to submit further delta files containing absolute values received at designated intervals, following the processing of the Next order files.

A stock quantity of 0 should be sent if the Brand would like to remove an item from the Next website. A stock update of zero will update the item to show “Currently unavailable” on the Next website, then after 20 minutes the item will be automatically removed from the search feed, unavailable for customers to purchase.

Example File Format

<inventory xmlns:i="https://custom-gateway.net/sl/proxy2/generic-fs/inventory" xmlns:p="https://custom-gateway.net/sl/proxy2/generic-fs/inventory-product"> 

<i:product> 

<p:sku>ABC</p:sku> 

<p:quantity_available>1</p:quantity_available> 

</i:product> 

</inventory> 


NOTE - with this inventory file, "sku" can be replaced with "ean".



File Paths

XML files should be placed in the following SFTP folder structure:

Orders will be placed in the /transfer/orders directory by Kornit X.

Acknowledgements should be sent to the /transfer/acknowledgements directory.

Inventory files should be posted to the /transfer/inventory directory.

Order Status should be sent to the /transfer/shipments directory.

Archive: Once orders are processed, they should be moved to the /transfer/archive directory.


    • Related Articles

    • Next | Order & Stock Management | Integration Guide - CSV

      Next Integration Guide CSV File Data Exchange Over SFTP Welcome to the Kornit X Platform Kornit X is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for ...

    • Next | Order & Stock Management | Integration Guide - API

      Next Integration Guide Data Exchange Over REST API Welcome to the Platform Kornit X is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for fulfilment by third ...

    • JoJo Maman Bébé Integration Guide - XML

            JoJo Maman Bébé   Direct Dispatch Supplier Onboarding  Generic FileSystem - XML      Prepared by Anna Britton (Professional Services Specialist)   & Cobi Martin (Training and Documentation Coordinator)        Welcome to the Platform  Kornit X ...

    • Next | Order & Stock Management | KornitX Platform For Label Plus

      Label Plus+ Suppliers Using the Kornit X Platform Please note we are now known exclusively as Kornit X, a division of Kornit Digital – Custom Gateway was our name before our takeover. To access the platform please refer to the following link – CLICK ...

    • Next | Order & Stock Management | KornitX Platform For Direct Dispatch

      Direct Dispatch Suppliers Using the Kornit X Platform Please note we are now known exclusively as Kornit X, a division of Kornit Digital – Custom Gateway was our name before our takeover. To access the platform please refer to the following link – ...