Data Exchange

Using Softera.eCom app, you will be able to create items, customers, orders and update listings from the e-shop using API. In this section, the general description of these processes are provided with examples of request addresses and bodies. The information, that must be send in requests and the needed Softera.eComm setup must be discussed in advance with the client, thus assuring that the process fits the customer needs.

This section only describes the requests that are used to send information to BC from e-shop. The main information, that the e-shop can get from BC is described in the later section „Examples of Exported Data“.

ITEM CREATION

Before creating items from the e-shop, these steps must be done:

• In the needed „eCom Shop“ card, the setting „Create Items“ must be turned on.
• In the needed „eCom Shop“ card, the „Default Item Template“ must be selected. This template will be used when no other will be specified.

The intermediate list "eCom External Items" is used to create BC items. This list contains the information received from the e-shop. This information is later used to create a BC item. The fields in this list, that are not the same as standard BC item card fields, are detailed below.

Additional information about the external item can be found by pressing:

• Units of Measure
• Item References
• Translations

From this list, the BC item card creation can be initialized by the function “Create Item“. If an error occurred during the creation, it will be shown in the list or by pressing “Show Error“. If the BC item card is created successfully, it can be opened by pressing “Item Card“.

Creating item via API consists of two steps:

1. Using the endpoint „eComExternalItems“ the information about the item is sent to BC

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalItems

Request body example:
{
"eComId": "",
"shopCode": "",
"description": "",
"description2": "",
"baseUnitOfMeasure": "",
"itemCategoryCode": "",
"netWeight": 0.00,
"grossWeight": 0.00,
"tariffNo": "",
"countryRegionOfOriginCode": "",
"vendorNo": "",
"vendorItemNo": "",
"templateCode": "",
"additionalInfo1": "",
"additionalInfo2": "",
"additionalInfo3": "",
"additionalInfo4": "",
"additionalInfo5": "",
"additionalInfo6": "",
"additionalInfo7": "",
"additionalInfo8": "",
"additionalInfo9": "",
"additionalInfo10": "",
"eComExtItemUnitsOfMeasure": [
{
"code": "",
"qtyPerUnitOfMeasure": 0.00,
"length": 0.00,
"width": 0.00,
"height": 0.00,
"cubage": 0.00,
"weight": 0.00
}
],
"eComExtItemReferences": [
{
"referenceNo": "",
"unitOfMeasure": "",
"description": "",
"description2": "",
"startingDate": "",
"endingDate": ""
}
],
"eComExtItemTranslations": [
{
"languageCode": "",
"description": ""
}
]
}

2. Using the endpoint’s „eComExternalItems“ function „ Microsoft.NAV.createBcItem“ the creation process of BC item is initialized. For this, the ID of the created „eCom External Item" is needed. This ID is provided in the first step request answer body.

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalItems({{externalItemID}})/Microsoft.NAV.createBcItem

If the creation is successful, the request answer will contain „Created“. If not – an error message will be shown.

CUSTOMER CREATION

Before creating customers from the e-shop, these steps must be done:

• In the needed „eCom Shop“ card, the setting „Create Customers“ must be turned on.
• For the needed e-shop, the list „eCom Shop Customer Template Setup“ must be filled. These Templates will be used in creating the BC customer cards.

The intermediate list "eCom External Customers" is used to create BC customers. This list contains the information received from the e-shop. This information is later used to create a BC customer. The fields in this list, that are not the same as standard BC customer card fields, are detailed below.

From this list, the BC customer card creation can be initialized by the function “Create Customer“. If an error occurred during the creation, it will be shown in the list or by pressing “Show Error“. If the BC customer card is created successfully, it can be opened by pressing “Customer Card“.

Creating customers via API consists of two steps:

1. Using the endpoint „eComExternalCustomers“ the information about the customer is sent to BC

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalCustomers

Request body example:
{
"eComId": "",
"shopCode": "",
"isBusiness": false,
"registrationNo": "",
"vatRegistrationNo": "",
"name": "",
"name2": "",
"address": "",
"address2": "",
"postCode": "",
"city": "",
"countryCode": "",
"eMail": "",
"phoneNo": "",
"additionalInfo1": "",
"additionalInfo2": "",
"additionalInfo3": "",
"additionalInfo4": "",
"additionalInfo5": ""
}

