Supplier Integrations: Generic API

Supplier Integrations: Generic 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

  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.             },

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.

Status and Timings
Orders for companies using the Generic API integration enabled will come in with orders on the status of "received" and will be sent out every hour.

Still Need Help?
You can access our extensive knowledge base or raise a ticket with our technical support teams using the buttons below

View all help articles

Raise a support ticket

    • Related Articles

    • Production Integrations: Generic API

      Generic API Integration Help Like other production integrations this should be enabled on a PRODUCTION CENTRE company if it is required. For this particular integration all it requires is to be enabled, there are no other details to complete. This ...

    • Notification Integrations : Generic API

      Introduction Kornit X has built a notification integration to connect to a Generic API. This notifications integration will alert the customers whenever an order has been received, dispatched and delivered. Integration Setup In order to set this ...

    • Product Integration: Generic API

      Generic API Integration Help This product integration The point of this product integrations is that if your products were listed in a specific way for a marketplace the integrations can be set to map the products to the correct categories and that ...

    • Supplier Integrations: Generic Emailer

      Introduction This integration allows the Kornit X platform to send order data out to a Generic Emailer for fulfillers using that system to produce and dispatch items. Integration Setup When setting this up there are no details to add into the ...

    • Supplier Integrations | Generic Hotfolder

      Introduction This integration allows the Kornit X platform to send order data out to a Generic Hotfolder for fulfillers using that system to produce and dispatch items. Integration Setup When setting this up users will need to set their Filesystem ...