Order Push API

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The purpose of this document is to describe how Very will create orders in Hemi.

The flow of creating orders is in the opposite way and Very will be creating order directly into our system. Thus we have to build a listener which accept orders in specific format.

”The Order Push API” allows a supplier to configure a 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.

Setup

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

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

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.

Sample way of doing this:

$hmac = hash_hmac('sha256', file_get_contents('php://stdin'), $key);

if(!hash_equals($hmac, getHeader('X-CustomGateway-Hmac')))
{
    throw new \Exception('HMAC mismatch');
}

”

Sample payload:

{
  "id": 48292893,
  "company_ref_id": 123456,
  "secondary_company_ref_id": "789012",
  "ref": "BA5081446450F3FE",
  "status": 1,
  "shipping_company": "",
  "shipping_address_1": "123 Test Street",
  "shipping_address_2": "",
  "shipping_address_3": "",
  "shipping_address_4": "Test",
  "shipping_address_5": "",
  "shipping_postcode": "SK10 2XR",
  "shipping_country": "United Kingdom",
  "shipping_country_code": "GB",
  "billing_company": "",
  "billing_address_1": "",
  "billing_address_2": "",
  "billing_address_3": "",
  "billing_address_4": "",
  "billing_address_5": "",
  "billing_postcode": "",
  "billing_country": "United Kingdom",
  "customer_name": "Paul Test",
  "customer_telephone": "",
  "customer_telephone_mobile": "",
  "sale_datetime": "2023-05-02 11:14:12",
  "external_ref": "L281223899999-L8-PH",
  "has_been_completed": false,
  "completion_datetime": "0000-00-00 00:00:00",
  "has_pdf_been_queued": false,
  "has_pdf_been_completed": false,
  "shipping_method": "Next Day",
  "customer_email": "paul.heseltine@kornit.com",
  "shipping_carrier": "DPD",
  "shipping_tracking": "",
  "shipping_note_url": "",
  "payment_trans_id": "",
  "payment_type": "",
  "has_initial_confirmation_email_been_sent": false,
  "has_shipping_confirmation_email_been_sent": false,
  "creation_datetime": "2023-05-02 11:29:02",
  "additional_info": "",
  "has_error": false,
  "error_message": "",
  "required_dispatch_date": "0000-00-00",
  "is_status_callback_pending": false,
  "stock_request_id": 0,
  "status_callback_attempts": 0,
  "status_callback_next_retry": "0000-00-00 00:00:00",
  "consolidate": false,
  "has_been_invoiced": false,
  "billing_customer_name": "",
  "billing_customer_email": "",
  "billing_customer_telephone": "",
  "shipping_price": 6,
  "shipping_price_inc_tax": 0,
  "shipping_tax_rate": 0,
  "is_urgent": false,
  "tag": "",
  "pos_user_id": null,
  "coupon_code": "",
  "currency_code": null,
  "is_free_of_charge": false,
  "status_name": "Received",
  "company_external_ref": "",
  "items": [
    {
      "id": 85632673,
      "sale_vat_rate": 0.2,
      "external_ref": "POS-EF8FE5",
      "ref": "8D2BD93C6450F3FE",
      "order_id": 48292893,
      "sku": "11508",
      "mapped_sku": "11508",
      "description": "Slim Fit White Shirt",
      "colour": "",
      "size": "",
      "quantity": 2,
      "type": 4,
      "print_job_id": 0,
      "print_job_promise_ref": "",
      "external_url": "",
      "external_thumbnail_url": "",
      "status": 1,
      "print_on_demand_ref": "",
      "plain_stock_item_ref": "",
      "license": "",
      "license_percentage": "",
      "unit_sale_price": 69.99,
      "unit_sale_price_inc_tax": 0,
      "unit_cost_price": 12.48,
      "shipping_price": 0,
      "shipping_price_inc_tax": 3,
      "bundle_ref": "",
      "textual_product_id": "11791111",
      "product_variant_id": null,
      "quantity_batched": 0,
      "quantity_dispatched": 0,
      "stock_request_id": null,
      "artwork_barcode": "",
      "quantity_consolidated": 0,
      "product_state_id": null,
      "status_name": "Received",
      "attributes": [],
      "assets": []
    },
    {
      "id": 85632674,
      "sale_vat_rate": 0.2,
      "external_ref": "POS-961B06",
      "ref": "46C958316450F3FE",
      "order_id": 48292893,
      "sku": "11655",
      "mapped_sku": "11655",
      "description": "Tailored Fit White Shirt",
      "colour": "",
      "size": "",
      "quantity": 1,
      "type": 4,
      "print_job_id": 0,
      "print_job_promise_ref": "",
      "external_url": "",
      "external_thumbnail_url": "",
      "status": 1,
      "print_on_demand_ref": "",
      "plain_stock_item_ref": "",
      "license": "",
      "license_percentage": "",
      "unit_sale_price": 59.99,
      "unit_sale_price_inc_tax": 0,
      "unit_cost_price": 10.99,
      "shipping_price": 0,
      "shipping_price_inc_tax": 0,
      "bundle_ref": "",
      "textual_product_id": "11792222",
      "product_variant_id": null,
      "quantity_batched": 0,
      "quantity_dispatched": 0,
      "stock_request_id": null,
      "artwork_barcode": "",
      "quantity_consolidated": 0,
      "product_state_id": null,
      "status_name": "Received",
      "attributes": [],
      "assets": []
    }
  ],
  "pdfs": [
    {
      "id": 32511879,
      "order_id": 48292893,
      "type": 1,
      "url": "https://s3-eu-west-1.amazonaws.com/xxx.pdf",
      "ref": "mjjkzj7fdf6trmwwx0jf",
      "is_outdated": false
    }
  ],
  "shipments": []
}

Mapping: N/A means we do not map this field anywhere in Hemi. Please note not all fields may be pushed from KornitX.

Since their payload is limited we have to make sure any missing information which is not provided by Very and is mandatory for Hemi to be filled.

Also the same is the case with the validations and if we receive and order with missing or duplicate:

Hemi Field

Orders > Marketplace Order ID

Product In Order > Item Order Line ID

Orders > External Trans ID

We want to return and error and do not allow to create the order.

If any of the mandatory information as per abstraction is missing we want to set the Orders > Status = Incomplete

<v1.5> We also need to have a grace period of 30 minutes in which we keep the order on ‘Pending’ status