Sincronització per CSV: especificació completa

Per a la sincronització entre els clients i Portal Hero fem servir un sistema de fitxers CSV. El principal fitxer CSV és el d'articles (o feed d'articles), on es llisten tots els articles que es publiquen als diferents portals. En aquest fitxer es troben els articles amb les seves característiques.

Funcionament de la sincronització

La manera d'identificar cada article serà mitjançant el camp id en el qual ens basarem com a identificador únic per decidir si un article s'actualitza o deixa d'existir. Quan un article aparegui per primera vegada al feed d'articles, aquest es pujarà a tots els portals seleccionats pel client. Quan un article deixi d'estar present al feed es marcarà com a venut i quan es canviï qualsevol dada de l'article també serà actualitzat als portals. Per tenir més detalls de la sincronització en si els pots consultar aquí.

El format general d'aquests arxius CSV és el següent:

• Camps separats per comes
• La capçalera ha d'estar present per poder identificar els camps
• Camps delimitats per doble cometa (si és necessari o sempre)
• Codificació de l'arxiu UTF-8

Compartició d'arxius

Tenim dues opcions per fer-nos arribar l'arxiu:

• SFTP
  Disposem d'un SFTP per compartir els arxius i facilitar l'intercanvi d'informació de manera segura. Es facilitaran les dades d'accés a l'SFTP (usuari i contrasenya) durant el procés d'onboarding.
  La resta de dades comunes de connexió són les següents:
  • Host: sftp.portalhero.pro
  • Port: 2222
  
  A més l'SFTP està securitzat i restringit a nivell de xarxa i necessitarem una o diverses IPs per afegir-les a la nostra llista d'IPs d'accés permeses.
  Dins de l'SFTP hi ha creada una carpeta anomenada upload on s'escriuran els arxius: Per al d'articles el nom de l'arxiu serà: item_feed.csv
• url
  El feed d'articles pot ser enviat també via una URL pública des d'on el procés de Portal Hero el descarregarà en cada execució diària del procés.
  La URL haurà de ser informada per part del client durant el procés d'onboarding. En cas de requerir més mesures de seguretat, ens pots facilitar qualsevol header(s) que afegirem a la petició.

Format dels arxius CSV

Relació dels camps, tipologia de detalls i exemples de l'arxiu CSV d'articles:

* Per als articles de cotxes, s'han de proporcionar els següents atributs al camp 'attributes' com una cadena JSON serialitzada:

Respecte al camp status que fa referència a l'estat dels articles, les opcions són les següents:

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

Atributs del Cotxe

Els atributs del cotxe són un conjunt de característiques que descriuen un cotxe. Es fan servir al feed i per publicar-lo als marketplaces.

Exemple (python):

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

attributes = json.dumps(car_attrs)

Atributs de la moto

Per integrar motos, l'article ha d'incloure la informació específica del vehicle. Les dades tècniques s'envien serialitzades com a JSON al camp 'attributes', mentre que la marca i el model viatgen als camps 'brand' i 'model' del CSV.

El camp 'external_category' ha de prendre un dels valors '2', 'Motos', 'Motorbikes' perquè l'article es processi com a moto. Aquesta integració requereix tenir actiu el servei d'ERP de motos al teu compte.

Els valors de 'brand' i 'model' han de coincidir exactament amb els de la nostra taxonomia de motos. Per consultar els valors vàlids disposem de dos endpoints públics (requereixen autenticació i el servei ERP de motos actiu):

• GET /motorbike_brands — retorna la llista completa de marques disponibles, amb el seu 'uid' i 'value'.
• GET /motorbike_models?brand_id={uid} — retorna els models associats a la marca indicada mitjançant 'brand_id'.

Tingues en compte que el títol de l'article es genera automàticament a partir de la marca, el model, la versió (si s'informa) i l'any, per la qual cosa el valor del camp 'title' serà sobreescrit en les motos.

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