Supplier API

Introduction

The Order Push API allows a supplier to configure a per dropship URL that will receive order details for any new orders created by retailers.

Order details are sent to the URL via a simple JSON POST request.

Additionally, a X-CustomGateway-Hmac header is also sent as part of the request. This header can be used to verify that the request has originated from Kornit^X.

Below is an example of the JSON structure you can expect to receive

JSON

{
    "id":0,
    "company_ref_id":Sales Channel Company Ref ID,
    "secondary_company_ref_id":"Dropship Connection Ref ID",
    "ref":"unique Kornit X reference",
    "status":1,
    "status_name":"Received",
    "shipping_company":"",
    "shipping_address_1":"",
    "shipping_address_2":"",
    "shipping_address_3":"",
    "shipping_address_4":"",
    "shipping_address_5":"",
    "shipping_postcode":"",
    "shipping_country":"",
    "shipping_country_code":"ISO 2 Country Code",
    "billing_company":"",
    "billing_address_1":"",
    "billing_address_2":"",
    "billing_address_3":"",
    "billing_address_4":"",
    "billing_address_5":"",
    "billing_postcode":"",
    "billing_country":"",
    "customer_name":"",
    "customer_telephone":"",
    "customer_telephone_mobile":"",
    "sale_datetime":"YYYY-MM-DD HH:MM:SS",
    "external_ref":"Sales Channel order reference",
    "has_been_completed":false,
    "completion_datetime":"0000-00-00 00:00:00",
    "shipping_method":"",
    "customer_email":"",
    "shipping_carrier":"",
    "shipping_tracking":"",
    "shipping_note_url":"Sales Channel Generate Paperwork URL",
    "payment_trans_id":"",
    "payment_type":"",
    "creation_datetime":"YYYY-MM-DD HH:MM:SS",
    "additional_info":"",
    "has_error":false,
    "error_message":"",
    "required_dispatch_date":"0000-00-00",
    "billing_customer_name":"",
    "billing_customer_email":"",
    "billing_customer_telephone":"",
    "shipping_price":0,
    "shipping_price_inc_tax":0,
    "shipping_tax_rate":0,
    "is_urgent":false,
    "coupon_code":"",
    "currency_code":null,
    "is_free_of_charge":true,
    "company_external_ref":"",
    "items":[
        {
            "id":0,
            "sale_vat_rate":0,
            "external_ref":"Sales Channels unique item ref",
            "ref":"KornitX unique item ref",
            "order_id":0,
            "sku":"",
            "mapped_sku":"",
            "description":"",
            "colour":"",
            "size":"",
            "quantity":1,
            "type":2,
            "print_job_id":0,
            "external_url":"",
            "external_thumbnail_url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/product-state\/ZZ9BC2105A64DF76C8-thumbnail.png",
            "status":1,
            "plain_stock_item_ref":"",
            "unit_sale_price":0,
            "unit_sale_price_inc_tax":0,
            "unit_cost_price":0,
            "shipping_price":0,
            "shipping_price_inc_tax":0,
            "bundle_ref":"",
            "textual_product_id":"0",
            "product_variant_id":"0",
            "artwork_barcode":"0",
            "status_name":"Received",
            "ecommerce":{
                "barcode":""
            },
            "attributes":[
            {
               "name":"",
               "value":""
              },
            ],
            "assets":[
                {
                    "name":"output-5251025.jpg",
                    "description":"Front",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZ759C450D64DF76C8\/print-artwork\/single-5251025.jpg"
                },
                {
                    "name":"output-merged-j1hdhnrfmg265vh.jpg",
                    "description":"Front & Neck",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZ759C450D64DF76C8\/print-artwork\/merged-302443.jpg"
                },
                {
                    "name":"thumbnail.png",
                    "description":"Default Thumbnail",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340.png"
                },
                {
                    "name":"thumbnail-2254325.png",
                    "description":"Thumbnail Front",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254325.png"
                },
                {
                    "name":"thumbnail-2254326.png",
                    "description":"Thumbnail Back",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254326.png"
                },
                {
                    "name":"thumbnail-2254329.png",
                    "description":"Thumbnail Neck Label",
                    "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254329.png"
                }
            ],
      "virtual_variant": {
        "ean": "1234567890131"
      }
        }
    ],
      "pdfs":[
      {
      "id":0,
      "order_id":0,
      "type":1,
      "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/misc\/html2pdf\/cc4c1c951eb1d6555401b628132a83a00.pdf",
      "ref":"5pr6wrmrm6l49n8khzb1",
      "is_outdated":false
    }
    ],
    "shipments":[
    ]
}

