Supplier Integration | Generic API

Supplier Integration | Generic API

Introduction

The Order Push API from Kornit X is our generic Order Manager API allowing us to POST order data in JSON format (matching the structure of our standard orders in API) to an endpoint nominated by a supplier. This is a cheaper alternative to Kornit X producing a custom API integration for suppliers that may have developers in house that could create such an endpoint and take in data in this format.

The below video details how this type of integration works.


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.

Example JSON

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

  2. {
  3.     "id":0,
  4.     "company_ref_id":Sales Channel Company Ref ID,
  5.     "secondary_company_ref_id":"Dropship Connection Ref ID",
  6.     "ref":"unique Kornit X reference",
  7.     "status":1,
  8.     "status_name":"Received",
  9.     "shipping_company":"",
  10.     "shipping_address_1":"",
  11.     "shipping_address_2":"",
  12.     "shipping_address_3":"",
  13.     "shipping_address_4":"",
  14.     "shipping_address_5":"",
  15.     "shipping_postcode":"",
  16.     "shipping_country":"",
  17.     "shipping_country_code":"ISO 2 Country Code",
  18.     "billing_company":"",
  19.     "billing_address_1":"",
  20.     "billing_address_2":"",
  21.     "billing_address_3":"",
  22.     "billing_address_4":"",
  23.     "billing_address_5":"",
  24.     "billing_postcode":"",
  25.     "billing_country":"",
  26.     "customer_name":"",
  27.     "customer_telephone":"",
  28.     "customer_telephone_mobile":"",
  29.     "sale_datetime":"YYYY-MM-DD HH:MM:SS",
  30.     "external_ref":"Sales Channel order reference",
  31.     "has_been_completed":false,
  32.     "completion_datetime":"0000-00-00 00:00:00",
  33.     "shipping_method":"",
  34.     "customer_email":"",
  35.     "shipping_carrier":"",
  36.     "shipping_tracking":"",
  37.     "shipping_note_url":"Sales Channel Generate Paperwork URL",
  38.     "payment_trans_id":"",
  39.     "payment_type":"",
  40.     "creation_datetime":"YYYY-MM-DD HH:MM:SS",
  41.     "additional_info":"",
  42.     "has_error":false,
  43.     "error_message":"",
  44.     "required_dispatch_date":"0000-00-00",
  45.     "billing_customer_name":"",
  46.     "billing_customer_email":"",
  47.     "billing_customer_telephone":"",
  48.     "shipping_price":0,
  49.     "shipping_price_inc_tax":0,
  50.     "shipping_tax_rate":0,
  51.     "is_urgent":false,
  52.     "coupon_code":"",
  53.     "currency_code":null,
  54.     "is_free_of_charge":true,
  55.     "company_external_ref":"",
  56.     "items":[
  57.         {
  58.             "id":0,
  59.             "sale_vat_rate":0,
  60.             "external_ref":"Sales Channels unique item ref",
  61.             "ref":"KornitX unique item ref",
  62.             "order_id":0,
  63.             "sku":"",
  64.             "mapped_sku":"",
  65.             "description":"",
  66.             "colour":"",
  67.             "size":"",
  68.             "quantity":1,
  69.             "type":2,
  70.             "print_job_id":0,
  71.             "print_job_promise_ref":"",
  72.             "external_url":"",
  73.             "external_thumbnail_url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/product-state\/ZZ9BC2105A64DF76C8-thumbnail.png",
  74.             "status":1,
  75.             "print_on_demand_ref":"",
  76.             "plain_stock_item_ref":"",
  77.             "license":"",
  78.             "license_percentage":"",
  79.             "unit_sale_price":0,
  80.             "unit_sale_price_inc_tax":0,
  81.             "unit_cost_price":0,
  82.             "shipping_price":0,
  83.             "shipping_price_inc_tax":0,
  84.             "bundle_ref":"",
  85.             "textual_product_id":"0",
  86.             "product_variant_id":"0",
  87.             "quantity_batched":1,
  88.             "quantity_dispatched":0,
  89.             "stock_request_id":null,
  90.             "artwork_barcode":"0",
  91.             "quantity_consolidated":0,
  92.             "product_state_id":null,
  93.             "status_name":"Received",
  94.             "ecommerce":{
  95.                 "barcode":""
  96.             },
  97.             "attributes":[
  98.             {
  99.                "name":"",
  100.                "value":""
  101.               },
  102.             ],
  103.             "assets":[
  104.                 {
  105.                     "name":"output-5251025.jpg",
  106.                     "description":"Front",
  107.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZ759C450D64DF76C8\/print-artwork\/single-5251025.jpg"
  108.                 },
  109.                 {
  110.                     "name":"output-merged-j1hdhnrfmg265vh.jpg",
  111.                     "description":"Front & Neck",
  112.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/print-job\/ZZ759C450D64DF76C8\/print-artwork\/merged-302443.jpg"
  113.                 },
  114.                 {
  115.                     "name":"thumbnail.png",
  116.                     "description":"Default Thumbnail",
  117.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340.png"
  118.                 },
  119.                 {
  120.                     "name":"thumbnail-2254325.png",
  121.                     "description":"Thumbnail Front",
  122.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254325.png"
  123.                 },
  124.                 {
  125.                     "name":"thumbnail-2254326.png",
  126.                     "description":"Thumbnail Back",
  127.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254326.png"
  128.                 },
  129.                 {
  130.                     "name":"thumbnail-2254329.png",
  131.                     "description":"Thumbnail Neck Label",
  132.                     "url":"https:\/\/s3-eu-west-1.amazonaws.com\/assets.easypromo3d.com\/output\/thumbnails\/print-jobs\/514797_90677340_2254329.png"
  133.                 }
  134.             ]
  135.         }
  136.     ],
  137.       "pdfs":[
  138.       {
  139.       "id":0,
  140.       "order_id":0,
  141.       "type":1,
  142.       "url":"https:\/\/s3-eu-west-1.amazonaws.com\/generated-assets-gateway3d-com\/misc\/html2pdf\/cc4c1c951eb1d6555401b628132a83a00.pdf",
  143.       "ref":"5pr6wrmrm6l49n8khzb1",
  144.       "is_outdated":false
  145.     }
  146.     ],
  147.     "shipments":[
  148.     ]

  150. }

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
  2. "attributes":[
  3.             {
  4.                "name":"TaxID",
  5.                "value":"123456789"
  6.             },
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
  2. "attributes":[
  3.             {
  4.                "name":"TaxID",
  5.                "value":"123456789"
  6.             },

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

  1. Enabled - Yes / No for if the integration is enabled and allowed to run
  2. Dispatch Date Filter - If enabled orders will only be processed on their “Required Dispatch Date” so assumes same day turnaround of production.
  3. Auto Ship - If enabled orders will be automatically classed as shipped when passed into the receiving supplier system
  4. Generate Documents - If you need to get Kornit X generated Dispatch or Address lables 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 Dispatch (meant for packing slips) or Address (meant for basic address labels) and any PDFs generated will be sent in the "pdfs" section of the JSON body.
  5. Enable Personalisation Text Elements - Enable this toggle option to on and you can ensure text personalisation can be sent within the payload, this has been detailed in more detail further down in this article. 
  6. Email Errors To - Any errors in running this integration will be sent to this email address.
  7. 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.
  8. Push URL - Your API Endpoint should be added here.
  9. 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.
  10. 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.
  11. Artwork Format - PNG, JPEG, TIFF, PDF dropdown.
  12. 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).
  13. Auth Username - If a basic authentication username is needed, add it here.
  14. Auth Password - If a basic authentication password is needed, add it here.
  15. 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.
  16. 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.
  17. 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.
  18. 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.

Personalisation Text Elements Array

With the Generic API supplier integration you can send through text elements within the array, an example of how this will appears is on the extraction below taken from the full payload. 

"personalisation_text-elements": [
      {
            "area_name": "Name",
            "area_position_x": 171,
            "area_position_y": 270,
            "final_text": "TEST",
            "size": 38     
      },
{
      "area_name": "Duplicated from Name",
      "area_position_x": 635,
      "area-position_y": 270,
      "final_text": "TEST",
      "size": 38
      }
]
}
]
This feature is a toggle option that is disabled by default. 

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.

