Skip to main content
Skip table of contents

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

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

KornitX 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 KornitX 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 KornitX ID for this item on this order

ref

string

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.