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.