CSV synchronisation: full specification

For synchronisation between customers and Portal Hero we use a system of CSV files. The main CSV file is the items file (or item feed), which lists all the items published on the different portals. This file contains the items with their characteristics.

How synchronisation works

The way to identify each item is through the id field, which we rely on as the unique identifier to decide whether an item is updated or ceases to exist. When an item appears for the first time in the item feed, it is uploaded to all the portals selected by the customer. When an item is no longer present in the feed, it is marked as sold, and when any of an item's data changes, it is also updated on the portals. For more details on synchronisation itself you can check them here.

The general format of these CSV files is as follows:

• Fields separated by commas
• The header must be present in order to identify the fields
• Fields delimited by double quotes (where necessary or always)
• File encoding UTF-8

File sharing

We have two options for getting the file to us:

• SFTP
  We provide an SFTP to share the files and make the secure exchange of information easier. The SFTP access details (username and password) will be provided during the onboarding process.
  The rest of the common connection details are as follows:
  • Host: sftp.portalhero.pro
  • Port: 2222
  
  In addition, the SFTP is secured and restricted at the network level, and we will need one or more IPs to add them to our list of allowed access IPs.
  Within the SFTP there is a folder called upload where the files will be written: for the items file the file name will be: item_feed.csv
• url
  The item feed can also be sent via a public URL from which the Portal Hero process will download it on each daily run of the process.
  The URL must be provided by the customer during the onboarding process. If more security measures are required, you can provide us with any header(s), which we will add to the request.

CSV file format

List of the fields, detail types and examples of the items CSV file:

* For car items, the following attributes must be provided in the 'attributes' field as a serialised JSON string:

Regarding the status field that refers to the condition of the items, the options are as follows:

["new", "as_good_as_new", "good", "fair", "has_given_it_all"]

Car attributes

Car attributes are a set of characteristics that describe a car. They are used in the feed and to publish it on the marketplaces.

Example (python):

car_attrs = {
    "version": "1.6 TDI Toyota",
    "year": "2018",
    "horse_power": 100,
    "mileage": 12000,
    "engine": "gasoil",
    "gearbox": "manual"
}

attributes = json.dumps(car_attrs)

Motorbike attributes

To integrate motorbikes, the item must include the vehicle-specific information. The technical data is sent serialised as JSON in the 'attributes' field, while the brand and model travel in the 'brand' and 'model' fields of the CSV.

The 'external_category' field must take one of the values '2', 'Motos', 'Motorbikes' for the item to be processed as a motorbike. This integration requires having the motorbike ERP service active on your account.

The values of 'brand' and 'model' must match exactly those of our motorbike taxonomy. To check the valid values we provide two public endpoints (they require authentication and the motorbike ERP service active):

• GET /motorbike_brands — returns the complete list of available brands, with their 'uid' and 'value'.
• GET /motorbike_models?brand_id={uid} — returns the models associated with the brand indicated via 'brand_id'.

Note that the item's title is generated automatically from the brand, the model, the version (if provided) and the year, so the value of the 'title' field will be overwritten for motorbikes.

Example (python):

motorbike_attrs = {
    "year": 2020,
    "version": "modelo actual",
    "km": 5420,
    "horse_power": 47,
    "engine_capacity_cc": 400,
    "fuel_type": "gasoline",
    "license_plate": "1234 ABC"
}

attributes = json.dumps(motorbike_attrs)