Aufträge

External channels

Creating orders from the outside

 

Prerequisites

You should have

  • a valid api channel-token enabled for api access & order management access
  • an api-client
  • at least one product-record stored in the Hublify PIM

 

Creating a new order

Some quick infos what happens usually inside Hublify whenever you create (aka inject) an order via the channel-api.

  • Hublify creates an order-record ...
    • with a Hublify internal (channel-specific) order-id
    • with all the other data you provide
       
  • Hublify creates a person-record. And assigns the order to this person.

 

Attention: The mandatory and available optional fields can vary depending on the targeted Hublify's system and channel-specific configuration!

 

... minimum data needed

The very minimum of data necessary to inject an order is basically

  • buying customer address (invoice-address equals delivery-address, if applicable)
  • one ordered product

 

Request URL

https://{your hublify url}/api/channel_10/order_create

Request parameter

{
    "fields": {
        "order": {
                                                 // Customer data
            "invoice_company": "",
            "invoice_gender": "male",            // "male|female|diverse|company"
            "invoice_firstname": "Max",
            "invoice_lastname": "Muster",
            "invoice_addrextra": "",
            "invoice_street": "Sample Street",
            "invoice_housenr": "1b",
            "invoice_zip": "22222",
            "invoice_town": "Hamburg",
            "invoice_country": "DE",

            "orderitems": [                      // Array of all order items.
                {
                    "oi_pcode": "EK00001",       // Product-Code. Product must be available in Hublify PIM.
                    "oi_quantity": 1,            // (optional, default: 1)
                }
            ]
        }
    }
}

Response

If your request was successful, you receive the current status and the hublify ids for this order and person.

{
    "status": true,
    "data": {
        "personid": "KCHN-00012345",               // Hublify internal customer-id created / assigned to.
        "orderid": "ACHN-00123456",                // Hublify internal order-id created.
        "o_orderid_external": null,                // NULL / empty, because no external order-id was provided in request.
        "order_state_code": "received",            // Hublify internal order-state code after order injection.
    }
}

Repsonse - Error

If your request failed, you receive a message detailing the error that occurred.

{
    "status": false,
    "msg": [
        {
            "type": "ERROR",
            "text": "Missing mandatory field 'orderitems'"
        }
    ]
}

 

... recommended data needed

Adding extra data, especially for later follow-up api-calls, callbacks and enhancing process stability is always a good idea!

Consider providing data, especially such as

  • your external system's:
    • customer-id
    • order-id

Hublify then can detect and avoid unwanted erroneous order injections.

 

Request URL

https://{your hublify url}/api/channel_10/order_create

Request parameter

{
    "fields": {
        "person": {
            "p_personid_external": "ABC000012",        // Provide your own unique customer-id here.

            "bday": "1973-01-22",
            "telephone": "+4940123456",
            "telephone_mobile": "+491601234567",
            "email": "max@muster.de",

        },
        "order": {
            "o_orderid_external": "CH00012345",        // Provide your own unique order-id for this order here.

            "invoice_company": "",
            "invoice_gender": "male",
            "invoice_firstname": "Max",
            "invoice_lastname": "Muster",
            "invoice_addrextra": "",
            "invoice_street": "Sample Street",
            "invoice_housenr": "1b",
            "invoice_zip": "22222",
            "invoice_town": "Hamburg",
            "invoice_country": "DE",

            "deliver_company": null,
            "deliver_gender": "female",
            "deliver_firstname": "Maxi",
            "deliver_lastname": "Muster",
            "deliver_addrextra": null,
            "deliver_street": "Second Street",
            "deliver_housenr": "2a",
            "deliver_zip": "11111",
            "deliver_town": "Berlin",
            "deliver_country": "DE",

            "orderitems": [
                {
                    "oi_pcode": "EK00001",
                    "oi_name": "Example Product 1",
                    "oi_type": "product",
                    "oi_quantity": 1,
                    "oi_price_single_brutto": 14.56,      // Single price including vat, per unit sold
                    "oi_vat_pct": 19                      // vat percentage-value
                },
                {
                    "oi_pcode": "PC0001",
                    "oi_name": "Example Product 2",
                    "oi_type": "product",
                    "oi_quantity": 2,
                    "oi_price_single_brutto": 12.34,
                    "oi_vat_pct": 19,
                }
            ]
        }
    }
}

If your request failed, you receive a message detailing the error that occured.

{
    "status": false,
    "msg": [
        {
            "type": "ERROR",
            "text": "Missing mandatory field 'orderitems'"
        }
    ]
}

 

If you sent the same order twice (based on the unique identifier you provided in o_orderid_external),
the second request will fail with a warning, but we will provide the data again.

(Updating already created orders will be possible in future! But that also depends on configured permission and order states.)
 

{
    "status": false,
    "data": {
        "personid": "KCHN-00012345",
        "orderid": "ACHN-00123456",
        "o_orderid_external": "CH00012345",
        "order_state_code": "received",
        "order_state_name": "Auftrag eingegangen"
    },
    "msg": [
        {
            "type": "WARNING",
            "text": "Order \"CH00012345\" was already injected and will be skipped."
        }
    ]
}

 

... full data provided

Following an example with more possible data provided.

Request URL

https://{your hublify url}/api/channel_10/order_create

Request parameter

{
    "fields": {
        "person": {
            "bday": "1973-01-22",
            "telephone": "+4940123456",
            "telephone_mobile": "+491601234567",
            "email": "max@muster.de",
            "p_personid_external": "ABC000012",

        },
        "order": {
            "o_orderid_external": "CH00012345",
            "st_label": "standard",
            "o_time_ordered": "2021-01-21 14:15:00",
            "o_comment": "Channel Order CH00012345, User ABC000012",
            "invoice_company": "",
            "invoice_gender": "male",
            "invoice_firstname": "Max",
            "invoice_lastname": "Muster",
            "invoice_addrextra": "",
            "invoice_street": "Sample Street",
            "invoice_housenr": "1b",
            "invoice_zip": "22222",
            "invoice_town": "Hamburg",
            "invoice_country": "DE",
            "deliver_company": null,
            "deliver_gender": "female",
            "deliver_firstname": "Maxi",
            "deliver_lastname": "Muster",
            "deliver_addrextra": null,
            "deliver_street": "Second Street",
            "deliver_housenr": "2a",
            "deliver_zip": "11111",
            "deliver_town": "Berlin",
            "deliver_country": "DE",
            "orderitems": [
                {
                    "oi_pcode": "EK00001",
                    "oi_name": "Example Product 1",
                    "oi_type": "product",
                    "oi_quantity": 1,
                    "oi_price_single_brutto": 14.56,
                    "oi_vat_pct": 19
                },
                {
                    "oi_pcode": "PC0001",
                    "oi_name": "Example Product 2",
                    "oi_type": "product",
                    "oi_quantity": 2,
                    "oi_price_single_brutto": 12.34,
                    "oi_vat_pct": 19,
                }
            ]
        }
    }
}

Response

See in examples above the possible responses.