Order Level Attributes

The Kornit X platform allows order level attributes to be submitted which may contain additional relevant information. For example for shipments to Brazil or other countries where this is required this is where the TaxID that will be needed to process shipping will be provided

JSON

"attributes":[
            {
               "name":"TaxID",
               "value":"123456789"
            },

Setup

To receive order pushes, a supplier must enable the "Generic API" supplier integration against the relevant dropship company in the Kornit X platform.

Note - This integration can be set on a “Fulfiller” type company if it is part of a network. In that case this integration will run on all connected dropships that do not have their own overriding integration.

Once the integration has been enabled, a push URL defined and changes saved, a HMAC key will be automatically generated.

The integration can be accessed by going to SETTINGS > COMPANIES and selecting a relevant Dropship or Fulfiller based on the above, selecting the “Supplier Integrations” tab and clicking “Generic API”

When this integration is selected you will be presented with a popup where required information and settings can be added.

Enabled - Yes / No for if the integration is enabled and allowed to run

Dispatch Date Filter - If enabled orders will only be processed on their “Required Dispatch Date” so assumes same day turnaround of production.

Dropship Delegation -

Auto Ship - If enabled orders will be automatically classed as shipped when passed into the receiving supplier system

Generate Documents - If you need to get KornitX generated Dispatch or Address labels then the option “Generate Documents” needs to be enabled on the integration settings and these will be generated as part of the initial order processing if they are set on the Sales Channel or Dropship companies. This only supports documents of type (1) Dispatch (meant for packing slips) or (4) Address (meant for basic address labels) and any PDFs generated will be sent in the "pdfs" section of the JSON body.

Email Errors To - Any errors in running this integration will be sent to this email address.

Start Timestamp (UTC) - This is a UTC date time which sets a limit on which any orders older than this will not be triggered on this integration.

Push URL - Your API Endpoint should be added here.

Proxy - If you have agreed a specific proxy IP with KornitX to be used to allow all requests to come from a static IP it should be added here.

HMAC Key - Once the integration has been enabled, a push URL defined and changes saved, a HMAC key will be automatically generated. See below for more details on verifying this key for security.

Artwork Format - PNG, JPEG, TIFF, PDF dropdown.

Do Not Send Blank Print Areas - If enabled then outputs will only be sent where a print area has been populated (this should nearly always be enabled).

Auth Username - If a basic authentication username is needed, add it here.

Auth Password - If a basic authentication password is needed, add it here.

Data Strategy - If you have worked with KornitX on a custom format for how the JSON should be sent to you which does not match our generic format then you will have a unique value to add here to trigger it.

Auth Strategy - If you have worked with KornitX on a custom authentication method which does not match our generic format then you will have a unique value to add here to trigger it.

Response Strategy - If you have worked with KornitX on a custom format for how the responses should be sent which does not match our generic format then you will have a unique value to add here to trigger it.

Push Min. Order Age (s) - An age in seconds that an order must be before the integration is allowed to pick it up, this can allow for customer service windows were order details might be able to be changed.

Authentication

Basic Authentication

Basic authentication can be used by populating the Auth Strategy field of the integration settings, with the following URI.

SL\Proxy2\Supplier\GenericApi\GenericApiHttpBasicAuthStrategy

This auth strategy uses the values entered into the Auth Username and Auth Password fields of the integration settings.

When this is set up, requests will include an authorization header. The value of the authorization header will be the Auth Username and Auth Password, separated by a colon, base 64 encoded and prefixed with “Basic “.

For example, if the Auth Username is “test” and the Auth Password is “test”, the authorization header will be sent as shown below.

Authorization: Basic dGVzdDp0ZXN0

OAuth 2.0 Authentication

OAuth 2.0 authentication can be used by populating the Auth Strategy field of the integration settings, with the following URI.

SL\Proxy2\Supplier\GenericApi\GenericApiOAuth2AuthStrategy

When using this auth strategy, the Auth Token URL field of the integration settings should be populated with the endpoint that token requests are made to.

The auth strategy uses the values entered into the Auth Username and Auth Password fields of the integration settings, as the Client ID and Client Secret respectively.

We will use these values, along with the grant_type client_credentials , to make a request to the token endpoint.

We will then use the token that is returned to us, in the authorization header when we push the order data to the endpoint specified in the Push URL field.

Authorization: Bearer [AUTH_TOKEN]

Supplier API for Kornit Printed Products

This API has additional settings and functionality when dealing with Kornit printed goods.

If you are producing goods on a Kornit Printer then our API can send more information allowing for better accuracy of placement, no manual operator intervention and reduced fixation usage and print time.

To enable this setting the

“Generic API” supplier integration needs to have “Enable QuickP Compatibility” enabled.
MACHINE on the products should be set to “Kornit DTG”
PRINT AREA on the products in the KornitX platform must have “Auto Crop” set to “centre” in the “Artwork Output” section

If these conditions are met then the printjob artwork the platform generates will be autocropped and details of offset, setup and table will be sent in the JSON data.

"offset_x": 62,

"offset_y": 165,

"setup": "AV HD6 Color STD",

"table": "StandardPallet"

Below is an example of the assets section of the section where these settings have been applied.

JSON

"assets": [
                {
                    "name": "AV HD6 Color STD_StandardPallet_95929329-output-5251025_1_62_165.png",
                    "description": "Front",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZC8D95787653BEDA9\/print-artwork\/single-5251025.png",
                    "quickp": {
                        "offset_x": 62,
                        "offset_y": 165,
                        "setup": "AV HD6 Color STD",
                        "table": "StandardPallet"
                    }
                },
                {
                    "name": "AV HD6 Color STD_StandardPallet_95929329-output-5251029_1_47_122.png",
                    "description": "Back",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZC8D95787653BEDA9\/print-artwork\/single-5251029.png",
                    "quickp": {
                        "offset_x": 47,
                        "offset_y": 122,
                        "setup": "AV HD6 Color STD",
                        "table": "StandardPallet"
                    }
                },
                {
                    "name": "thumbnail.png",
                    "description": "Default Thumbnail",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_94121395.png"
                },
                {
                    "name": "thumbnail-2346990.png",
                    "description": "Thumbnail Front",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_94121395_2346990.png"
                },
                {
                    "name": "thumbnail-2346991.png",
                    "description": "Thumbnail Back",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_94121395_2346991.png"
                },
                {
                    "name": "thumbnail-2346992.png",
                    "description": "Thumbnail Neck Label",
                    "url": "https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_94121395_2346992.png"
                }
            ]
        }

