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

{
    "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

"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 - If the dropship is set as a dropship delegate on a fulfiller company, enabling this setting will allow all dropships that are connected to the fulfiller, to use the integration set up on the dropship delegate company. In effect, this allows a single integration to serve multiple dropships.

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.

Enable QuickP Compatibility - See the “Supplier API for Kornit Printed Products” section below.

Include Branding Attributes - This option will include details of any branding attributes associated with the items in the order. This appears in the item data, in an array named branding_attributes which is within an object named ecommerce. Each object in the array includes attribute_set_name, group, value, sku, spec, description and image fields.

Enable Personalisation Text Elements - This option will include details of any text personalisation associated with the items in the order. This appears in the item data, in an array named personalisation_text_elements and each object in the array includes area_name, area_position_x, area_position_y, final_text and size fields.

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.

Auth Token URL - The endpoint that token requests should be made to (only relevant when the OAuth 2.0 data strategy is in use).

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. See the Authentication section below for details on the standard authentication strategies that we offer.

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.

"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

Order > Item Object

Order > Item > Assets Object

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

Order > Item > Assets > Quickp Object

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

Order > Pdfs Object

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

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.