Estrazione ordini e aggiornamento stato via API

Caratteristiche Generali delle API

Le API sono accessibili con chiamate REST, per usarle occorre aprire un ticket, Scegli Altro e richiedi una API Key.
Ogni chiamata API dovrà includere nella URL l'API key
La forma generale di una chiamata API è:

https://app.sellrapido.com/sr_company_ws/api/path/api_key

  • path: è il percorso che identifica la chiamata da effettuare sul server, deve essere sostituito con uno dei valori indicati nei paragrafi seguenti
  • api_key: è la API key assegnata all'utente
 Il body della richiesta deve essere un JSON che contiene i vari parametri della richiesta.

Estrazione Ordini tramite API

L'API serve per scaricare tutti i tuoi ordini da SellRapido per importarli nel tuo gestionale ed eseguire in autonomia l'evasione degli stessi:

https://app.sellrapido.com/sr_company_ws/api/order/api_key

Metodo HTTP: POST

Il body della richiesta deve avere la seguente forma (i vari parametri sono opzionali e permettono di costruire filtri per selezionare gli ordini da scaricare):

{
startDate”: "yyyy-mm-dd",*
endDate”: "yyyy-mm-dd",
“startModified”: "yyyy-mm-dd",
“endModified”: "yyyy-mm-dd",
“code”: ,
"format”: “csv”|”json” (se non specificato vale “json”),
“status”: “sent”|”standby”|”cancelled”|”accepted”,
“columnSeparator”: separatore di colonna per formato csv (es: "|"),
“writeHeading”: true|false (true per stampare le intestazioni di colonna, se non specificato vale “true”),
“offset”: primo record da estrarre,
“limit”: numero di record da estrarre (-1 per estrarli tutti, di default vale /immagini_guida/cred-yatego-1.png )
"tags": ["tag1", "tag2"] (verranno estratti gli ordini che contengono almeno uno dei tag specificati)

}

          *startDate / endDate