2. Using the endpoint’s „eComExternalCustomers“ function „Microsoft.NAV.createBcCustomer“ the creation process of BC customer is initialized. For this, the ID of the created „eCom External Customer" is needed. This ID is provided in the first step request answer body.

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalCustomers({{externalCustomerID}})/Microsoft.NAV.createBcCustomer

If the creation is successful, the request answer will contain „Created“. If not – an error message will be shown.

ORDER CREATION

Before creating orders from the e-shop, all necessary settings, products and buyers must be set. The most important steps:

• Fill „eCom setup“.
• Fill „eCom Shops“ setup.
• Setup which Items will be used in the e-shop.
• Setup which Customer will be used in the e-shop.
• Setup and provide eCom IDs that will be used in the orders.
• Decide what information must be imported into e-shop from BC and when.
• Decide what information must be exported from e-shop to BC and when.

The intermediate order "eCom order" and "eCom return order" are used to create BC sales orders. These orders contain the information received from the e-shop. This information then is used to create a BC sales order or a BC sales return order. The process of creating these orders is the same, the only difference is the information sent, so only the creation of the sales order will be detailed below. „eCom orders“ are described in detail in the „eCom Orders“ section, so this section will only describe the creation process.

Creating orders via API consists of two steps:

1. Using the endpoint „eComOrders“ the information about the order is sent to BC

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComOrders

Request body example:
{
"eComOrderNo": "",
"orderType": "",
"shopCode": "",
"scheduled": false,
"createNewOrder": false,
"eComCustomerId": "",
"customerIsBusiness": false,
"customerRegistrationNo": "",
"customerVatRegistrationNo": "",
"customerName": "",
"customerName2": "",
"customerAddress": "",
"customerAddress2": "",
"customerPostCode": "",
"customerCity": "",
"customerCountryCode": "",
"customerEmail": "",
"customerPhoneNo": "",
"shipToName": "",
"shipToName2": "",
"shipToAddress": "",
"shipToAddress2": "",
"shipToPostCode": "",
"shipToCity": "",
"shipToCountryCode": "",
"appliesToOrderNo": "",
"returnReasonCode": "",
"navInvoice": false,
"orderDate": "0000-00-00",
"postingDate": "0000-00-00",
"shipmentDate": "0000-00-00",
"currencyCode": "",
"amount": 0.00,
"amountIncludingVat": 0.00,
"paymentTermsCode": "",
"paymentMethodCode": "",
"shipmentMethodCode": "",
"shippingAgentCode": "",
"useNavPrices": false,
"shipmentLabel": "",
"sellFromMarketplaceCode": "",
"shipmentLManifest": "",
"additionalInfo1": "",
"additionalInfo2": "",
"additionalInfo3": "",
"additionalInfo4": "",
"additionalInfo5": "",
"eComOrderLines": [
{
"itemNumber": "",
"crossReferenceNo": "",
"description": "",
"description2": "",
"variantCode": "",
"unitOfMeasure": "",
"quantity": 0.00,
"unitPrice": 0.00,
"amount": 0.00,
"amountIncludingVat": 0.00,
"appliesToOrderNo": "",
"returnReasonCode": "",
"vatPerCent": 0,
"additionalInfo1": "",
"additionalInfo2": "",
"additionalInfo3": "",
"additionalInfo4": "",
"additionalInfo5": "",
"ecomOrderLineIncomingAttributes": [
{
"type": "",
"code": "",
"value": ""
}
]
}
],
"eComOrderServiceLines": [
{
"serviceId": "",
"serviceDescription": "",
"servicePrice": 0.00,
"amount": 0.00,
"amountIncludingVat": 0.00
}
],
"eComOrderCouponLines": [
{
"couponTypeCode": "",
"couponId": "",
"couponDescription": "",
"couponValue": 0.00
}
]
}

2. Using the endpoint’s „eComOrders“ function „Microsoft.NAV.createBcOrder“ the creation process of BC order is initialized. For this, the ID of the created „eCom Order“ is needed. This ID is provided in the first step request answer body.

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComOrders({{eComOrderID}})/Microsoft.NAV.createBcOrder