NOTE - the “name” field on kornit print areas contains the full naming convention so if the file is saved under this name and you have the setup names on your systems these files will drop straight in with the required settings ready to print.

Verifying the HMAC Header

Whilst optional, this step is highly recommended for security.

For each push request, a HMAC message digest can be calculated using the SHA256 algorithm with the request body as the input and the HMAC key displayed in the Generic API settings page.

The calculated HMAC message digest should match the value of the requests's X-CustomGateway-Hmac header.

If the values do not match then you should reject the push request.

Field Definitions

Order Object

Name	Type	Description
id	integer	Kornit^X order identifier
external_ref	string	A unique reference code that can be used to identify the order in your system.
company_ref_id	integer	The Sales Channel (Retailer) reference ID
secondary_company_ref_id	integer	The dropship connection reference ID
ref	string	unique Kornit^X reference
status	integer	Order Status ID
status_name	string	Order Status Name
sale_datetime	string	The date and time (must be UTC) of when the order was placed in the format `YYYY-MM-DD HH:MM:SS` (i.e. 2023-04-30 10:54:23)
required_dispatch_date	string	The required dispatch date for the order in the format `YYYY-MM-DD` (i.e. 2023-04-30)
creation_datetime	string	The creation date time for the order in the platform in the format `YYYY-MM-DD` (i.e. 2023-04-30)
customer_name	string	Customer's full name.
customer_email	string	Customer's contact email.
customer_telephone	string	Customer's contact telephone number.
shipping_company	string	Shipping address company.
shipping_address_1	string	Shipping address 1.
shipping_address_2	string	Shipping address 2.
shipping_address_3	string	Shipping address 3.
shipping_address_4	string	Shipping town or city.
shipping_address_5	string	Shipping region.
shipping_postcode	string	Shipping post or ZIP code.
shipping_country_code	string	ISO 3166-1 alpha-2 country code.
shipping_method	string	Shipping method.
shipping_carrier	string	Shipping carrier.
shipping_note_url	string	An optional URL for a specifying an external shipping note. If no value is provided then a basic shipping note will be generated. The URL must begin with either `http://` or `https://`.
billing_customer_name	string	Billing name.
billing_customer_email	string	Billing email address
billing_company	string	Billing address company.
billing_address_1	string	Billing address 1.
billing_address_2	string	Billing address 2.
billing_address_3	string	Billing address 3.
billing_address_4	string	Billing town or city.
billing_address_5	string	Billing region.
billing_postcode	string	Billing post or ZIP code.
billing_country_code	string	Billing country code.
coupon_code	string	Coupon code used on the orders purchase
payment_trans_id	string	Payment transaction identifier.
payment_type	string	Payment method used (i.e. stripe, paypal)
currency_code	string	The currency the order is in
shipping_price	string	if provided pricing information is here
shipping_price_inc_tax	string	if provided pricing information is here
shipping_tax_rate	string	if provided pricing information is here
is_free_of_charge	boolean	True if order was considered free of charge for example a reprint
attributes	array	An array of order level attributes such as TaxID or additional require information
has_error	boolean	True if the order is in an error state
error_message	string	If the order has an error the message is provided here
additional_info	string	additional information submitted by the retailer
items	array	An array of order item objects.

