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>ORDER ID</id> This is the reference used for status updates.  This should be stored in your systems and used as the order identifier for status updates for all integrations. 

<company_ref_id>KORNITX ID REFERENCE FOR NEXT</company_ref_id> This value will always be populated with 18698.

<secondary_company_ref_id>KORNITX SUPPLIER ID</secondary_company_ref_id> This reference is the dropship reference specific to each supplier account.

<ref>KORNITX ORDER REFERENCE</ref> This is not required for the integration or invoicing and can therefore be ignored.

<status>516</status> 

<shipping_company/> 

<shipping_address_1>43 TEST STREET</shipping_address_1> Address Line 1

<shipping_address_2/> This will always be blank

<shipping_address_3/> This will always be blank

<shipping_address_4>TEST</shipping_address_4> Town / City

<shipping_address_5>TEST</shipping_address_5> Region / County

<shipping_postcode>J34 2JF</shipping_postcode> Postcode

<shipping_country>United Kingdom</shipping_country> Country

<shipping_country_code>GB</shipping_country_code> Country Code

<billing_company/> Billing Info will not be provided

<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> EXTERNAL ORDER REFERENCE (NEXT)</external_ref> This is the Next Customer Order Reference and should be stored for invoicing.

<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> This is the date the customer is expecting the order on or before.

<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</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> This SKU is generated by Next and is the SKU required for invoicing.

<mapped_sku>MANUFACTURER SKU</mapped_sku> This SKU is the Manufacturing SKU. If the product has size or colour options, this SKU will be unique to the option selected.

<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> Pricing may not always be included in the file. If values are included they should not be used for invoicing purposes.

<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> This url should be stored in your systems so that is can be downloaded, printed and included with each order.

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

The Dispatch Note "url" can be found within the "pdfs" array, example below: 

<pdfs> 

<pdf> 

<type>1</type> 

<url>https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/misc/html2pdf/02ed35b8f21b26b137c5dd3b0c224d0d.pdf</url>

</pdf> 

                  </pdfs> 
Notes

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.


Invoicing & Reports

Invoicing is not handled via the Kornit X Platform.   Suppliers who are integrated to the Kornit X Platform will usually extract and store all relevant information needed for order reporting / reconciliation for Next Invoicing in their own systems.
For order reconciliation purposes, as well as the standard order information we recommend that you always store the following data fields:
            <sku>
            <mapped_sku>
            <external_ref>

If required, you can however extract Order Detail Reports from the Kornit X Platform.
Step by Step instructions for this can be found in the Using the Kornit X Platform Documentation  under the 'Reports' header.

FAQ's

Can't find what you're looking for? Click here where more information can be found on our FAQ page.

    • 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 KornitX 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 ...

    • Next | Order & Stock Management | FAQs

      Next Supplier Onboarding FAQs Direct Dispatch & Personalised Suppliers Welcome to the KornitX Platform The following document has been written to supplement to information provided in the Technical Documentation. This document covers the most common ...

    • 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 | Integration Test Plan - CSV & XML

      Next Supplier Onboarding Integration Test Plan - CSV & XML When completing the integration, please follow the below test plan and confirm when all of the steps have been successfully completed. Acknowledge & Dispatch Order (with tracking) 1a. ...