Nuove API v2
Sono in corso di rilascio le nuove API v2, con nuove funzionalità e una nuova e più sicura modalità di autenticazione.
Introduzione
Le API forniscono la possibilità di integrare Qapla' sia in lettura che in scrittura con il tuo sistema di ecommerce proprietario o per il quale non è stato ancora implementato un plugin o un connector.
- L'API di Qapla è basata su REST.
- Accetta richieste GET, POST, PUT, DELETE e PATCH codificate JSON.
- Restituisce i valori codificati JSON.
- Il fuso orario di riferimento è il CEST, che corrisponde all'orario UTC+2 quando è in vigore l'ora legale, o UTC+1 quando è in vigore l'ora solare.
Ultima versione disponibile
Questa è la versione più recente delle API. Non tutte le API sono state migrate alla versione 1.3, mano a mano che saranno aggiunte nuove funzionalità, verranno aggiornate.
Le API non ancora aggiornate fanno ancora riferimento alla versione 1.2
Versioni precedenti
Le precedenti versioni di questa API sono mantenute ancora attive, ma considerate deprecate.Webhook
Qapla' ha anche un servizio Webhook che è parte integrante delle API.API Key
Per poter utilizzare le API è necessario essere a conoscenza delle API Key private assegnate al/ai tuo/i canale/i, che si trovano sul Control Panel nella sezione:Impostazioni \ [NOME_CANALE]
Questa chiave API deve essere protetta e mantenuta segreta.
Endpoint
https://api.qapla.it/[API_VERSION]/[ENDPOINT]
[API_VERSION] | È il valore di versione dell'API. |
[ENDPOINT] | È l'endpoint che devi chiamare. |
Response
La risposta JSON ad una Request utilizza questo formato standard[API_NAME] | Il nome dell'API consumata |
[OK/KO] | OK in caso di risposta positiva, KO In caso di errore |
[ERROR_MESSAGE] | È null in caso di OK e conterrà l'errore in caso di KO |
Limiti di utilizzo
Il sistema utilizza l'algoritmo TokenBucket con i seguenti parametri:
Bucket capacity | 120 | Maximum of 120 requests |
---|---|---|
Tokens per second | 2 | Refilling at a rate of 2 per second |
Una request multipla (es: pushShipment o pushOrder con 100 spedizioni od ordini) viene valutata come 100 token.
HTTP Response Status Codes
Un superamento del limite porterà al seguente response HTTP429
Too Many Requests
e al seguente errore di risposta da parte di qualunque API coinvolta
"error": "Too Many Requests"
Abuse
L'abuso dell'utilizzo porterà ad un BAN dell'API Key.Sandbox
Non esiste un ambiente di Sandbox vero e proprio. È sufficiente utilizzare il campo sandbox direttamente nelle chiamate API che lo supportano per utilizzare l'infrastrutture di test senza avere effetti operativi (come costi, richieste di presa al corriere, ecc..)Test
Una volta ottenuta l'API Key è possibile effettuare immediatamente un test di connessione utilizzado l'API getChannel.Spedizioni
- Canale, rappresentato dalla API Key
- Corriere, "courier"
- Tracking number, "trackingNumber"
pushShipment
pushShipment permette di caricare una o più spedizioni tramite una POST dei dati in formato JSON.In combinazione con il Webhook crea un sistema integrato di gestione delle spedizioni.
POSThttps://api.qapla.it/1.3/pushShipment/
Request
In questo esempio vengono caricate due spedizioni, una in formato "minimo" e una "completo".
Parametri
Esistono 3 tipi di modalità di caricamento delle spedizioni.
- "minimo" contenente 3 campi obbligatori*
- "necessario" per attivare i servizi aggiuntivi di comunicazione al cliente come Email transazionali, ecc.•
- "completo" con sempre i primi 3 campi obbligatori, ma che contiene tutte le informazioni
*Parametro obbligatorio
•Parametro necessario per attivare email transazionali e/o SMS
Il numero massimo di spedizioni inviabili per ogni singola request è 100.
apiKey(string) | La API Key assegnata al canale nel quale si desidera importare le spedizioni | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pushShipment(array) |
È un array di massimo 100 spedizioni da caricare.
|
Response Body200
Errori
In caso di errore invece ogni riga di spedizione verrà segnalata:
getShipment
getShipment permette di leggere lo stato di una spedizione tramite il tracking number, il riferimento ordine o l'ID.Per una gestione totale ed integrata del ciclo di aggiornamento delle spedizioni valuta anche il Webhook.
GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]
GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]
GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&id=[SHIPMENT_ID]
GEThttps://api.qapla.it/1.3/getShipment/?apiKey=[API_KEY]&custom1=[CUSTOM1]
Parametri
Parametro | Descrizione | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare | ||||||||||||||||||||||||
Parametri esclusivi | |||||||||||||||||||||||||
trackingNumber(string) | il tracking number interessato | ||||||||||||||||||||||||
reference(string) | il riferimento ordine | ||||||||||||||||||||||||
id(int) | ID della spedizione | ||||||||||||||||||||||||
custom1, custom2, custom3(string) | i campi custom1, custom2, custom3 | ||||||||||||||||||||||||
Parametri opzionali | |||||||||||||||||||||||||
lang | La lingua dei nomi degli stati Qapla' (it, en, es), default: it.
Esempio: &lang=en |
||||||||||||||||||||||||
data |
Il flag data specifica quali e quanti dati vogliamo ricevere, di default torna dei dati minimi sullo stato di avanzamento della spedizione.
Il parametro può essere combinato separato da virgole, ad esempio &data=consignee,historyper ottenere solo questi dati. |
Response Body200
Descrizione
result | Il risultato dell'operazione: OK o KO in caso di errore | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
error | L'errore in caso di result: KO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
version | La versione dell'API | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lang | La lingua richiesta / passata come parametro (default: it) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
count | Quante spedizioni sono presenti | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shipments | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
id | ID della spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
hash | L'hash della spedizione, utilizzato per esempio dalla pagina di tracking | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url | Indirizzo della pagina di tracking di questa spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reference | Il riferimento ordine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trackingNumber | Il tracking number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isDeleted | è true (valore boolean) se la spedizione è cancellata | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isArchived | è true (valore boolean) se la spedizione è archiviata | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
origin | L'origine della spedizione se caricata (es: magento, prestashop, amazon, ecc) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
courier |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
status |
Lo stato attuale della spedizione
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shipDate | La data di spedizione comunicataci al caricamento della spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
orderDate | La data dell'ordine comunicataci al caricamento della spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dateIns | La data di caricamento della spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
consignee |
I dati del destinatario
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
language | La lingua in cui "parlerà" la spedizione quando verranno inviate notifiche come email o SMS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
newTrackingNumber | L'eventuale nuovo tracking number assegnato alla spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
oldTrackingNumber | L'eventuale vecchio tracking number in caso venga popolato il campo newTrackingNumber | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasNewTrackingNumber | È true (valore boolean) se la spedizione ha ottenuto un nuovo tracking number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isTrackingNumber | È true (valore boolean) se il valore trackingNumber contiene il vero tracking number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trueTrackingNumber | Contiene l'eventuale "vero" tracking number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
altTrackingNumber | Contiene un eventuale tracking number alternativo nel caso la spedizione lo abbia cambiato a parità di corriere in corso di viaggio | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
returnTrackingNumber | Indica l'eventuale tracking number di ritorno se diverso da quello di andata | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isReturnShipment | È true (valore boolean) se la spedizione è una spedizione di reso / ritorno | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isCOD | È true (valore boolean) se la spedizione è in constrassegno | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amountText | L'importo testuale della spedizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount | L'importo come numero float | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isDelivered | È true (valore boolean) se la spedizione è consegnata | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isChild | È true (valore boolean) se la spedizione è "figlia" di un'altra spedizione, in questo caso verrà popolato il campo "parent" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
parent |
La spedizione "padre"
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasChildren | È true (valore boolean) se la spedizione ha dei "figli", in questo caso verrà popolato il campo "children" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
children |
È un array di spedizioni "child"
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom1 | Il valore custom1 come importato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom2 | Il valore custom2 come importato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom3 | Il valore custom3 come importato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
deliveryMode | Può assumere i valori "home" per una consegna direttamente al destinatario o "pickup" per una consegna diretta ad un punto di ritiro (Pickup point) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasFlag | È true (valore boolean) se la spedizione è stata "segnalata", in questo caso viene popolato il campo "flag" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
flag |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notifications |
Tutte le notifiche inviate per stato per questa spedizione. Ottenibile utilizzando il parametro data=notifications ed incluso se data=all
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trackingHistory |
È un array dei seguenti elementi
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
parcels |
I colli presenti nella spedizione. Ottenibile utilizzando il parametro data=parcels ed incluso se data=all
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rows |
Le righe dei prodotti presenti nella spedizione. Ottenibile utlizzando il parametro data=rows ed incluso se data=all
|
Errori
In caso di errore il campo "result" conterrà "KO" ed il error la descrizione dell'errore.{ "getShipment": { "result": "KO", "error": "[ERROR_MESSAGE]" } }
getShipments
getShipments permette di ricevere la lista delle spedizioni importate da Qapla' per data di inserimento, data di spedizione, data ordine.GEThttps://api.qapla.it/1.2/getShipments/?apiKey=[API_KEY]&[DATE]
Parametri
Parametro | Descrizione |
---|---|
apiKey | la API Key assegnata al canale che vogliamo interrogare |
[DATE]* | |
shipDate | data spedizione in formato ISO 8601 "YYYY-MM-DD" |
orderDate | data ordine in formato ISO 8601 "YYYY-MM-DD" |
dateIns | data di caricamento in formato ISO 8601 "YYYY-MM-DD" |
Response Body200
Descrizione
result(string) | Il risultato dell'operazione: OK o KO in caso di errore | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
error(string) | L'errore in caso di result: KO | ||||||||||||||||||||||||||||||||||||||
version(string) | La versione dell'API | ||||||||||||||||||||||||||||||||||||||
search(string) | Il parametro imputato come ricerca | ||||||||||||||||||||||||||||||||||||||
count(int) | Quante spedizioni sono presenti | ||||||||||||||||||||||||||||||||||||||
shipments(array) |
È un array che può contenere più di una spedizione
|
Errori
updateShipment
updateShipment permette di aggiornare una spedizione.PUThttps://api.qapla.it/1.2/updateShipment/
deleteShipment
deleteShipment permette di eliminare una spedizione.DELETEhttps://api.qapla.it/1.2/deleteShipment/
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare |
courier*(string) | il codice corriere della spedizione |
trackingNumber*(string) | il tracking number della spedizione |
Response Body200
undeleteShipment
undeleteShipment permette di ripristinare una spedizione.PATCHhttps://api.qapla.it/1.2/undeleteShipment/
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare |
courier*(string) | il codice corriere della spedizione |
trackingNumber*(string) | il tracking number della spedizione |
Response Body200
trackingByTimeFrame
trackingByTimeFrame permette di ottenere l'elenco delle spedizioni che hanno subito un aggiornamento dello stato del tracking compreso nel timeframe dateFrom / dateTo.GEThttps://api.qapla.it/1.2/trackingByTimeFrame/
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare |
Parametri opzionali | |
dateFrom(timestamp) | default: un'ora fa. In formato ISO 8601 "yyyy-mm-dd hh:mm:ss" |
dateTo(timestamp) | in formato ISO 8601 "yyyy-mm-dd hh:mm:ss" |
lang |
La lingua dei nomi degli stati Qapla' (it, en, es), default: it.
Esempio: &lang=en |
Response Body200
Descrizione
result | Il risultato dell'operazione: OK o KO in caso di errore |
---|---|
error | L'errore in caso di result: KO |
version | La versione dell'API |
lang | La lingua richiesta / passata come parametro (default: it) |
count | Quante spedizioni sono presenti |
shipments | La descrizione della spedizione |
Ordini
- Canale, rappresentato dalla API Key
- Riferimento ordine, "reference"
- Tracking number, "trackingNumber"
L'aggiornamento di un ordine avviene se durante una pushOrder, la data di aggiornamento "updatedAt" è maggiore di quella registrata.
pushOrder
pushOrder permette di caricare uno o più ordini tramite una POST dei dati in formato JSON.POSThttps://api.qapla.it/1.3/pushOrder/
Parametri
*Parametro obbligatorio
Il numero massimo di ordini inviabile per ogni singola request è 100.
apiKey*(string) | La API Key assegnata al canale che vogliamo interrogare | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
origin(string) | Origine dell'ordine, valori ammessi:
ahlens, aliexpress, allegro, alltricks, amazon, animalis, anthropologie, asos, atlasformen, auchan, bandq, beerwulf, bestsecret,
bhv, bigcommerce, bild, blackredwhite, blokker, boots, brandalley, bricobravo, bricodepot, bricomarche, bricoprive, bulevip, but, carrefour_es,
carrefour_fr, casadellibro, castorama, cdiscount, commercelayer, conforama, creavea, cultura, darty, debenhams, decathlon, douglas, ebay, ecwid,
elcorteingles, elkjop, ellos, empik, eprice, etsy, fanatics, feelunique, fnac, fonq, freepeople, fressnapf, gifi, greenweez_fr, handm, home24, ibs,
incomedia, lafayette, laredoute, leroyMerlin_it, magento, magento2, maisonDuMonde_es, maisonDuMonde_it, manomano, manomano_de, manomano_es, manomano_fr,
manomano_gb, manomano_it, matalan, mathon, maty, maykers, mediaMarkt_at, mediaMarkt_de, mediaMarkt_es, mediaMarkt_it, mediaMarkt_nl, miravia_es, modivo_pl,
mountainwh, natureetdeco, newcart, nocibe, obelink, pandacola, pccomponentes, perfumesclub, phonehouse, pixmania, placedestend, planetahuerto, pourdebon,
prestashop, printemps, privalia, privalia_es, privalia_it, privsportshop, public, quirumed, redcarepharmacy, rueducommerce, sarenza, shopapotheke, shopify,
shopware6, showroomprive, slood, spartoo, spartoo_be, spartoo_bg, spartoo_cn, spartoo_com, spartoo_comhr, spartoo_couk, spartoo_cz, spartoo_de, spartoo_dk,
spartoo_es, spartoo_fi, spartoo_fr, spartoo_gb, spartoo_gr, spartoo_hu, spartoo_it, spartoo_nl, spartoo_pl, spartoo_pt, spartoo_ro, spartoo_se, spartoo_si, spartoo_sk, sprinter_es,
stadium, storeden¤, superdrug, teamsystemcommerce¤tiendanimal, tradeinn, truffaut, twil, ubaldi, urbanoutfitters, venca, venteunique, vivino, vtex, watchfinder,
winesitting, woocommerce, wook, worten_es, worten_pt, yoox
¤storeden e teamsystemcommerce possono essere usati come sinonimi
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pushOrder(array) |
È un array di massimo 100 ordini da caricare.
|
Response Body200
Descrizione
version(string) | Il numero di versione di questa API | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
result(string) | È "OK" se la trasmissione è andata a buon fine, "KO" in caso di errore | ||||||||||
error(string) | L'eventuale messaggio di errore in caso di result "KO" | ||||||||||
count(int) | Quanti ordini inviati nella richiesta | ||||||||||
orders(array) |
È un array che corrisponde al numero di ordini inviati nella richiesta.
|
||||||||||
imported(int) | Contatore degli ordini importati | ||||||||||
updated(int) | Contatore degli ordini aggiornati | ||||||||||
deleted(int) | Contatore degli ordini cancellati | ||||||||||
skipped(int) | Contatore degli ordini saltati | ||||||||||
existing(int) | Contatore degli ordini già esistenti |
Errori
Il messaggio di errore viene riportato nel campo "error".getOrder
getOrder permette di recuperare un ordine.GEThttps://api.qapla.it/1.3/getOrder/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]
Parametri
Parametro | Descrizione | ||||||||
---|---|---|---|---|---|---|---|---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare | ||||||||
reference*(string) | il riferimento ordine | ||||||||
data |
Il flag data specifica quali e quanti dati vogliamo ricevere, di default torna dei dati minimi sullo stato di avanzamento della spedizione.
|
Response Body200
getOrders
getOrders permette di ricevere la lista degli ordini importati da Qapla'.GEThttps://api.qapla.it/1.2/getOrders/?apiKey=[API_KEY]&[DATE]
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare |
[DATE] | |
updatedAt | data aggiornamento ordine in formato ISO 8601 "YYYY-MM-DD" |
createdAt | data ordine in formato ISO 8601 "YYYY-MM-DD" |
dateIns | data di caricamento in formato ISO 8601 "YYYY-MM-DD" |
dateFrom / dateTo | forbice di date per il valore "updatedAt" in formato ISO 8601 "yyyy-mm-dd hh:mm:ss" |
Response Body200
deleteOrder
deleteOrder permette di eliminare un ordine.DELETEhttps://api.qapla.it/1.2/deleteOrder/
updateOrder
updateOrder è sopperita dall' impostazione pushOrder e si utilizza il parametro updatedAt per stabilire se l'ordine debba essere aggiornato.updatedAt*(YYYY-MM-DD HH:MM:SS) | Data di aggiornamento ordine. Attenzione Questa data viene usata per stabilire se aggiornare l'ordine su Qapla', ovvero se l'ordine è stato già importato da Qapla'. Un valore più recente di questo campo farà sì che Qapla' lo consideri come "ordine aggiornato" e quindi aggiorni tutti i dati precedentemente importati. |
---|
undeleteOrder
undeleteOrder permette di ripristinare un ordine eliminato.PATCHhttps://api.qapla.it/1.2/undeleteOrder/
detectOrderCourier
Questa API è attualmente in test. Richiedere l'attivazione al Customer Care.
Utile prima di una createLabel per identificare preventivamente il corriere da utilizzare.
È basata su 3 regole per identificare il corriere in base a peso, eventuale importo in contrassegno ed il CAP di destinazione.Se si è in possesso di chiare regole come ad esempio le seguenti:
Peso | COD | CAP | |
---|---|---|---|
minore o uguale a 3Kg | GLS | ||
maggiore di 3Kg | minore di 100€ | BRT | |
maggiore di 3Kg | maggiore di 100€ | minore di 70000 (nord) | GLS |
maggiore di 3Kg | maggiore di 100€ | maggiore di 70000 (sud) | BRT |
è possibile predeterminare e preassegnare il corriere all'ordine prima che l'etichetta venga creata, ad esempio con la createLabel.
POSThttps://api.qapla.it/1.2/detectOrderCourier/
Request
Parametri
*Parametro obbligatorio
Parametro | Descrizione |
---|---|
apiKey*(string) | La API Key del canale |
country*(string) | La nazione del destinatario in formato ISO 3166-1 alpha-2 (Esempio: IT) |
weight*(float) | Eventuale peso dell'ordine |
cod(float) | Importo della spedizione, se la spedizione è in contrassegno |
postCode(string) | CAP del destinatario |
Response Body200
Parametro | Descrizione |
---|---|
courier(json) | Contiene id, codice e nome del corriere identificato |
rule(json) | Contiene id, e nome della regola identificata |
request(json) | I parametri della request |
Errori
In caso di errore il campo "result" conterrà "KO" ed il campo "error" la descrizione dell'errore.Platforms
fetchPlatformOrders
fetchPlatformOrders permette di ricevere la lista degli ordini presenti su una platform.GEThttps://api.qapla.it/1.2/fetchPlatformOrders/?apiKey=[API_KEY]&platform=[PLATFORM]&orderFormat=[ORDERFORMAT]&skip
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | La API Key assegnata al canale che vogliamo interrogare |
platform(string) |
La platform associata, per esempio un marketplace. Se non viene indicata, viene considerata la platform (CMS) associata al canale. Se nessuna platform è associata al canale, il parametro diventa obbligatorio per indicare un marketplace.
Valori ammessi:
amazon, carrefour, cdiscount, ebay, ecwid, eprice, ibs, magento, magento2, manomano, prestashop, privalia, shopify, spartoo, storeden¤, teamsystemcommerce¤, vtex, woocommerce, worten, leroymerlin, greenweez, maisondumonde, mediamarkt,
bigcommerce, commercelayer, shopware6, aliexpress, allegro, sprinter, decathlon, bricobravo, miravia_es
¤storeden e teamsystemcommerce possono essere usati come sinonimi
|
dateFrom / dateTo(timestamp) | Forbice di date per il valore "updatedAt" in formato ISO 8601 "yyyy-mm-dd hh:mm:ss" |
orderFormat(string) | Se viene passato il valore (platform) verranno restituiti gli ordini in formato originale. Nel caso in cui non venga passato alcun valore i risultati verranno restituiti in formato standard (qapla). |
skip(string) | Se viene passato il parametro &skip (senza un valore) gli ordini verranno analizzati e saltati in caso lo stato ordine sia indicato come tra quelli da non considerare. |
Response Body200
Errori
In caso di errore il campo "result" conterrà "KO" ed il error la descrizione dell'errore.{ "fetchPlatformOrders": { "result": "KO", "error": "[ERROR_MESSAGE]" } }
updatePlatformOrder
updatePlatformOrder permette di aggiornare gli ordini presenti su una platform.PUThttps://api.qapla.it/1.2/updatePlatformOrder/
Autenticazione
L'autenticazione avviene tramite l'apiKey del canale, passando Q-API-Key nell'header della request
Parametro | Descrizione |
---|---|
Q-API-Key*(string) | L' API Key del canale. |
Parametri
Parametro | Descrizione |
---|---|
platform*(string) |
La platform associata, per esempio un marketplace.
Valori ammessi:
magento, magento2, prestashop, shopify, woocommerce, amazon, ibs, manomano, spartoo, carrefour, leroymerlin, greenweez, maisondumonde, mediamarkt,
bigcommerce, commercelayer, cdiscount, ecwid, shopware6, storeden¤, teamsystemcommerce¤, vtex, aliexpress, allegro, ebay, eprice, privalia, sprinter, worten, decathlon, bricobravo, miravia_es
¤storeden e teamsystemcommerce possono essere usati come sinonimi
|
reference(string) | Il riferimento alfanumerico dell'ordine. Da inserire, se richiesto, in base alla platform specifica utilizzata. |
orderID(int) | Riferimento numerico dell'ordine. Da inserire, se richiesto, in base alla platform specifica utilizzata. |
courier*(string) | Il codice corriere di Qapla' |
trackingNumber*(string) | Il tracking number dell'ordine da aggiornare |
setShipped(bool) | E' true se è impostata la spedizione. Da utilizzare a seconda delle peculiarità della platform utilizzata. |
setDelivered(bool) | E' true se è impostata la consegna. Da utilizzare a seconda delle peculiarità della platform utilizzata. |
storeCountry(string) | Il codice nazione in formato iso 2 del marketplace. (se richiesto) |
trackingUrl(string) | Eventuale URL per visualizzare informazioni sul tracking |
Peculiarità
setShipped o setDelivered sono obbligatori.
La request di aggiornamento con setShipped e trackingNumber deve essere ripetuta due volte a distanza di almeno 1 per policy del marketplace che richiede un intervallo di un'ora tra gli stati Ready To Ship e Shipped.
La request di aggiornamento con setDelivered va effettuata una sola volta a distanza di almeno 12 ore dalla seconda request con setShipped per policy del marketplace che richiede un intervallo di 12 ore tra gli stati Shipped e Delivered.
Response Body200
Etichette
createLabel
createLabel permette di creare una etichetta in formato PDF o ZPL (impostazioni da configurare sul Control Panel).Richiedere l'attivazione al Customer Care.
POSThttps://api.qapla.it/1.3/createLabel/
Test
È possibile ottenere una "dummy label" di test utilizzando il corriere avente codice GENERIC.Request
Parametri
*Parametro obbligatorio
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiKey*(string) | La API Key del canale | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sandbox(boolean) | È true se si vuole utilizzare la sandbox (modalità test) Attenzione: questo parametro funziona se il corriere è già stato correttamente impostato sul canale. Rivolgersi al Customer Care di Qapla'. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
origin(string) | Origine della spedizione, valori ammessi:
ahlens, aliexpress, allegro, alltricks, amazon, animalis, anthropologie, asos, atlasformen, auchan, bandq, beerwulf, bestsecret,
bhv, bigcommerce, bild, blackredwhite, blokker, boots, brandalley, bricobravo, bricodepot, bricomarche, bricoprive, bulevip, but, carrefour_es,
carrefour_fr, casadellibro, castorama, cdiscount, commercelayer, conforama, creavea, cultura, darty, debenhams, decathlon, douglas, ebay, ecwid,
elcorteingles, elkjop, ellos, empik, eprice, etsy, fanatics, feelunique, fnac, fonq, freepeople, fressnapf, gifi, greenweez_fr, handm, home24, ibs,
incomedia, lafayette, laredoute, leroyMerlin_it, magento, magento2, maisonDuMonde_es, maisonDuMonde_it, manomano, manomano_de, manomano_es, manomano_fr,
manomano_gb, manomano_it, matalan, mathon, maty, maykers, mediaMarkt_at, mediaMarkt_de, mediaMarkt_es, mediaMarkt_it, mediaMarkt_nl, miravia_es, modivo_pl,
mountainwh, natureetdeco, newcart, nocibe, obelink, pandacola, pccomponentes, perfumesclub, phonehouse, pixmania, placedestend, planetahuerto, pourdebon,
prestashop, printemps, privalia, privalia_es, privalia_it, privsportshop, public, quirumed, redcarepharmacy, rueducommerce, sarenza, shopapotheke, shopify,
shopware6, showroomprive, slood, spartoo, spartoo_be, spartoo_bg, spartoo_cn, spartoo_com, spartoo_comhr, spartoo_couk, spartoo_cz, spartoo_de, spartoo_dk,
spartoo_es, spartoo_fi, spartoo_fr, spartoo_gb, spartoo_gr, spartoo_hu, spartoo_it, spartoo_nl, spartoo_pl, spartoo_pt, spartoo_ro, spartoo_se, spartoo_si, spartoo_sk, sprinter_es,
stadium, storeden¤, superdrug, teamsystemcommerce¤tiendanimal, tradeinn, truffaut, twil, ubaldi, urbanoutfitters, venca, venteunique, vivino, vtex, watchfinder,
winesitting, woocommerce, wook, worten_es, worten_pt, yoox
¤storeden e teamsystemcommerce possono essere usati come sinonimi
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reference*(string) | Il riferimento alfanumerico dell'ordine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
orderID(string) | Eventuale riferimento numerico dell'ordine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
courier*(string) | Il codice corriere di Qapla' | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
courierService*(string) | Eventuale tipo del servizio del corriere; per esempio può essere il codice contratto di GLS Italy. Se il campo è vuoto o non viene inviato il default è '0'. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
name*(string) | Nome del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
address*(string) | Indirizzo del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
city*(string) | Città del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
state*(string) | Provincia del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
postCode*(string) | CAP del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
country*(string) | La nazione del destinatario in formato ISO 3166-1 alpha-2 (Esempio: IT) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
email(string) | Email del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
telephone(string) | Telefono del destinatario | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount(float) | Importo della spedizione. Specificare solo un separatore (il punto) per indicare i decimali, e non utilizzare separatori per indicare le migliaia. Indicare al massimo due cifre decimali. Esempio: 2340.23 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shippingCost(float) | Costo della spedizione. Specificare solo un separatore (il punto) per indicare i decimali, e non utilizzare separatori per indicare le migliaia. Indicare al massimo due cifre decimali. Esempio: 9.35 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currencyCode(string) | Codice valuta ISO 4217 (default: EUR) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
isCOD(boolean) | È true se il pagamento è in contrassegno | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment(string) | Eventuale metodo di pagamento dell'ordine. Può essere impostato su CONTRASSEGNO solo se anche isCOD è impostato a true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notes(string) | Eventuali note dell'ordine | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
parcels(int|array) |
Eventuali colli dell'ordine. Può anche essere definito come array indicando le informazioni di ogni singolo collo:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
weight(float) | Eventuale peso dell'ordine (non valido se "parcels" è un array) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
length(float) | Eventuali misure: lunghezza (non valido se "parcels" è un array) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
width(float) | Eventuali misure: profondità (non valido se "parcels" è un array) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
height(float) | Eventuali misure: altezza (non valido se "parcels" è un array) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shippingCODPaymentOption(string) | La modalità di pagamento dell'eventuale contrassegno se diversa dalle impostazioni di default (da concordarsi) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shippingInsurance(float | string) |
Eventuale importo assicurato ALL-IN: valorizzare il campo "shippingDeliveryOptions" inserendo la stringa: ALLIN Per la generazione diretta con SDA, il valore va passato sotto forma di stringa, specificando uno dei seguenti codici:
Per la generazione diretta con CRONO PTI, il valore va passato sotto forma di stringa, specificando uno dei seguenti codici:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shippingDeliveryOptions(string | JSON) |
Per il corriere PTI bisogna usare un JSON strutturato come i seguenti esempi
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shippingRequiredDeliveryDate(YYYY-MM-DD) | La data in formato YYYY-MM-DD di richiesta consegna | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
latestShipDate(string) | Spedizione entro questa data in formato YYYY-MM-DD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
latestDeliveryDate(string) | Consegna entro questa data in formato YYYY-MM-DD | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
pickupDate(YYYY-MM-DD) | La data in formato YYYY-MM-DD di ritiro richiesta al corriere
Per il corriere SDA, se questo campo non viene specificato in fase di creazione dell'etichetta, in fase di trasmissione verrà automaticamente assegnato il giorno lavorativo successivo a quello della trasmissione |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gSpedPrinterID(int) | Eventuale id stampante (user_id) per la Labeling Machine di Gsped (da concordarsi) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
printNodePrinterID(int | string) | Eventuale id o nome della stampante da utilizzare con PrintNode (da concordarsi) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
forceReprint(int) | Se impostato a 1 forza nuovamente la stampa dell'etichetta tramite PrintNode; valido se utilizzato con "printNodePrinterID" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
content(string) | Il contenuto della merce che potrà essere presente sull'etichetta(dipende dal corriere) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom1(string) | Campo personalizzato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom2(string) | Campo personalizzato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom3(string) | Campo personalizzato | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sender |
È il mittente della spedizione se diverso dall'intestatario del contratto. AttenzioneSe il mittente è gia stato creato sul Control Panel o già inviato precedentemente questo viene codificato e sarà sufficiente inviare il solo codice. "sender": "codicedelsender"
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tradeDocuments(array) |
Documenti elettronici da trasmettere al corriere. È possibile caricare più di un file per spedizione. Il peso massimo di ogni file è 5 MB. Per il momento disponibile solo per i corrieri DHL, FedEx e UPS. Trasmesso come un array di oggetti, con tre elementi obbligatori ciascuno:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rows(array) |
È un array di "righe ordine". Non è obbligatorio, ma se popolato ha alcuni dati che lo sono.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
assemblyTypes(array) |
Eventuale elenco di tipologie di montaggio, una per prodotto, per i corrieri che supportano questa informazioni
Disponibile per il "courierService" 20 (HD). Deve essere specificato un elemento per ogni elemento di rows. I valori disponibili per "code":
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PUDO(object) |
Permette di impostare un punto di Pick-up o Drop-off del ritiro della merce. Ogni campo va compilato in base alla necessità del corriere. Far riferimento alle tabelle poco sotto
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice(object) |
Permette di impostare le informazioni relative alla fattura associata alla spedizione, utile per le spedizioni che devono passare la dogana.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dangerousGoods(JSON) |
Per il corriere FEDEX bisogna usare un JSON strutturato come segue parcel: rappresenta il numero del parcel che contiene i dangerous good (nell'esempio una spedizione con 3 parcels di cui solo il primo e il terzo contengono dangerous goods)
type: battery
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
forceLabelsOutput(int) | Se impostato a 1, la api "createLabel" restituirà le etichette generate anche quando viene stampata con PrintNode o GLM. Utilizzabile solo se "printNodePrinterID" o "gSpedPrinterID" sono a loro volta impostati. Valore di default: 0 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
goodsCode(string) |
Response Body200
Parametro | Descrizione |
---|---|
isShipped(boolean) | È true se l'ordine è già stato etichettato e restituisce l'etichetta già creata. |
id(int) | L'id della spedizione. Importante per invocare altre API. |
trackingNumber(string) | Il tracking number della spedizione. |
returnTrackingNumber(string) | Se richiesta etichetta di reso contestuale |
format(string) | Il formato dell'etichetta
|
labels(array) | Un array con il base64 delle etichette ottenute (potrebbero esserci più etichette per più colli o resi, ecc.).
Oppure Lo ZPL per la stampa su Zebra, come configurato sul Control Panel. |
Errori
In caso di errore il campo "result" conterrà "KO" ed il campo "error" la descrizione dell'errore.deleteLabel
deleteLabel permette di eliminare un'etichetta creata con createLabel.Questa API è attualmente in test. Richiedere l'attivazione al Customer Care.
DELETEhttps://api.qapla.it/1.2/deleteLabel/
getLabel
getLabel permette scaricare un'etichettta precedentemente creata su Qapla' nel formato originale del corriere (PDF, JPG o ZPL).Attenzione: la getLabel NON funziona con le dummy label create con il corriere GENERIC (anche con la createLabel).
GEThttps://api.qapla.it/1.2/getLabel/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]
GEThttps://api.qapla.it/1.2/getLabel/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]
GEThttps://api.qapla.it/1.2/getLabel/?apiKey=[API_KEY]&id=[SHIPMENT_ID]
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | la API Key assegnata al canale che vogliamo interrogare |
Parametri esclusivi | |
trackingNumber(string) | il tracking number interessato |
reference(string) | il riferimento ordine |
parcel(int) | Il numero del collo (default = 1) - Disponibile solo per le etichette in formato PDF |
id(int) | l'id della spedizione |
json(string) | se passato (es: &json) forza la response come JSON |
getReturnLabel(string) | se passato (es: &getReturnLabel) restituisce l'etichetta di reso contestuale |
Response Body200
L'etichetta con il corretto content type (JPG, PDF o testo per la ZPL)
Oppure, se usato il parametro &json
Errori
In caso di errore il campo "result" conterrà "KO" ed il error la descrizione dell'errore.checkLabel
checkLabel permette di verificare lo stato di una etichetta precedentemente creata.GEThttps://api.qapla.it/1.2/checkLabel/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]
GEThttps://api.qapla.it/1.2/checkLabel/?apiKey=[API_KEY]&reference=[ORDER_REFERENCE]
GEThttps://api.qapla.it/1.2/checkLabel/?apiKey=[API_KEY]&id=[SHIPMENT_ID]
Parametri
Parametro | Descrizione |
---|---|
apiKey*(string) | La API Key assegnata al canale che vogliamo interrogare |
Parametri esclusivi | |
trackingNumber(string) | Il tracking number interessato |
reference(string) | Il riferimento ordine |
id(int) | L'id dell'etichetta |
Response Body200
Errori
In caso di errore il campo "result" conterrà "KO" e il campo error la descrizione dell'errore.confirmLabel
confirmLabel permette di confermare e trasmettere al corriere le etichette create con createLabel e di ottenere la Distinta di carico (borderò/manifest) in formato PDF .Richiedere l'attivazione al Customer Care.
POSThttps://api.qapla.it/1.3/confirmLabel/
Request
Parametri
Attenzione Utilizzare "labelCreationDate" oppure "labelID".*Parametro obbligatorio
Parametro | Descrizione |
---|---|
apiKey*(string) | La API Key del canale |
courier*(string) | Il codice corriere di Qapla' |
labelCreationDate*(date) | La data della creazione etichette in formato ISO 8601 "YYYY-MM-DD" |
labelID*(array) |
Un array degli ID delle spedizioni ottenuto con createLabel Parametro non supportato per questo corriere, utilizzare solo il parametro labelCreationDate |
Response Body200
Parametro | Descrizione |
---|---|
courier(string) | Il codice del corriere |
number(string) | Il numero della conferma |
date(string) | La data di conferma |
shipments(int) | Il numero di spedizioni confermate |
error(array|string) | Errori riscontrati in fase di conferma |
manifest(string) | Il manifest in PDF codificato Base64 |
Errori
In caso tutte le spedizioni siano andate in errore, il campo "result" conterrà "KO" ed il campo "error" sarà una stringa contenente la descrizione dell'errore.In caso contrario il campo "error" sarà un array contenente i dettagli dei singoli errori.
Corrieri
getCouriers
getCouriers permette di richiedere l'elenco dei corrieri sia totale, sia per singola nazione /ragione.GEThttps://api.qapla.it/1.2/getCouriers/?apiKey=[API_KEY]&country=[COUNTRY_LIST]&code=[COURIER_CODE]
Parametri
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiKey | la API Key assegnata al canale che vogliamo interrogare | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parametri opzionali | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
country | vuoto per tutti i corrieri, o un elenco di valori nazione separati da virgolacountry=it,fr,globalI valori disponibili sono:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
code | Il codice Qapla' del corrierecode=BRT |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hasLabels | Seleziona i corrieri che hanno la generazione etichette su Qapla' |
Response Body200
Il seguente URL
GEThttps://api.qapla.it/1.2/getCouriers/?apiKey=[API_KEY]&country=globaldarà come risultato:
detectCourier
detectCourier cerca di determinare il corriere dal tracking number fornito, rispondendo con un elenco di corrieri.GEThttps://api.qapla.it/1.2/detectCourier/?apiKey=[API_KEY]&trackingNumber=[TRACKING_NUMBER]
getPudos
getPudos permette di richiedere l'elenco dei PUDO (Pick Up Drop Off points) di più corrieri contemporaneamente.Richiedere l'attivazione al Customer Care.
POSThttps://api.qapla.it/1.2/getPudos/
Request
Parametri
*Parametro obbligatorio
Parametro | Descrizione |
---|---|
apiKey*(string) | La API Key del canale. Può essere, in alternativa, fornita come parametro di query nell'URL della richiesta, sempre utilizzando il metodo http POST. Esempio: POSThttps://api.qapla.it/1.2/getPudos/?apiKey=[API_KEY] |
postCode*(string) | CAP della località di cui si intende cercare i PUDO |
country*(string) | Codice ISO 3166-2 della nazione in cui è localizzato il postCode. Non viene effettuato un controllo sulla qualità del codice |
couriers(array) | Elenco dei “Codici corriere” di Qapla' di cui si vuole conoscere i PUDO. I codici corriere validi sono BRT, DHL, DHL-PAKET, DHLPARCEL-ES, FEDEX, FERMOPOINT, GLS, INPOST, PTI, UPS, CORREOS, TIPSA, CORREOS-EXPRESS, MRW-ES, SEUR, NACEX-ES e SENDING. Se questo parametro non viene specificato o viene lasciato vuoto, verranno recuperati i PUDO di tutti i corrieri validi e configurati su Qapla'. |
province(string) | Provincia della località oggetto di ricerca |
city(string) | Città/comune della località oggetto di ricerca (obbligatorio per TIPSA) |
street(string) | Indirizzo, completo di eventuale numero civico |
radius(number) | Raggio, espresso in KM, entro il quale limitare la ricerca dei PUDO. Specificare un valore ≤ 0 equivale a non specificare nessun raggio |
limit(number) | Numero di PUDO restituiti per ogni corriere. Specificare un valore ≤ 0 equivale a non specificare nessun limite, in questo caso il corriere restituirà il suo default |
Response Body200
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
result(string) | Indica se l'operazione è andata a buon fine, i valori possibili sono “OK” e “KO” | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
error(string) | Contiene la descrizione dell'eventuale errore che è stato sollevato, vuoto se result = “OK” | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data(array) |
Array di oggetti contenenti l'elenco dei PUDO. Ogni elemento dell'array corrisponde alla risposta ottenuta da un corriere
|
Business Days
Un oggetto dell'array businessDays rappresenta un giorno di apertura settimanale e presenta diversi attributi:
Parametro | Descrizione |
---|---|
day(int) | Indica il numero del giorno della settimana secondo la codifica ISO 8601 ( 1 = Lunedì…7 = Domenica) |
dayName(string) | Il nome del giorno della settimana in inglese |
dayNameIT(string) | Il nome del giorno della settimana in italiano |
businessHours(array) | Array di oggetti formati da due attributi, “open” e “close”, entrambi di tipo string, rappresentanti un orario nel formato “hh:mm” |
getQuotes
getQuotes permette di richiedere preventivi di spedizione a più corrieri per più servizi contemporaneamente.Richiedere l'attivazione al Customer Care.
POSThttps://api.qapla.it/1.3/getQuotes/
Request
Header
*Parametro obbligatorio
Parametro | Descrizione |
---|---|
x-api-key*(string) | L' API Key del canale. |
x-sandbox(string) |
Richiede l'esecuzione in sandbox per test, i valori restituiti in questa modalità potrebbero non essere realistci. Valori ammessi "true" o "false". GLS-ITA Non fornisce un ambiente sandbox, quindi le richieste vengono inviate ai server di produzione. |
Body
*Parametro obbligatorio
Parametro | Descrizione | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
reference*(string) | Codice di riferimento univoco, viene reinviato nella risposta, accetta solo lettere maiuscole, lettere minuscole, numeri e i simboli "-", "_" e "." | ||||||||||
senderCode(string) |
Codice mittente Qapla' da usare per il preventivo. Se valorizzato la procedura utilizzerà i dati del mittente del Canale con tale codice; se il valore inserito è inesistente ritornerà un errore; in caso non venga valorizzato la procedura utilizzerà il mittente di default o l'indirizzo dell'Azienda. NOTA: per GLS-ITA non è possibile specificare un senderCode. |
||||||||||
recipient*(object) | Destinatario
|
||||||||||
currency(string) | Valuta usata per valorizzare i campi monetari e in cui si richiede il preventivo espressa in stringa di tre caratteri. Se non specificata viene considerato il valore "EUR" Nessuna conversione viene effettuata I seguenti corrieri non supportano la scelta della valuta e riportano errore se viene richiesta qualsiasi valuta diversa da EUR: GLS-ITA, LICCARDI Inoltre i corrieri possono restituire preventivi in valuta diversa da quella qui indicata. La valuta del preventivo viene riportata nella risposta. |
||||||||||
amountShipment*(float) | Valore della spedizione, nella valuta specificata dal campo currency. Formato float con 2 decimali senza simboli per la valuta (#.##). | ||||||||||
amountInsurance(float) | Valore assicurato della spedizione, nella valuta specificata dal campo currency o in Euro per i corrieri che non lo supportano. Formato float con 2 decimali senza simboli per la valuta (#.##) Non valorizzare (o valorizzare con 0) se non si vuole il servizio di assicurazione della merce. |
||||||||||
amountCash(float) | Valore del contrassegno della spedizione, nella valuta specificata dal campo currency o in Euro per i corrieri che non lo supportano. Formato float con 2 decimali senza simboli per la valuta (#.##). Non valorizzare (o valorizzare con 0) se non si vuole il servizio di contrassegno. |
||||||||||
parcels*(array) | Lista dei colli nella spedizione
|
||||||||||
couriers(array) | Elenco dei "Codici corriere" di Qapla' di cui si vuole ottenere il preventivo. I codici corriere validi sono DHL, FEDEX, GLS-ITA, LICCARDI, TNT-ITA, UPS e AMAZON-SHIPPING. Se questo parametro non viene specificato o viene lasciato vuoto, verranno richiesti i preventivi di tutti i corrieri validi e configurati su Qapla'. |
Response Body200
Parametro | Descrizione | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
result(string) | Indica se l'operazione è andata a buon fine, i valori possibili sono “OK” e “KO”. | |||||||||||||||||||||||||||||||||||||||||||||||||||||
version(string) | Versione della API che ha generato la risposta. | |||||||||||||||||||||||||||||||||||||||||||||||||||||
reference(string) | Ripete il campo reference della richiesta. | |||||||||||||||||||||||||||||||||||||||||||||||||||||
quotationId(string) | Identificatore univoco della richiesta assegnato dal nostro sistema (formato UUIDv4). | |||||||||||||||||||||||||||||||||||||||||||||||||||||
startTimestamp(string) | Data e ora in cui la richiesta è stata ricevuta (formato RFC3339). | |||||||||||||||||||||||||||||||||||||||||||||||||||||
finishTimestamp(string) | Data e ora in cui la richiesta è stata evasa (formato RFC3339). | |||||||||||||||||||||||||||||||||||||||||||||||||||||
couriers(array) | Array di oggetti rappresentanti le risposte per ogni corriere interrogato
|
apiVirtual
apiVirtual permette di aggiornare lo stato di una spedizione del corriere virtuale.POSThttps://api.qapla.it/virtual/
Parametri
*Parametro obbligatorio
apiKey*(string) | La API Key assegnata al canale che vogliamo interrogare | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVirtual(array) |
È un array che può contenere massimo 100 aggiornamenti.
|
Response Body200
Errori
In caso di errore il campo "result" conterrà "KO" ed il error la descrizione dell'errore.Canali
getChannel
getChannel permette di ottenere informazioni sul canale collegato all'API Key e alla azienda che lo ha creato.GEThttps://api.qapla.it/1.2/getChannel/?apiKey=[API_KEY]
checkChannel
Permette di verificare le connessioni con la piattaforma e i marketplace configurati sul canale.GEThttps://api.qapla.it/1.2/checkChannel/?apiKey=[API_KEY]
getChannelMonitor
getChannelMonitor permette di ottenere informazioni sull'utilizzo del canale collegato all'API Key in un certo periodo.GEThttps://api.qapla.it/1.2/getChannelMonitor/?apiKey=[API_KEY]
createChannel
Permette di creare un nuovo canale.POSThttps://api.qapla.it/1.2/createChannel/
Request
Parametri
*Parametro obbligatorio
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiKey*(string) | La API Key del canale | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
createChannel*(object) |
|
Response Body200
Errori
In caso di errore il campo "result" conterrà "KO" ed il campo "error" la descrizione dell'errore.updateChannel
Permette di modificare alcune impostazioni del canale.PATCHhttps://api.qapla.it/1.2/updateChannel/
deleteChannel
Permette di eliminare uno specifico canale.DELETEhttps://api.qapla.it/1.2/deleteChannel/
Misc
getCredits
getCredits permette di ottenere i crediti rimanenti sul proprio account premium.GEThttps://api.qapla.it/1.2/getCredits/?apiKey=[API_KEY]
Parametri
Parametro | Descrizione |
---|---|
apiKey | la API Key assegnata al canale che vogliamo interrogare |
Response Body200
Descrizione
result(string) | Il risultato dell'operazione: OK o KO in caso di errore |
---|---|
error(string) | L'errore in caso di result: KO |
credits(int) | I crediti rimanenti |
date(string) | La data di aggiornamento del conteggio |
getQaplaStatus
getQaplaStatus permette di ottenere l'elenco dettagliato degli stati spedizione Qapla'.GEThttps://api.qapla.it/1.2/getQaplaStatus/?apiKey=[API_KEY]&lang=[LANG]&id=[ID]
Parametri
Parametro | Descrizione |
---|---|
apiKey(string) | la API Key assegnata al canale che vogliamo interrogare |
Parametri opzionali | |
lang(string) | La lingua dei nomi degli stati Qapla' (it, en, es), default: it.
Esempio: &lang=en |
id(int) | Eventuale id del quale si vuole ottenere informazioni Esempio: &id=3 |
Response Body200
result(string) | Il risultato dell'operazione: OK o KO in caso di errore | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
error(string) | L'errore in caso di result: KO | ||||||||||||||||
version(string) | La versione dell'API | ||||||||||||||||
qaplaStatus(array) |
È un array di stati
|
Script
Tracking Script
Inserendo e configurando il nostro Tracking Script, è possibile ottenere il tracking in qualunque parte del sito.
<!-- Place this code after <body> tag --> <script type="text/javascript"> let apiKey = "7b1b7235"; // your channel's public API Key let reference = "104"; // your order's reference // let noCSS = true; // let compact = true; // let lang = "en"; </script> <script type="text/javascript" src="https://api.qapla.it/js/1.2/qapla-tracking.min.js"></script> <!-- Place this element where you want to display the Qapla' Tracking --> <div id="qapla-tracking"></div>
Parametri
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiKey*(string) | La API KEY “pubblica” presente nella configurazione del canale di vendita sul Control Panel (CP) di Qapla’. | ||||||||||||||||||||||||||||||||||
reference*/ trackingNumber*(string) | Tracciare per riferimento ordine o per tracking number. | ||||||||||||||||||||||||||||||||||
noCSS(bool) | se true non include il css standard, permettendo un override. | ||||||||||||||||||||||||||||||||||
compact(bool) | se true visualizza una versione compatta, senza gli stati propri del corriere. | ||||||||||||||||||||||||||||||||||
lang(string) | se impostato mostra gli stati del corriere nella lingua selezionata. Se non impostato viene utilizzato il default ('it')
|
Risultato
Il risultato è un HTML che verrà inserito dentro l'elemento con id qapla-tracking avente il seguente contenuto.Help
Qapla' Status
È l'interpretazione dello stato della spedizione con dei valori che Qapla' assegna a ciascun possibile stato del corriere.
id | detailID | Nome | Descrizione | |
---|---|---|---|---|
0 | ATTESA ELABORAZIONE | La gestione automatica di interrogazione del corriere non è ancora stata eseguita. | ||
1 | IN SOSPESO | La spedizione è stata trovata ma non ci sono ancora notizie da parte del corriere. | ||
2 | ATTESA RITIRO | Il corriere non ha ancora ritirato la spedizione. | ||
20 | PARTITO | La spedizione è partita. | ||
3 | IN TRANSITO | La merce è in transito. | ||
50 | IN LAVORAZIONE | Spedizione in lavorazione | ||
50 | 1 | IN LAVORAZIONE • DOGANA | ||
4 | IN CONSEGNA | Spedizione in consegna. | ||
5 | TENTATIVO DI CONSEGNA FALLITO | La consegna è fallita. Pre-allarme per possibili problemi. | ||
8 | RITARDO | La spedizione sta subendo dei ritardi. | ||
6 | ECCEZIONE | Viene segnalato un qualche problema che può essere generico o spiegato da ulteriori icone. | ||
6 | 1 | ECCEZIONE • GIACENZA | La spedizione è in giacenza | |
6 | 2 | ECCEZIONE • SPEDIZIONE IN RIENTRO / RIFIUTATA | La spedizione è stata rifiutata e la merce è in rientro. | |
6 | 3 | ECCEZIONE • DANNEGGIAMENTO | Il corriere segnala che la merce risulta danneggiata. | |
6 | 4 | ECCEZIONE • SMARRIMENTO | Il corriere segnala che la merce risulta smarrita. | |
6 | 5 | ECCEZIONE • CONSEGNA PARZIALE | ||
10 | PUNTO DI RITIRO | La spedizione è stata consegnata in un Punto di Ritiro. | ||
95 | RIENTRATO | La spedizione è rientrata al mittente. | ||
99 | CONSEGNATO | La spedizione è stata consegnata al destinatario. |