Order > Item Object

Name	Type	Description
id	integer	Unique Kornit^X ID for this item on this order
ref	string	Unique Kornit^X reference for this item on this order
order_id	integer	The order_id this item belongs to
external_ref	string	A reference code that can be used to identify the order item in your system.
sku	string	Product SKU.
mapped_sku	string	Suppliers SKU for this product mapped in the platform
description	string	Product description.
quantity	integer	Item quantity.
colour	string	Item colour.
size	string	Item size.
textual_product_id	integer	Determines which Catalog product the order item is for (can be used for either textual items or external URL items).
product_variant_id	integer	A specific ID for the variant of this product
type	integer	Item type code. Please see the Item Type Codes Table below and the “Which Order Item Type is Right for Me?“ page.
external_url	string	Only populated for external items (type 1). URL to an image which will be used for this item. This URL must be available until the order has been processed.
external_thumbnail_url	string	URL to a thumbnail of this product
print_job_ref	string	Required for print job items (type 2). A unique identifier linking this item to an already existing print job (created by a Kornit X Smartlink). The specified print job must have been created using a company ID which the current API key (URL parameter k) is permitted access to.
bundle_ref	string	A connecting reference for items which should be considered bundled
ecommerce > barcode	string	EAN / Barcode ID for this specific product
attributes	array	An array of item level attributes
status	integer	Item status ID
status_name	string	Item status name
artwork_barcode	string	Submitted with orders and only used if the artwork contains a barcode unique to this order item which can be workflow scanned
unit_sale_price	string	if provided pricing information is here
unit_sale_price_inc_tax	string	if provided pricing information is here
unit_cost_price	string	if provided pricing information is here
shipping_price	string	if provided pricing information is here
shipping_price_inc_tax	string	if provided pricing information is here

Order > Item > Assets Object

Assets contains all of the printable artwork as well as generated thumbnails for preview.

Name	Type	Description
url	string	A public URL to full-sized print ready artwork.
name	string	A public URL to a thumbnail of the artwork.
description	string	Print area name if an artwork output or a thumbnail description

Order > Item > Assets > Quickp Object

Quickp contains details specifically for items to be printed on Kornit printers.

Name	Type	Description
offset_x	integer	post auto-cropping this is the x offset value that should be used for artwork positioning
offset_y	integer	post auto-cropping this is the y offset value that should be used for artwork positioning
setup	string	based on production attributes this is the expected setup name in QuickP that should be used
table	string	based on production attributes this is the expected table name in QuickP that should be used

Order > Pdfs Object

Assets contains all of the printable artwork as well as generated thumbnails for preview.

Name	Type	Description
id	integer	Unique ID for this document
order_id	integer	The order_id this PDF belongs to
type	integer	ID for which type of document has been generated
url	string	The reference for this document
ref	string	A public URL to a thumbnail of the artwork.

Expected Responses

We expect one of the following HTTP status codes in response to each push we make to the endpoint provided by the user.

HTTP Status Code	Description
200	If the data was successfully received, respond with a 200 HTTP status code.
400	If there is a syntax issue with the data sent, respond with a 400 HTTP status code and a helpful error message in the response body.
401	If there is an authentication issue with the request, respond with a 401 HTTP status code.
500	If the server is unable to handle the request, respond with a 500 HTTP status code.