Import Sales Order

Import Sales Orders

To push orders into Microsoft Business Central the URL POST http://<serer name>:<odata port>/<service instance name>/api/BEterna/Import/v2.0/companies(<company system id>)/orders?$filter=webshopChannelCode eq '<webshop channel code>' can be used. The filter on the webshop channel code is mandatory. It must be called with a JSON structure to create an order:

{
   "webshopChannelCode" : "B2C",
   "orderId" : "12345",
   "orderType" : "1",
   "orderDate" : "2022-05-27 13:30:00",
   "subclient" : "",
   "customerIP" : "172.16.11.11",
   "language" : "DEU",
   "testOrder" : "0",
   "registeredCustomer" : "1",
   "adChannel" : "",
   "adMedia" : "",
   "subtotal" : "10000",
   "totalAmount" : "10400",
   "tax" : "1661",
   "currency" : "EUR",
   "giftWrapped" : "0",
   "customsDuty" : "0",
   "ustIdNo" : "",
   "customerComment" : "",
   "warhouseShipmentDate" : "",
   "customerNo" : "12345",
   "contactNo" : "12345",
   "salutation" : "Herr",
   "title" : "",
   "name" : "Tester",
   "name2" : "Test",
   "street" : "Teststraße",
   "housenumber" : "1",
   "addressSecondLine" : "",
   "zip" : "12345",
   "city" : "Testort",
   "isoCountry" : "DE",
   "state" : "",
   "email" : "test@test.com",
   "phone" : "",
   "customerNoBilling" : "12345",
   "contactNoBilling" : "12345",
   "salutationBilling" : "Herr",
   "titleBilling" : "",
   "nameBilling" : "Tester",
   "name2Billing" : "Test",
   "streetBilling" : "Teststraße",
   "housenumberBilling" : "1",
   "addressSecondLineBilling" : "",
   "zipBilling" : "12345",
   "cityBilling" : "Testort",
   "isoCountryBilling" : "DE",
   "stateBilling" : "",
   "emailBilling" : "test@test.com",
   "phoneBilling" : "",
   "salutationShipping" : "Herr",
   "titleShipping" : "",
   "nameShipping" : "Tester",
   "name2Shipping" : "Test",
   "streetShipping" : "Teststraße",
   "housenumberShipping" : "1",
   "addressSecondLineShipping" : "",
   "zipShipping" : "12345",
   "cityShipping" : "Testort",
   "isoCountryShipping" : "DE",
   "stateShipping" : "",
   "phoneShipping" : "",
   "shippingMethodId" : "1",
   "shippingCosts" : "400",
   "paymentMethodId" : "1",
   "transactionId" : "",
   "paymentCosts" : "0",
   "orderLines" : [
      {
         "id" : "1",
         "type" : "1",
         "itemNumber" : "12345",
         "variant" : "",
         "singlePrice" : "10000",
         "amount" : "1",
         "voucherCode" : "",
         "discountAmount" : "0",
         "reservationRequestLocation" : "",
         "lineDescription" : "",
         "lineDescription2" : "",
         "warhouseShipmentDate" : ""
      }
   ]
}

If a field is empty it can be left out in the JSON structure. The header fields have the following meaning:

