order-candidates-rest-controller-impl (sales order candidates/disposition)

Overview

Via this endpoint you can import sales order candidates into metasfresh and at the same time even create new business partner and product entries. You can also use this endpoint to upload file attachments and attach them to the sales order candidates.

To use this endpoint successfully, you require the following data:

Data source name of the endpoint (dataSource):
int-SOURCE.de.metas.rest_api.ordercandidates.impl.OrderCandidatesRestControllerImpl
Internal name of the data target (dataDest): int-DEST.de.metas.ordercandidate

These are so-called “identifier strings” (ID strings) whose respective values need to be provided using one of the corresponding prefixes:

int- for the ID of the data record on the internal platform (internalId)
ext- for the ID of the data record on the external platform (externalId)
val- for the search key of the data entry in metasfresh

If no prefix is provided, the element value is regarded as the ID of the data entry (AD_Input_DataSource_ID = metasfreshId).

Note:
You will find the imported sales order candidates and file attachments under “Sales Order Disposition” in the WebUI menu.

Steps

Import sales order candidates

Follow these instructions and use the request method POST /api/sales/order/candidates. At step 7, paste your JSON server request you have prepared based on the request example provided for this endpoint.

Upload file attachments

Click on the request method
POST /api/sales/order/candidates/{dataSourceName}/{externalReference}/attachments.
Click on the right below the request method. Several input fields become editable.
In the field Authorization token, paste your authentication token.
In the field dataSourceName, paste the endpoint’s data source name.
In the field externalReference, enter the external reference ID (External Header ID) of the sales order candidate’s entry where the file shall be attached.

Note: You can view the External Header ID in the advanced edit menu from the actions menu of the respective sales order candidate’s entry.
In the field file, click or to select the attachment file.
Click to upload the file attachment.

Note: Any error messages will be displayed in the Responses section below.

Example server request

Create sales order candidates incl. business partner and product entry

{
  "bpartner": {
    "bpartner": {
      "active": true,
      "code": "API_001_testBP",
      "companyName": "API Inc.",
      "externalId": "API-bp00001",
      "group": "Standard",
      "name": "Ganesh Rupka BP",
      "phone": "1800-CALL-ME",
      "syncAdvise": {
        "ifExists": "DONT_UPDATE",
        "ifNotExists": "CREATE"
      }
    },
    "contact": {
      "active": true,
      "description": "RESTing with the apes.",
      "email": "ganesh.rupka@nomail.com",
      "externalId": "API-con00001",
      "firstName": "Ganesh",
      "lastName": "Rupka",
      "phone": "1800-CALL-ME-NOW",
      "name": "Ganesh B. Rupka",
      "syncAdvise": {
        "ifExists": "DONT_UPDATE",
        "ifNotExists": "CREATE"
      }
    },
    "location": {
      "active": true,
      "address1": "Street No. 1",
      "address2": "East Wing",
      "address3": "Apt. 3",
      "address4": "Room 4",
      "postal": "1234",
      "city": "New Dehli",
      "countryCode": "IN",
      "externalId": "API-loc00001",
      "name": "Ganesh Rupka's address",
      "syncAdvise": {
        "ifExists": "DONT_UPDATE",
        "ifNotExists": "CREATE"
      }
    },
    "syncAdvise": {
      "ifExists": "DONT_UPDATE",
      "ifNotExists": "CREATE"
    }
  },
  "currencyCode": "INR",
  "dataSource": "int-SOURCE.de.metas.rest_api.ordercandidates.impl.OrderCandidatesRestControllerImpl",
  "dataDest": "int-DEST.de.metas.ordercandidate",
  "dateRequired": "2019-08-23",
  "externalHeaderId": "extHead-101",
  "externalLineId": "extLine-101",
  "invoiceDocType": {
    "docBaseType": "ARI"
  },
  "org": {
    "code": "001",
    "syncAdvise": {
      "ifExists": "DONT_UPDATE",
      "ifNotExists": "FAIL"
    }
  },
  "poReference": "SEO_768-04",
  "pricingSystemCode": "Testpreise Kunden",
  "product": {
    "code": "Coco_2468",
    "name": "Coconuts",
    "type": "ITEM",
    "priceStd": 6.90,
    "uomCode": "PCE",
    "syncAdvise": {
      "ifExists": "DONT_UPDATE",
      "ifNotExists": "CREATE"
    }
  },
  "uomCode": "PCE",
  "productDescription": "I've got a lovely bunch of coconuts.",
  "qty": 5
  "salesPartnerCode": "test_42",
  "shipper": "val-DPD - Classic",
  "paymentRule": "OnCredit",
  "orderDocType": "SalesOrder"
}

Useful Tips

Element Note

"pricingSystemCode": The pricing system provided in the JSON server request must point to an existing sales price list that contains a price list version whose validity period includes the date from the server request in order for the product prices to be created. The aforementioned price list must also be equipped with a default tax category.
In addition, make sure that the scheduler for the sales order candidate import process (C_OLCand process to C_OrderLines) is set to active.

"postal":
"city":
"countryCode": When importing ZIP, city and country, make sure that the postal code provided also exists in the system, otherwise it cannot be linked to the corresponding database table C_Location and only the respective fields are populated without further georeference.

Element	Note
`"pricingSystemCode":`	The pricing system provided in the JSON server request must point to an existing sales price list that contains a price list version whose validity period includes the date from the server request in order for the product prices to be created. The aforementioned price list must also be equipped with a default tax category. In addition, make sure that the scheduler for the sales order candidate import process (`C_OLCand process to C_OrderLines`) is set to active.
`"postal":` `"city":` `"countryCode":`	When importing ZIP, city and country, make sure that the postal code provided also exists in the system, otherwise it cannot be linked to the corresponding database table `C_Location` and only the respective fields are populated without further georeference.

View source file on GitHub.com