If the creation is successful, the request answer will contain „Accepted“. If not – an error message will be shown.

LISTING UPDATE

In the Softera.eCom app, listings are created in BC and then they are imported into e-shop. After this, the information about the listings unique e-shop ID must be exported back to BC. This is necessary to ensure that the listings would be the same in BC and in the e-shop.

Updating listing via API:

Using the endpoint „Listings“, the listing information may be updated. Together with the request body, the odata.tag value must be sent as well, to ensure that after the listing information was read, it didn‘t change in BC.

Request address example:
{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/listings({{listingID}})

Request body example:
{
"id": "",
"shopListingID": 0
}

Examples of Exported Data

Items

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/Items
• Possible extensions: itemTranslations,itemUnitsOfMeasure,itemReferences,itemAttributeMapValues,itemPictureUrls,itemVariants
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "no": "",
  "description": "",
  "description2": "",
  "baseUom": "",
  "salesUom": "",
  "grossWeight": 0,
  "netWeight": 0,
  "tariffNo": "",
  "minimumOrderQuantity": 0,
  "manufacturerCode": "",
  "itemCategoryCode": "",
  "lastDateModified": "",
  "lastDefinitionDateTimeModified": "",
  "salesBlocked": false,
  "additionalInfo": ""
  }

Item Categories

• Request address example:{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/itemCategories
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "code": "",
  "description": "",
  "parentCategory": "",
  "additionalInfo": ""
  }

Item Variants

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/itemVariants
• Possible extensions: itemTranslations,itemReferences,itemVariantAttributeValues,itemPictureUrls
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "code": "",
  "description": "",
  "description2": "",
  "additionalInfo": ""
  }

External Items

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalItems
• Possible extensions: eComExtItemUnitsOfMeasure,eComExtItemReferences,eComExtItemTranslations
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "eComId": "",
  "shopCode": "",
  "description": "",
  "description2": "",
  "baseUnitOfMeasure": "",
  "itemCategoryCode": "",
  "netWeight": 0,
  "grossWeight": 0,
  "tariffNo": "",
  "countryRegionOfOriginCode": "",
  "vendorNo": "",
  "vendorItemNo": "",
  "templateCode": "",
  "additionalInfo1": "",
  "additionalInfo2": "",
  "additionalInfo3": "",
  "additionalInfo4": "",
  "additionalInfo5": "",
  "additionalInfo6": "",
  "additionalInfo7": "",
  "additionalInfo8": "",
  "additionalInfo9": "",
  "additionalInfo10": ""
  }

Item Attributes

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/itemAttributes
• Possible extensions: itemAttributeTranslations,itemAttributeValues($expand=itemAttributeValueTranslations)
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "attributeId": 0,
  "name": "",
  "blocked": false,
  "type": "",
  "unitOfMeasure": "",
  "additionalInfo": ""
  }

Item Inventory

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/itemInventory
• Possible extensions: itemVariantInventory
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "no": "",
  "referenceNo": "",
  "baseUom": "",
  "quantity": 0,
  "plannedReceiptDate": ""
  }

Location Inventory

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/locationInventory
• Possible extensions: itemInventory
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "code": "",
  "name": ""
  }

Listings

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/listings
• Possible extensions: listingPictureUrls,listingTexts,listingItems($expand=itemAttributeValue)
  *** Information in the request answer:**
  {
  "@odata.etag": "",
  "id": "",
  "code": "",
  "shopCode": "",
  "shopListingID": 0,
  "modelItemNumber": "",
  "modelItemDescription": "",
  "unitPrice": 0,
  "netWeight": 0,
  "status": "New",
  "lastDateTimeModified": "",
  "relatedEntries": 0,
  "includedEntries": 0
  }

Customers