field	data type	content
`webshopChannelCode`	Text[20]	Webshop Channel Code
`orderId`	Text[20]	distinct ID of the order
`orderType`	Text[30]	type of the order, actually only the value `1` is supported
`orderDate`	Text[30]	order date and time in the form `2022-05-01 10:00:00`
`subclient`	Text[30]	the subclient who placed the order, actually not used
`customerIP`	Text[30]	IP address of the customer, actually not used
`language`	Text[3]	language code of the customer
`testOrder`	Text[1]	`0` or `1`, actually not used
`registeredCustomer`	Text[1]	`1` if the customer is registered and must exist, `0` if it is a guest order
`adChannel`	Text[30]	advertising channel the customer came from, actually not used
`adMedia`	Text[30]	advertising media the customer came from, actually not used
`subtotal`	Text[30]	the sum of all order lines in the least currency unit, e.g. Cent
`totalAmount`	Text[30]	the total amount of the order including shipping an payment costs in the header data in the least currency unit
`tax`	Text[30]	the VAT amount of the order in the least currency unit
`currency`	Text[10]	the ISO3 currency code of the order
`giftWrapped`	Text[1]	`0` or `1`, actually not used
`customsDuty`	Text[30]	customs duties for the order in the least currency unit, actually not used
`ustIdNo`	Text[20]	VAT identifier of the customer if needed
`customerComment`	Text[80]	special customer comment for the order
`warhouseShipmentDate`	Text[20]	shipment date of the order, can be empty, is used for all order lines that do not have an own shipment date
`customerNo`	Text[20]	customer no. of the order, must be filled, even if the customer is new
`contactNo`	Text[20]	contact no. of the order, must be filled and exist
`salutation`	Text[30]	salutation of the customer, actually not used
`title`	Text[30]	title of the customer, actually not used
`name`	Text[50]	last name of the customer
`name2`	Text[50]	first name of the customer, can be empty
`street`	Text[50]	address (street location) of the customer
`housenumber`	Text[10]	house number of the customer
`addressSecondLine`	Text[50]	second line of the customer address
`zip`	Text[20]	zip code of the customer
`city`	Text[30]	city of the customer
`isoCountry`	Text[10]	the ISO2 country code of the customer
`state`	Text[30]	the state of the customer, is only useful for U.S. orders
`email`	Text[80]	the email address of the customer
`phone`	Text[30]	the phone no. of the customer
`customerNoBilling`	Text[20]	billing customer no. of the order, must be filled, even if there is no different billing customer
`contactNoBilling`	Text[20]	billing contact no. of the order, must be filled and exist
`salutationBilling`	Text[30]	salutation of the billing customer, actually not used
`titleBilling`	Text[30]	title of the billing customer, actually not used
`nameBilling`	Text[50]	last name of the billing customer
`name2Billing`	Text[50]	first name of the billing customer, can be empty
`streetBilling`	Text[50]	address (street location) of the billing customer
`housenumberBilling`	Text[10]	house number of the billing customer
`addressSecondLineBilling`	Text[50]	second line of the billing customer address
`zipBilling`	Text[20]	zip code of the billing customer
`cityBilling`	Text[30]	city of the billing customer
`isoCountryBilling`	Text[10]	the ISO2 country code of the billing customer
`stateBilling`	Text[30]	the state of the billing customer, is only useful for U.S. orders
`emailBilling`	Text[80]	the email address of the billing customer
`phoneBilling`	Text[30]	the phone no. of the billing customer
`salutationShipping`	Text[30]	salutation of the shipping address, actually not used
`titleShipping`	Text[30]	title of the shipping address, actually not used
`nameShipping`	Text[50]	last name of the shipping address
`name2Shipping`	Text[50]	first name of the shipping address, can be empty
`streetShipping`	Text[50]	address (street location) of the shipping address
`housenumberShipping`	Text[10]	house number of the shipping address
`addressSecondLineShipping`	Text[50]	second line of the shipping address
`zipShipping`	Text[20]	zip code of the shipping address
`cityShipping`	Text[30]	city of the shipping address
`isoCountryShipping`	Text[10]	the ISO2 country code of the shipping address
`stateShipping`	Text[30]	the state of the shipping address, is only useful for U.S. orders
`emailShipping`	Text[80]	the email address of the shipping address
`phoneShipping`	Text[30]	the phone no. of the shipping address
`shippingMethodId`	Text[30]	the shipping method of the order, must be one of the shipping ids assigned to the webshop channel
`shippingCosts`	Text[30]	the shipping costs of the order in the least currency unit, if not transfered as an order line
`paymentMethodId`	Text[30]	the payment method of the order, must be one of the payment ids assigned to the webshop channel
`transactionId`	Text[30]	The transaction Id distinctively identifieing the electronic payment of the order, must be filled if configured for the payment method
`paymentCosts`	Text[30]	additional payment costs for the order in the least currency unit, if not transfered as an order line

There can be one or more order lines. They are transfered using a JSON array. The following field can be defined for a single order line:

field	data type	content
`id`	Integer	distinct identifier of the line in the order, must be distict per order
`type`	Text[30]	must be one of the following values: `1` item line, `2` voucher sale, `3` discount, `4` shipping costs, `5` voucher cashing in, `6` payment costs, which values are possible depends on the setup of the webshop channel
`itemNumber`	Text[20]	the item number for item lines, must be empty otherwise
`variant`	Text[10]	otionally the item variant code for item lines, must be empty otherwise
`singlePrice`	Text[30]	unit price of the line in the least currency unit
`amount`	Text[30]	the quantity of the line for item lines, otherwise ist must always be `1`
`voucherCode`	Text[30]	the voucherCode for voucher sale and cashing in, otherwise is must be empty
`discountAmount`	Text[30]	the discountAmount of the orderline in the least currency unit, the discount amount is for the whole order line and is not depending on the quantity
`reservationRequestLocation`	Text[10]	not used, must be empty
`lineDescription`	Text[250]	the line description of the order line, if empty, the standard line description of business central is used (e.g. item description)
`lineDescription2`	Text[250]	the line description 2 of the order line, if empty, the standard line description 2 of business central is used (e.g. item description 2)
`warhouseShipmentDate`	Text[20]	shipment date of the order line, can be empty

The request is answered with a JSON structure containing all the header data that were transfered. If the answer should contain the transfered order lines as well, the $expand=orderLines can be attached to the URL and the answer contains the full order data that were transfered:

{
   "@odata.context": "http://betlpznb207:7268/BC/api/BEterna/Import/v2.0/$metadata#companies(c309b416-2edd-ec11-bb45-000d3a392167)/orders/$entity",
   "@odata.etag": "W/\"JzE5OzczMTc3ODQ0MzEzODk0ODgxMTIxOzAwOyc=\"",
   "systemId": "826cd7ec-fbdf-ec11-9978-f2a09b5afc21",
   "webshopChannelCode": "B2C",
   "orderId": "12345",
   "orderType": "1",
   "orderDate": "2022-05-27 13:30:00",
   "subclient": "",
   "customerIP": "172.16.11.11",
   "language": "DEU",
   "testOrder": "0",
   "registeredCustomer": "1",
   "adChannel": "",
   "adMedia": "",
   "subtotal": "10000",
   "totalAmount": "10400",
   "tax": "1661",
   "currency": "EUR",
   "giftWrapped": "0",
   "customsDuty": "0",
   "ustIdNo": "",
   "customerComment": "",
   "warhouseShipmentDate": "",
   "customerNo": "12345",
   "contactNo": "12345",
   "salutation": "Herr",
   "title": "",
   "name": "Tester",
   "name2": "Test",
   "street": "Teststraße",
   "housenumber": "1",
   "addressSecondLine": "",
   "zip": "12345",
   "city": "Testort",
   "isoCountry": "DE",
   "state": "",
   "email": "test@test.com",
   "phone": "",
   "customerNoBilling": "12345",
   "contactNoBilling": "12345",
   "salutationBilling": "Herr",
   "titleBilling": "",
   "nameBilling": "Tester",
   "name2Billing": "Test",
   "streetBilling": "Teststraße",
   "housenumberBilling": "1",
   "addressSecondLineBilling": "",
   "zipBilling": "12345",
   "cityBilling": "Testort",
   "isoCountryBilling": "DE",
   "stateBilling": "",
   "emailBilling": "test@test.com",
   "phoneBilling": "",
   "salutationShipping": "Herr",
   "titleShipping": "",
   "nameShipping": "Tester",
   "name2Shipping": "Test",
   "streetShipping": "Teststraße",
   "housenumberShipping": "1",
   "addressSecondLineShipping": "",
   "zipShipping": "12345",
   "cityShipping": "Testort",
   "isoCountryShipping": "DE",
   "stateShipping": "",
   "phoneShipping": "",
   "shippingMethodId": "1",
   "shippingCosts": "400",
   "paymentMethodId": "1",
   "transactionId": "",
   "paymentCosts": "0",
   "orderLines": [   {
      "@odata.etag": "W/\"JzE4OzcxNTE0NzU1MzU0NjMzNDEyOTE7MDA7Jw==\"",
      "systemId": "836cd7ec-fbdf-ec11-9978-f2a09b5afc21",
      "id": 1,
      "type": "1",
      "itemNumber": "12345",
      "variant": "",
      "singlePrice": "10000",
      "amount": "1",
      "voucherCode": "",
      "discountAmount": "0",
      "reservationRequestLocation": "",
      "lineDescription": "",
      "lineDescription2": "",
      "warhouseShipmentDate": ""
   }]
}