filtrano sulla data ordine

    N.B.  Il campo code nell'estrazione ordini via API è opzionale.

    Se valorizzato deve contenere un array di codici ordine che verrà utilizzato per estrarre solo gli ordini corrispondenti ai quei codici, quindi ad esempio

    "code": ["224341564","AXDF5-23542","SDER-465632"]

    I codici ordine sono quelli assegnati dal marketplace (non è l'id SellRapido)


    Campi del post-vendita

    La valorizzazione dei campi varia da Marketplace a Marketplace, pertanto non sempre è possibile valorizzarli (ad esempio le commissioni di vendita/pagamento non sono sempre disponibili).
    In generale sono sempre disponibili i dati necessari ad effettuare la spedizione:
    • informazioni sul prodotto venduto (sku, prezzo quantità, etc.)
    • indirizzo di fatturazione
    • indirizzo di spedizione
    Tutte le informazioni aggiuntive - specie quelle relative ai costi, al fornitore e al corriere - vanno inserite a mano oppure in automatico da SellRapido (ove sia possibile incrociare i dati con i listini di prevendita).
    I campi prefissati con:
    • h. sono quelli della testata ordine
    • r. sono quelli delle righe ordine

     

    h.agent riferimento agente, inserito a mano in SellRapido 
    h.billed 1 se l'oridne è stato esportato da SellRapido per fatturazione
    h.buyer_address1 indirizzo
    h.buyer_address1_dd indirizzo - destinazione diversa
    h.buyer_address2 indirizzo riga aggiuntiva
    h.buyer_address2_dd indirizzo riga aggiuntiva - destinazione diversa
    h.buyer_checkout_message messaggio lasciato dal buyer
    h.buyer_city citta
    h.buyer_city_dd citta - destinazione diversa
    h.buyer_country nazione
    h.buyer_country_dd nazione - destinazione diversa
    h.buyer_email email
    h.buyer_fax fax
    h.buyer_fax_dd fax destinazone diversa
    h.buyer_fiscal_code codice fiscale
    h.buyer_invoice_ecode codice per fatturaiozne elettronica
    h.buyer_latitude non utilizzato
    h.buyer_latitude_dd non utilizzato
    h.buyer_loc_place non utilizzato
    h.buyer_loc_place_dd non utilizzato
    h.buyer_longitude non utilizzato
    h.buyer_longitude_dd non utilizzato
    h.buyer_mobile tel. cellulare
    h.buyer_mobile_dd tel. cellulare - destinazione diversa
    h.buyer_name nominativo buyer
    h.buyer_name_dd nominativo buyer - destinazione diversa
    h.buyer_pec email certificata
    h.buyer_phone telefono
    h.buyer_phone_dd telefono - destinazione diversa
    h.buyer_province provincia
    h.buyer_province_dd provincia - destinazione diversa
    h.buyer_token non utilizzato
    h.buyer_user_id id buyer lato marketplace
    h.buyer_vat partita iva
    h.buyer_zip cap
    h.buyer_zip_dd cap destinazione diversa
    h.channel_code codice canale marketplace
    h.cod_cash_only 1 se pagamento in contrassegno con contante
    h.cod_option non utilizzato
    h.cod_price costo contrassegno
    h.code codice ordine assegnato dal marketplace
    h.code_number numero ordine assegnato dal marketplace
    h.content_type valorizzato a mano in SellRapido , descrive il contenuto dell'ordine
    h.courier id corriere, valorizzato a mano in SellRapido 
    h.courier_code codice corriere del marketplace, scari cato dal marketplace se disponibile
    h.created data creazione in SellRapido 
    h.currency codice valuta
    h.customer id buyer codificato in SellRapido 
    h.date_last_delivery ultima data utile per la consegna
    h.date_last_ship ultima data utile per la iniziare la spedizione
    h.date_order data ordine
    h.date_payment data pagamento
    h.date_shipping data spedizione
    h.feedbacks_date data in cui è stato lasciato l'ultimo feedback
    h.fields_lock elenco campi bloccati (campo di sistema)
    h.hidden 1 per indicare che l'oridne è arhciviato e quindi non più visibile in SellRapido 
    h.id id ordine SellRapido 
    h.insurance_code non utilizzato
    h.is_prime 1 pe rindicare che è un ordine Amazon Prime
    h.marketplace_code codice marketplace
    h.marketplace_country nazione marketplace
    h.marketplace_fee commissioni marketplace
    h.marketplace_payment_info_date data in cui sono state scaricate alcune info aggiuntive oridne (solo per Amazon), è un campo di sistema
    h.merchant_id codice seller
    h.modified data modifica ordine
    h.note note ordine
    h.payment_code codice metodo pagamento marketplace
    h.payment_note note pagamento
    h.paypal_fee commissioni paypal
    h.paypal_transaction_id id transazione paypal
    h.price totale ordine comprnesivo di tutto (iva, sconti, etc.)
    h.price_discount_markup eventuale sconto ricarico applicato, è un campo calcolato per differenza per far tornare il totale
    h.problem_description descrizione eventuale problema
    h.reference_1 persona di riferimento 1
    h.reference_2 persona di riferimento 2
    h.run_request campo di sistema
    h.shipped_by_marketplace 1 se è un ordine in logistica marketplace
    h.shipping_code codice metodo spedizione marketplace
    h.shipping_cost costo spedizione (eventuale costo sostenuto dal seller)
    h.shipping_insurance_price non utilizzato
    h.shipping_note note spedizione
    h.shipping_price spese spedizione (eventuale costo sostenuto dal buyer)
    h.shop campo di sistema
    h.status stato ordine
    h.status_message messaggio associato alo stato ordine (di norma un errore)
    h.status_old campo di sistema: stato ordine precedente
    h.supplier_code codice fornitore
    h.tags elenco tag associate all'ordine
    h.tracking codice tracking
    h.weight peso complessivo
    h.total_tax tasse totale (IVA) in valore assoluto (solo per ordini SellRapido Ecommerce)
    r.brand marca
    r.category_id id categoria prodotto marketplace
    r.category_name nome categoria prodotto marketplace
    r.cod_price non utilizzato
    r.courier_code codice corriere del marketplace, scari cato dal marketplace se disponibile
    r.created data creazione in SellRapido 
    r.date_payment non utilizzato
    r.date_shipping non utilizzato
    r.ean codice ean
    r.fields_lock elenco campi bloccati (campo di sistema)
    r.id id riga ordine SellRapido 
    r.image_url url immagine prodotto
    r.marketplace_fee commissioni marketplace
    r.modified data modifica in SellRapido 
    r.mpn codice prodotto del produttore
    r.note note
    r.on_demand_date data in cui il prodotto può essere spedito
    r.order_head rif id ordine SellRapido 
    r.order_row_supplier rif id riga ordine fornitore (se esiste)
    r.order_supplier non utilizzato
    r.order_supplier_code non utilizzato
    r.price prezzo prodotto (può essere o meno con IVA a seconda del marketplace)
    r.price_cost costo prodotto (valorizzato a mani o in base al listino di prevendita)
    r.price_discount_markup eventuale sconto ricarico applicato
    r.price_total total edi riga
    r.product_id id prodotto lato marketplace
    r.quantity quantità ordinata
    r.refund_date data rimborso
    r.refund_price importo rimborsato
    r.refund_reason ragione del rimborso
    r.shipping_code non utilizzato
    r.shipping_cost costo spedizione (eventuale costo sostenuto dal seller)
    r.shipping_insurance_price non utilizzato
    r.shipping_note note spedizione
    r.shipping_price spese spedizione (eventuale costo sostenuto dal buyer)
    r.sku SKU prodotto
    r.sku_parent SKU prodotto padre (per le varianti)
    r.stock_unloaded campo di sistema
    r.supplier id del fornitore
    r.title titolo
    r.title_extra non utilizzato
    r.tracking tracking a livello di riga (non conosco casi in cui è utilizzato)
    r.transaction_id id transazione lato marketplace (es: id transazione eBay)
    r.vat_perc percentuale IVA
    r.product_tax tasse unitarie (IVA) in valore assoluto (solo per ordini SellRapido Ecommerce)


    Aggiornamento stato ordini

    Questa API serve per aggiornare le informazioni di un ordine: 

    https://app.sellrapido.com/sr_company_ws/api/order/api_key/status

    In particolare, ti permette di aggiornare i seguenti dati:

    • lo stato 
    • le informazioni di tracking e corriere

    • la data di pagamento

    Attenzione:

    È possibile fare aggiornamenti massivi di più ordini con unica chiamata.

    È possibile aggiornare il tracking e corriere, ma non rimuoverli.

    È possibile aggiornare la data di pagamento, ma non rimuoverla.

    Metodo HTTP: POST

    Il body della richiesta deve avere la seguente forma:

    [
    {"id":1406, "status":"sent", "tracking":"test", "courier":59},

    {"id":1453, "status":"sent", "tracking":"test", "courier_code":"BARTOLINI1"},
    {"id":1442, "status":"accepted", "payment_date":"2020-10-20T02:30:00.000"},
    {"id":1443, "status":"standby", "tracking":null, "courier":null, "payment_date":"2020-10-20T02:30:00.000"},
    {"id":1453, "status":" sent ", "tracking":null, "courier":null, "payment_date":"2020-10-20T02:30:00.000", "shipping_note": "consegna effettuata di mattina"}
    ]  
     

    Ogni elemento dell'array è un aggiornamento di un diverso ordine

    • Id è l'id dell'ordine (obbligatorio)
    • Status è lo stato dell'ordine. Può avere i valori di standby, accepted, sent, cancelled (obbligatorio)
    • courier_code è alternativo a courier e rappresenta il codice parlante del corriere. Può essere uno dei seguenti valori: AWS, BARTOLINI1, DBSCHENKER, DHL, EBOOST, FEDEX, FERCAM, GLS, GLSFIX, MBE, NEXIVE_EXP, NEXIVE_REG, POSTE_ITALIANE_CRONO, SDA, SOGETRAS, SPEDIAMO.IT, TNT, UPS
    • Tracking è il codice di tracking che deve essere popolato assieme al courier
    • Payment_date: data del pagamento in formato ISO 8601
    • Shipping_note: note di spedizione, non obbligatorio

    Sono implementati vari controlli di coerenza.

    La chiamata può restituire un elenco di errori.
    I cambi di stato che hanno avuto successo (o non hanno prodotto nessuna modifica sul sistema) non compaiono nella risposta.

    Esempio di risposta con errori:

    [
    {
    "index": 0,
    "id": "1",
    "error_message": "order with id 1 has tracking but no courier"
    }
    ]

    • index identifica l'iesimo elemento dell'input. Può essere valorizzata a -1 nel caso non sia possibile far risalire l'errore a uno specifico elemento.
    • id si rifererisce all'id dell'ordine
    • error_message è una descrizione dell'errore


    Nel caso nessun cambio di stato abbia generato errori, la risposta sarà un elenco vuoto:

    [