Import Endpoints
Overview
The Data API exposes a set of RESTful web service endpoints that allow customers to submit new data in simplified form to Kalibrate Pricing. The Data API Endpoints implement the standard set of import formats as the file-based imports currently supported via SFTP.
The endpoints themselves use the same authentication and authorization mechanisms as the standard Data API endpoints, however they will require credentials with ReadWrite privileges. These credentials should be used for Import only and will be issued by Kalibrate as part of the onboarding process.
Import Endpoints all use the POST http verb and require a correctly formatted JSON document body. The JSON document body schema for each endpoint is provided in the swagger documentation for each endpoint.
Calls to each endpoint will return a unique operation identifier. This can be used to match the import request to the processed import data in the Import Status user interface (a.k.a. Error Browser)
Field Length Restrictions
Certain fields (attributes) in the import data are restricted to certain lengths (as follows:)
| Attribute | Length (characters) |
|---|---|
| brand | 100 |
| siteID | 20 |
| produceCode | 20 |
| source | 20 |
| origin | 50 |
| currencyUnit | 3 |
| Import Entity | Description | Endpoint |
|---|---|---|
| Competitor Prices | This is used for the import of product prices at competitor sites | /api/import/competitorPrice |
| Own Prices | This is used for the import of product prices at own sites | /api/import/ownPrice |
| Sales Volue | Send updated sales volume information | /api/import/salesVolume |
| Cost Breakdown | This is used for the import of product cost breakdowns at own sites | /api/import/costBreakdown |
Competitor Prices
This channel is used to import prices for the products sold by competitor sites. The import of competitor prices will, if the system is enabled to generate prices on data receipt, initiate the price generation process for any sites associated with the imported competitors.
If the optional OwnSite identifier is included,the price generation process will only be initiated for the specified own site, and not the other own sites associated to the competitor.
Details
The import data schema for Competitor Price data is an array of competitorPriceItems. Each competitor price item consists of the following attributes:
| Name | Type | Description | Mandatory |
|---|---|---|---|
| ownSite | Own Site | Own sites when provided will ensure that price generation only occurrs for the provided own site. Child attributes are mandatory if the optional own site block is included | N |
| ownSite.brand | String | Own brand name | Y |
| ownsite.siteId | String | Import code of the related own site | Y |
| brand | String | Competitor brand name | Y |
| competitorId | String | Import code of the competitor site | Y |
| effectiveDate | DateTime | UTC date from which the competitor price is effective | Y |
| productCode | String | Global product import code | Y |
| source | String | Data channel format | N |
| origin | String | Description of where the price originated | N |
| competitorPrice | CompetitorPrice | The price value and currency unit for the competitor price | Y |
| competitorPrice.currencyUnit | String | ISO 4217 currency code | N |
| competitorPrice.priceValue | Currency | Price value to import for the product | Y |
Schema
{
"competitorPrices": {
"competitorPriceItems": [
{
"ownSite": {
"brand": "string",
"siteId": "string"
},
"brand": "string",
"competitorId": "string",
"effectiveDate": "2020-09-17T12:40:32.895Z",
"productCode": "string",
"source": "string",
"origin": "string",
"competitorPrice": {
"currencyUnit": "string",
"priceValue": 0
}
}
}
Own Price
This channel is used by PriceNet to import prices for the products sold by each site
Details
| Name | Type | Description | Mandatory |
|---|---|---|---|
| siteId | String | Import code of the site | Y |
| brand | String | Own brand name | Y |
| effectiveDate | DateTime | UTC date from which the competitor price is effective | Y |
| productCode | String | Global product import code | Y |
| source | String | Data channel format | N |
| origin | String | Description of where the price originated | N |
| ownPrice | OwnPrice | The price value and currency unit for the product price | Y |
| OwnPrice.currencyUnit | String | ISO 4217 currency code | N |
| OwnPrice.priceValue | Currency | Price value to import for the product | Y |
Schema
{
"ownPrices": {
"ownPriceItems": [
{
"siteId": "string",
"brand": "string",
"effectiveDate": "2020-09-17T12:59:07.249Z",
"productCode": "string",
"ownPrice": {
"currencyUnit": "string",
"priceValue": 0
},
"source": "string",
"origin": "string",
}
]
}
}
Sales Volume
This channel is used to import the volumes of each product sold by each site. These are known as Sell-Out volumes.
The Sales Breakdown import schema will import various sales elements which, when added together producea completes ales volume value.
These values can be used to store elements such as “cash sales”, “card sales”, etc., or even the “total sales volumes”.
The sales volumes can now be imported using sub-daily dates for each defined type, i.e. 00:00:00 to 12:00:00 and 12:00:01 to 23:59:59.
Volumes that span days will be proportion by time where the system requires daily volumes, e.g. 10000 litres imported for Tues 20:00:00 to Weds 06:00:00 will be split to include 4000 litres for Tues and 6000 litres for Weds.
This is usually required for running rates and Optimisation.
Details
| Name | Type | Description | Mandatory |
|---|---|---|---|
| brand | String | Name the related own brand | Y |
| siteId | String | Import code for the own site | Y |
| startDate | DateTime | Date/Time of the start of the sales volume period | Y |
| endDate | DateTime | Date/Time of the end of the sales volume period | Y |
| productCode | String | Import code of the global product | Y |
| infoCode | String | TBC | ? |
| salesVolume | SalesVolume | Sales Volume data | Y |
| SalesVolume.Volume | Decimal | Volume value for this volume record | Y |
| SalesVolume.Price | Decimal | Price value for this volume record | Y |
| SalesVolume.Type | String | Import Code of the associated Sales Type for which this volume relates | Y |
Schema
{
"salesVolumes": {
"salesVolumeItems": [
{
"brand": "string",
"siteId": "string",
"startDate": "2020-09-17T13:26:52.481Z",
"endDate": "2020-09-17T13:26:52.481Z",
"productCode": "string",
"infoCode": 0,
"salesVolume": {
"volume": 0,
"price": 0,
"type": "string"
}
]
}
}
Cost Breakdown
This channel is used to import various cost elements which, when added together produce acomplete costvalue. These values can be used to store elements such as “taxes”, “discounts”, “logistic costs”, etc., or even the “total cost price”.
The cost elements can be imported at various levels, i.e. Network, Area, OwnSite, Terminal, All, where the cost value is imported for each product at the defined level, e.g. Importing a cost value of 0.89 for TOTALCOST for product GP-04-DIES for site Hyperlow Superstore (OS-23-HYSU) will import the cost for one product.
Importing the same information for terminal CarPort will import the cost for all products where the site has the terminal property of CarPort.
The same applies for Network and Area.
Importing for All will import the cost for all own products in the data model.
Details
| Name | Type | Description | Mandatory |
|---|---|---|---|
| entity | Integer | Identifier of the enity type | Y |
| entityName | String | Import code of the instance of the entity type | Y |
| effectiveDate | Date/Time | Date/Time from which the cost breakdown record applies | Y |
| productCode | String | Import code for the related global product | Y |
| cost | Cost | Cost detail | Y |
| cost.costValue | Decimal | Actual value associated with the cost element | Y |
| cost.costType | String | Import code of the cost type associated with this cost element | Y |
Schema
{
"costs": {
"costItems": [
{
"entity": 0,
"entityName": "string",
"effectiveDate": "2020-09-17T13:38:37.780Z",
"productCode": "string",
"cost": {
"costValue": 0,
"costType": "string"
}
]
}
}