• Request address example:{{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/customers
• Possible extensions: shipToAddresses,contacts
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "no": "",
  "eComId": "",
  "name": "",
  "name2": "",
  "address": "",
  "address2": "",
  "city": "",
  "contact": "",
  "phoneNo": "",
  "faxNo": "",
  "postCode": "",
  "email": "",
  "registrationNo": "",
  "currencyCode": "",
  "customerPriceGroup": "",
  "customerDiscGroup": "",
  "languageCode": "",
  "paymentTermsCode": "",
  "paymentTermsDescription": "",
  "paymentTermsDiscountPerCent": 0,
  "salespersonCode": "",
  "salespersonName": "",
  "salesPersonEmail": "",
  "salesPersonPhone": "",
  "countryRegionCode": "",
  "balanceLcy": 0,
  "balanceOverdueAmount": 0,
  "outstandingSalesOrders": 0,
  "creditLimitLcy": 0,
  "vatRegistrationNo": "",
  "vatBusPostingGroup": "",
  "partnerType": "",
  "shippingAdvice": "",
  "shippingTime": "",
  "netChangeLcy": 0,
  "balanceIsOverdue": true,
  "additionalInfo": ""
  }

External Customers

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComExternalCustomers
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "eComId": "",
  "shopCode": "",
  "isBusiness": false,
  "registrationNo": "",
  "vatRegistrationNo": "",
  "name": "",
  "name2": "",
  "address": "",
  "address2": "",
  "postCode": "",
  "city": "",
  "countryCode": "",
  "eMail": "",
  "phoneNo": "",
  "additionalInfo1": "",
  "additionalInfo2": "",
  "additionalInfo3": "",
  "additionalInfo4": "",
  "additionalInfo5": ""
  }

Customer Invoice Status

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/customerInvoiceStatuses
• Necessary filters: shopCode, customerId
  *** Information in the request answer:**
  {
  "@odata.etag": "
  "id": "
  "shopCode": "",
  "customerId": "",
  "customerName": "",
  "customerName2": "",
  "documentNo": "",
  "postingDate": "",
  "isPaid": false,
  "remainingAmountLcy": 0
  }

Order Status

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/orderStatuses
• Necessary filters: shopCode
  *** Information in the request answer:**
  {
  "@odata.etag": "",
  "shopCode": "",
  "orderNo": "",
  "dateTime": "",
  "orderType": "",
  "eComNo": "",
  "statusCode": ""
  }

Posted Invoice

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/postedInvoices
• Necessary filters: shopCode, eComOrderNo
• Possible extensions: postedInvoiceLines,documentPdfFiles
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "shopCode": "",
  "no": "",
  "eComNo": "",
  "eComOrderNo": "",
  "externalDocumentNo": "",
  "currencyCode": "",
  "documentDate": "",
  "postingDate": "",
  "shipmentDate": "",
  "customerId": "",
  "pricesIncludingVAT": false,
  "amount": 0,
  "amountIncludingVAT": 0,
  "paymentTermsCode": "",
  "dueDate": "",
  "paymentDiscountPerCent": 0,
  "invoiceDiscountAmount": 0
  }

Posted Credit Memo

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/postedCreditMemos
• Necessary filters: shopCode, eComOrderNo
• Possible extensions: postedCreditMemoLines,documentPdfFiles
• Information in the request answer:
  {
  "@odata.etag": "
  "id": "",
  "shopCode": "",
  "no": "",
  "eComNo": "",
  "eComOrderNo": "",
  "externalDocumentNo": "",
  "currencyCode": "",
  "documentDate": "",
  "postingDate": "",
  "shipmentDate": "",
  "customerId": "",
  "pricesIncludingVAT": false,
  "amount": 0,
  "amountIncludingVAT": 0,
  "paymentTermsCode": "",
  "dueDate": "",
  "paymentDiscountPerCent": 0,
  "invoiceDiscountAmount": 0
  }

Sale Prices

• Request address example: {{baseURL}}/{{environment}}/api/softera/eCom/v2.0/companies({{companyID}})/eComSalesPrices
• Information in the request answer:
  {
  "@odata.etag": "",
  "id": "",
  "itemNo": "",
  "variantCode": "",
  "unitOfMeasureCode": "",
  "minimumQuantity": 0,
  "salesType": "",
  "salesCode": "",
  "customereComId": "",
  "customerDiscGroup": "",
  "campaignCode": "",
  "currencyCode": "",
  "unitPrice": 0,
  "allowLineDiscount": true,
  "lineDiscountPerCent": 0,
  "unitPriceIncludingDiscount": 0,
  "pricesIncludingVAT": false,
  "vatPerCent": 0,
  "allowInvoiceDiscount": true,
  "createdDateTime": ""
  }