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:
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: