Getting Started

This guide, designed especially for integration engineers, will help you understand the basic integration process. It will also familiarize you with the Pricefx API endpoints needed for loading your master data to Pricefx via REST API.

In the following example procedure for data loading (and data fetching), we will demonstrate how to import products into the Product Master Data table using the Pricefx REST API.

The process consists of three main steps:

Authentication
Making an API call to upload the data
Making an API call to retrieve the data

Prerequisites

The Pricefx partition. To get a partition, reach out to your Pricefx Contact.
Permission. The integration user requires the Data Integration role to bulk load the data.
Clean source dataset and configured Products table. Names of columns in your source product dataset that you will send in your API call must match the column names of the target Products table. The Columns in the Products table must be adjusted according to your data (e.g., the correct data type and format). See the Configure Products Table article.

Authentication

Each REST API request must contain authentication information. Use the JWT token as a preferred method of authentication. The token can be sent as an HTTP header or as a cookie and has an encoded expiration timestamp. JWT tokens can be revoked by changing the user's password.
To obtain a JWT token, follow these steps:

1. Send a Request Using Basic HTTP Authentication

Make a POST request to the /login/extended endpoint using the Basic Authentication to obtain the JWT token.

Warning

Use the Basic HTTP Authentication only to get your JWT Token. Basic authentication intentionally leads to an extra 500 ms slower request execution time.

2. Handle the Response

If the request is successful, you will receive a response with the status code: 200 OK. The response returns the JWT token as a cookie:

Copy

Copied

X-PriceFx-jwt: <encoded_jwt_token>

Attention

JWT token expires in 30 minutes. Once the JWT nears its expiry (in 20 minutes), the server automatically re-issues a new JWT token value (as an updated cookie). The client should then replace the token on their end. It is good practice to refresh your JWT token before it expires (do not wait for status 401). Cookie-aware clients (such as browsers) do that automatically. Each JWT token contains the expiration time as an Epoch Unix Timestamp encoded in Base64.

3. Use the JWT Token

Include the JWT token (X-PriceFx-jwt) in the Authorization header of all subsequent REST API requests.

Optionally: Use the non-expiring token. The token can be retrieved via the /accountmanager.getjsonwebtoken endpoint. Use it with caution as a non-expiring token presents a long-term risk to the security of the system. It is generally considered best practice to use tokens with a reasonable expiry time rather than non-expiring tokens.

Load the Data

There are two main endpoints dedicated to loading data into Products and Customers Master Data tables – /loaddata/P and /integrate. Use the /loaddata endpoint to insert more records (Products, in our example) in bulk and the /integrate endpoint to insert or update just a few records and to update particular fields. In our example, we will use the /loaddata endpoint as it is the most used endpoint for inserting products into Pricefx via REST API.

To load data into the Product Master Data table proceed as follows:

1. Prepare the Data

Ensure that the source dataset is properly formatted – the column names in the source dataset must match the column names in the target Products table.
Verify that the target Products table has the correct types and formats.

Information

The following data types and formats are supported:

Pricefx	OpenAPI specification	Note
String	`string`
Real	`number`	Applies to all formats of the Real type (NUMERIC, NUMERIC_LONG, INTEGER, PERCENT, MONEY, MONEY_EUR, MONEY_USD, MONEY_GBP, MONEY_JPY, MONEY_CHF, MONEY_PLN)
Integer	`integer`
Date	`type: string` `format: date`
Timestamp	`type: string` `format: date-time`	Example: `2023-03-07T07:00:00-08:00` (the UTC-8 time zone offset is specified within the time stamp)
Link	`type: string` `format: uri`
Entity Reference	`string`
Boolean	`boolean`

2. Create a JSON Payload

Convert the source dataset into a JSON payload that can be sent in a REST API request. The JSON payload should contain the object that has three main keys in the main data property: "header", "options", and "data". The header array where each item represents the column name in the target table. options is an object that contains the configuration of the data load. data is an array of arrays, where each inner array represents a product and its attributes as defined by the header property.
The JSON payload example – inserts 3 products into the Products Master Data table:

Copy

Copied

{
   "data":{
      "header":[
         "sku",
         "label",
         "unitOfMeasure",
         "currency",
         "lastUpdateDate",
         "formulaName",
         "attribute1",
         "attribute2",
         "attribute3",
         "attribute4",
         "attribute5",
         "attribute6",
         "attribute7",
         "attribute8",
         "userGroupEdit",
         "userGroupViewDetails"
      ],
      "options":{
         "direct2ds":false,
         "detectJoinFields":true,
         "maxJoinFieldsLengths":[

         ]
      },
      "data":[
         [
            "B-0001",
            "Pub Beer",
            "",
            "EUR",
            "2020-12-17T09:45:56",
            "ElementWithVLookup",
            "17.16",
            "American Pale Lager",
            "",
            "",
            "DG_03",
            "Maturity",
            "",
            "2018-04-18",
            "",
            ""
         ],
         [
            "B-0002",
            "Devil's Cup",
            "",
            "EUR",
            "2022-10-07T09:43:30",
            "",
            "24.05",
            "American Pale Ale (APA)",
            "",
            "",
            "DG_03",
            "Maturity",
            "",
            "2018-04-18",
            "",
            ""
         ],
         [
            "B-0003",
            "Rise of the Phoenix",
            "",
            "EUR",
            "2019-07-15T11:18:26",
            "ConfiguratorWithRadioButton",
            "34.4",
            "American IPA",
            "",
            "A",
            "DG_03",
            "",
            "",
            "2018-04-18",
            "",
            ""
         ]
      ]
   }
}

Replace column names within the header property with the appropriate column names used in the target table and values within data with the corresponding product data values.

3. Send a POST Request to the API Endpoint

Make a POST request to the /loaddata/P endpoint, where P is the type code of the target "Products" Master Data table.
Include the JWT token in the Authorization header, and set the Content-Type header to application/json. Include the JSON payload in the request body.

time-out

The server has a default timeout of 3 minutes (180 seconds) for processing API requests. This means that when the server receives an API request, it will process the request and send a response within 3 minutes. If it takes longer than 3 minutes, the connection will be terminated.

You can send the request via the TryIt console below. Enter your credentials in the Security section, replace the sample payload in the body section to make it compatible with your target Products table, enter the baseUrl and the name of the partition you want to use. When you click the Send button, the request will be sent to the /loaddata/P endpoint. This fills the target table with the data you provided in the payload. You can find the number of records inserted in the response within the data property.

Fetch the Data

To retrieve records from the Products Master Data table, we will use the /productmanager.fetchformulafilteredproducts endpoint.

Follow these three steps to fetch the data from the Products table:

1. Define the Payload of the API Call

To adjust the response to your API call, you can optionally provide the following parameters in the request body:

startRow (optional): Use this parameter if you want to implement paging for results. The number defining the start of the returned objects for the result set. If not set, the default value of 0 will be used.
endRow (optional): Use this parameter if you want to implement paging for results. The number defining the end of the returned objects for the result set. If not set, the default value of 300 will be used.
a filter (optional): Employ a filter to narrow down the result. See Advanced Filter within the Filtering, Sorting, Pagination article.
Example (filtering):

Copy

Copied

{
  "endRow": 300,
  "operationType": "fetch",
  "startRow": 0,
  "textMatchStyle": "exact",
  "data": {
    "_constructor": "AdvancedCriteria",
    "operator": "and",
    "criteria": [
      {
        "fieldName": "currency",
        "operator": "iEquals",
        "value": "EUR"
      }
    ]
  }
}

resultFields (optional): Choose the fields you want to return. Returns key-value pairs as objects. This is the more friendly response compared to valueFields but the server fetches all fields from the database in the backend which might result in slower performance. For a sample request and response, please see the /productmanager.fetchformulafilteredproducts endpoint reference.
Example (resultFields):

Copy

Copied

{
  "endRow": 300,
  "operationType": "fetch",
  "startRow": 0,
  "textMatchStyle": "exact",
  "data": null,
  "resultFields": [
    "sku",
    "label",
    "currency"
  ]
}

valueFields (optional): Choose fields you want to return. Returns just an array of values. Use this option if better performance is required. For a sample request and response, please see the /productmanager.fetchformulafilteredproducts endpoint reference.

2. Send a POST Request to the API Endpoint

Make a POST request to the /productmanager.fetchformulafilteredproducts endpoint. Include the JWT token in the Authorization header and provide the request body if needed.

You can send the request via the TryIt console below. Enter your credentials in the Security section, replace or remove the sample payload in the Body section, enter the baseUrl and the name of the partition you want to use.
When you click the Send button, the request will be sent to the /productmanager.fetchformulafilteredproducts endpoint. If the API call is successful (status 200 OK), records that match the criteria defined in your request will be returned in the response.

3. Handle the Response

If the request is successful, you will receive a response with the status code: 200 OK. The response will contain the fetched data in JSON format, along with metadata about the pagination and the total number of records.
Here is an example of a successful response:

Copy

Copied

{
   "response":{
      "node":"pricefx-cluster-app-frontend-6669d4d854-25v8w",
      "startRow":0,
      "data":[
         {
            "version":0,
            "typedId":"2147506307.P",
            "sku":"B-0001",
            "label":"Pub Beer",
            "unitOfMeasure":"",
            "userGroupEdit":"",
            "userGroupViewDetails":"",
            "currency":"EUR",
            "formulaName":"ElementWithVLookup",
            "createDate":"2023-04-13T08:46:04",
            "createdBy":2147490696,
            "lastUpdateDate":"2020-12-17T09:45:56",
            "lastUpdateBy":2147490696,
            "attribute1":17.16,
            "attribute2":"American Pale Lager",
            "attribute3":0,
            "attribute4":"",
            "attribute5":"DG_03",
            "attribute6":"Maturity",
            "attribute7":"",
            "attribute8":"2018-04-18"
         },
         {
            "version":0,
            "typedId":"2147506308.P",
            "sku":"B-0002",
            "label":"Devil's Cup",
            "unitOfMeasure":"",
            "userGroupEdit":"",
            "userGroupViewDetails":"",
            "currency":"EUR",
            "formulaName":"",
            "createDate":"2023-04-13T08:46:04",
            "createdBy":2147490696,
            "lastUpdateDate":"2022-10-07T09:43:30",
            "lastUpdateBy":2147490696,
            "attribute1":24.05,
            "attribute2":"American Pale Ale (APA)",
            "attribute3":0,
            "attribute4":"",
            "attribute5":"DG_03",
            "attribute6":"Maturity",
            "attribute7":"",
            "attribute8":"2018-04-18"
         },
         {
            "version":0,
            "typedId":"2147506309.P",
            "sku":"B-0003",
            "label":"Rise of the Phoenix",
            "unitOfMeasure":"",
            "userGroupEdit":"",
            "userGroupViewDetails":"",
            "currency":"EUR",
            "formulaName":"ConfiguratorWithRadioButton",
            "createDate":"2023-04-13T08:46:04",
            "createdBy":2147490696,
            "lastUpdateDate":"2019-07-15T11:18:26",
            "lastUpdateBy":2147490696,
            "attribute1":34.4,
            "attribute2":"American IPA",
            "attribute3":0,
            "attribute4":"A",
            "attribute5":"DG_03",
            "attribute6":"",
            "attribute7":"",
            "attribute8":"2018-04-18"
         }
      ],
      "endRow":3,
      "totalRows":3,
      "status":0
   }
}

By following the steps in this guide you have learned the process of authentication, inserting data using the /loaddata/P endpoint, and fetching data using the /productmanager.fetchformulafilteredproducts endpoint. With these fundamental concepts, you can now extend your knowledge and explore other Pricefx REST API endpoints (see the Pricefx API Reference section in the menu) to manage and manipulate data. As you continue to work with the Pricefx API, remember to follow best practices and ensure the security of your data by using JWT tokens. For further assistance, don't hesitate to reach out to your Pricefx contact.