Sincronización por CSV: especificación completa

Para la sincronización entre los clientes y Portal Hero utilizamos un sistema de ficheros CSV. El principal fichero CSV es el de artículos (o feed de artículos), donde se listan todos los artículos que se publican en los distintos portales. En este fichero se encuentran los artículos con sus características.

Funcionamiento de la sincronización

La manera de identificar cada artículo será mediante el campo id en el que nos basaremos como identificador único para decidir si un artículo se actualiza o deja de existir. Cuando un artículo aparezca por primera vez en el feed de artículos, éste se subirá a todos los portales seleccionados por el cliente. Cuando un artículo deje de estar presente en el feed se marcará como vendido y cuando se cambie cualquier dato del artículo también será actualizado en los portales. Para tener más detalles de la sincronización en sí puedes consultarlos aquí.

El formato general de estos archivos CSV es el siguiente:

• Campos separados por comas
• La cabecera tiene que estar presente para poder identificar los campos
• Campos delimitados por doble comilla (si es necesario o siempre)
• Codificación del archivo UTF-8

Compartición de archivos

Tenemos dos opciones para hacernos llegar el archivo:

• SFTP
  Disponemos de un SFTP para compartir los archivos y facilitar el intercambio de información de manera segura. Se facilitarán los datos de acceso al SFTP (usuario y contraseña) durante el proceso de onboarding.
  El resto de datos comunes de conexión son los siguientes:
  • Host: sftp.portalhero.pro
  • Port: 2222
  
  Además el SFTP está securizado y restringido a nivel de red y necesitaremos una o varias IPs para añadirlas a nuestra lista de IPs de acceso permitidas.
  Dentro del SFTP hay creada una carpeta llamada upload donde se escribirán los archivos: Para el de artículos el nombre del archivo será: item_feed.csv
• url
  El feed de artículos puede ser enviado también vía una URL pública desde donde el proceso de Portal Hero lo descargará en cada ejecución diaria del proceso.
  La URL deberá ser informada por parte del cliente durante el proceso de onboarding. En caso de requerir más medidas de seguridad, puedes facilitarnos cualquier header(s) que añadiremos a la petición.

Formato de los archivos CSV

Relación de los campos, tipología de detalles y ejemplos del archivo CSV de artículos:

* Para los artículos de coches, se deben proporcionar los siguientes atributos en el campo 'attributes' como una cadena JSON serializada:

Respecto al campo status que hace referencia al estado de los artículos, las opciones son las siguientes:

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

Atributos del Coche

Los atributos del coche son un conjunto de características que describen un coche. Se utilizan en el feed y para publicarlo en los marketplaces.

Ejemplo (python):

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

attributes = json.dumps(car_attrs)

Atributos de la moto

Para integrar motos, el artículo debe incluir la información específica del vehículo. Los datos técnicos se envían serializados como JSON en el campo 'attributes', mientras que la marca y el modelo viajan en los campos 'brand' y 'model' del CSV.

El campo 'external_category' debe tomar uno de los valores '2', 'Motos', 'Motorbikes' para que el artículo se procese como moto. Esta integración requiere tener activo el servicio de ERP de motos en tu cuenta.

Los valores de 'brand' y 'model' tienen que coincidir exactamente con los de nuestra taxonomía de motos. Para consultar los valores válidos disponemos de dos endpoints públicos (requieren autenticación y el servicio ERP de motos activo):

• GET /motorbike_brands — devuelve la lista completa de marcas disponibles, con su 'uid' y 'value'.
• GET /motorbike_models?brand_id={uid} — devuelve los modelos asociados a la marca indicada mediante 'brand_id'.

Ten en cuenta que el título del artículo se genera automáticamente a partir de la marca, el modelo, la versión (si se informa) y el año, por lo que el valor del campo 'title' será sobrescrito en las motos.

Ejemplo (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)