Sincronizzazione via CSV: specifica completa

Per la sincronizzazione tra i clienti e Portal Hero utilizziamo un sistema di file CSV. Il file CSV principale è quello degli articoli (o feed degli articoli), dove sono elencati tutti gli articoli che vengono pubblicati sui diversi portali. In questo file si trovano gli articoli con le loro caratteristiche.

Funzionamento della sincronizzazione

Il modo di identificare ogni articolo sarà tramite il campo id sul quale ci baseremo come identificatore univoco per decidere se un articolo viene aggiornato o cessa di esistere. Quando un articolo appare per la prima volta nel feed degli articoli, questo viene caricato su tutti i portali selezionati dal cliente. Quando un articolo non è più presente nel feed viene contrassegnato come venduto e quando si modifica un qualsiasi dato dell'articolo viene anche aggiornato sui portali. Per avere maggiori dettagli sulla sincronizzazione in sé puoi consultarli qui.

Il formato generale di questi file CSV è il seguente:

• Campi separati da virgole
• L'intestazione deve essere presente per poter identificare i campi
• Campi delimitati da doppie virgolette (se necessario o sempre)
• Codifica del file UTF-8

Condivisione dei file

Abbiamo due opzioni per farci arrivare il file:

• SFTP
  Disponiamo di un SFTP per condividere i file e facilitare lo scambio di informazioni in modo sicuro. I dati di accesso all'SFTP (utente e password) verranno forniti durante il processo di onboarding.
  Gli altri dati comuni di connessione sono i seguenti:
  • Host: sftp.portalhero.pro
  • Port: 2222
  
  Inoltre l'SFTP è protetto e limitato a livello di rete e avremo bisogno di uno o più IP da aggiungere alla nostra lista di IP di accesso consentiti.
  All'interno dell'SFTP è stata creata una cartella chiamata upload dove verranno scritti i file: Per quello degli articoli il nome del file sarà: item_feed.csv
• url
  Il feed degli articoli può essere inviato anche tramite un URL pubblico da cui il processo di Portal Hero lo scaricherà a ogni esecuzione giornaliera del processo.
  L'URL dovrà essere comunicato dal cliente durante il processo di onboarding. Nel caso in cui siano necessarie ulteriori misure di sicurezza, puoi fornirci qualsiasi header che aggiungeremo alla richiesta.

Formato dei file CSV

Elenco dei campi, tipologia di dettagli ed esempi del file CSV degli articoli:

* Per gli articoli di auto, si devono fornire i seguenti attributi nel campo 'attributes' come una stringa JSON serializzata:

Riguardo al campo status che fa riferimento allo stato degli articoli, le opzioni sono le seguenti:

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

Attributi dell'auto

Gli attributi dell'auto sono un insieme di caratteristiche che descrivono un'auto. Si utilizzano nel feed e per pubblicarla sui marketplace.

Esempio (python):

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

attributes = json.dumps(car_attrs)

Attributi della moto

Per integrare le moto, l'articolo deve includere le informazioni specifiche del veicolo. I dati tecnici si inviano serializzati come JSON nel campo 'attributes', mentre la marca e il modello viaggiano nei campi 'brand' e 'model' del CSV.

Il campo 'external_category' deve assumere uno dei valori '2', 'Motos', 'Motorbikes' affinché l'articolo venga elaborato come moto. Questa integrazione richiede di avere attivo il servizio di ERP di moto sul tuo account.

I valori di 'brand' e 'model' devono coincidere esattamente con quelli della nostra tassonomia di moto. Per consultare i valori validi disponiamo di due endpoint pubblici (richiedono autenticazione e il servizio ERP di moto attivo):

• GET /motorbike_brands — restituisce l'elenco completo delle marche disponibili, con il loro 'uid' e 'value'.
• GET /motorbike_models?brand_id={uid} — restituisce i modelli associati alla marca indicata tramite 'brand_id'.

Tieni presente che il titolo dell'articolo viene generato automaticamente a partire dalla marca, dal modello, dalla versione (se indicata) e dall'anno, per cui il valore del campo 'title' verrà sovrascritto nelle moto.

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