Updated Generic API Supplier Integration Features

At KornitX we have continued to develop updates for variants and this is due to the fact we pride ourselves on constant evolution and the release of new features and enhancements every week. We have detailed each new variant enhancement below. If you are interested in knowing what features arrive, they will be continually updated within the "Core Platform Feature Updates" Article - CLICK HERE
This will continue to be updated below whenever a new enhancement is rolled out to improve the Generic API Supplier Integration, a time stamp will be labelled with each feature

Option to not send Blank Print Areas through Orders
The Generic API Supplier Integration has been updated to exclude any blank print areas produced whenever orders are placed through the Generic API. The benefit of this update means that no longer will fulfillers generate blank print areas for orders, only printed artwork will be included within order details. 

The platform will automatically enable this but users can disable or re-enable if they wish by enabling the "Do Not Send Blank Print Areas" slider shown below. 


Generic API Now Supports OAUTH2
The Generic API integration now supports OAUTH2 which was included to ensure we are using the most up to date version of OAUTH to ensure our security is up to date.

To use this
Auth Strategy = SL\Proxy2\Supplier\GenericApi\GenericApiOAuth2AuthStrategy
Auth Username = Client ID
Auth Password = Client Secret

    • Related Articles

    • Product Integration | Generic API

      Introduction This article has been created to show how to setup the Product integration Kornit X has built to connect to Generic API.  Setup To setup the Generic API integration, please head to your category and within and within the advanced ...

    • Supplier Integration | DigitalPCS

      Introduction This article has been created to show how to setup the supplier integration Kornit X has built to connect to DigitalPCS.  Setup To setup the DigitalPCS integration, please head to your company and within the advanced settings head to ...

    • Supplier Integration | Inkthreadable

      Introduction This article has been created to show how to setup the supplier integration Kornit X has built to connect to Inkthreadable.  Setup To setup the Inkthreadable integration, please head to your company and within the advanced settings head ...

    • Supplier Integration | Printful

      Introduction This article has been created to show how to setup the supplier integration Kornit X has built to connect to Printful.  Setup To setup the Printful integration, please head to your company and within the advanced settings head to ...

    • Supplier Integration | OnPrintShop

      Introduction This article has been created to show how to setup the supplier integration Kornit X has built to connect to OnPrintShop.  Setup To setup the OnPrintShop integration, please head to your company and within the advanced settings head to ...