Introduzione
Le API Qapla' v2 offrono una piattaforma avanzata per l'integrazione sia in lettura che in scrittura con sistemi di e-commerce proprietari o per quelli che non dispongono di un plugin o connettore specifico.
L'architettura si basa su uno stile RESTful che garantisce una gestione delle risorse intuitiva e conforme agli standard internazionali, semplificando l'integrazione e l'automazione dei processi.
- L'API è strutturata secondo i principi REST (RESTful API).
- Supporta richieste di tipo GET, POST, PUT, DELETE e PATCH, utilizzando il formato JSON sia per l'invio che per la ricezione dei dati.
- Le risposte includono codici di stato HTTP per indicare il risultato della richiesta (HTTP Status Codes).
- Il fuso orario di riferimento per tutte le date e i timestamp nelle API è UTC.
- Le date sono fornite nel formato ISO ISO 8601 (
YYYY-MM-DDTHH:MM:SSZ
). Esempio:2024-12-02T07:56:55Z
API Key
Per utilizzare le API, è necessario disporre di una API Key privata, che viene assegnata ai canali abilitati.
È possibile trovare l'API Key nel Control Panel nella sezione Canali.
L'API Key deve essere mantenuta riservata e protetta.
Ogni canale ha una o più API Key private, che definiscono i permessi e gli endpoint accessibili.
Autenticazione
L'autenticazione del canale avviene tramite il servizio di SSO di Qapla' seguendo il flusso Bearer Token Authentication.
Per ottenere un token di accesso (Access Token), è necessario inviare una richiesta POST all'endpoint dedicato con l'API Key del canale:
POST https://sso.qapla.it/auth/channel
La richiesta deve contenere il seguente JSON nel body:
{"apiKey":"API_KEY"}
apiKey (string) | L'API Key del canale Qapla'. |
---|
curl -X POST https://sso.qapla.it/auth/channel \ -H "Content-Type: application/json" \ -d '{"apiKey": "API_KEY"}'
Response Body 200
Descrizione
accessToken (string) | Il token di accesso utilizzato per autenticare tutte le richieste successive. Deve essere incluso come Bearer Token nell'intestazione HTTP `Authorization`. |
---|---|
tokenType (string) | Indica il tipo di token (sempre "Bearer"). |
expiresIn (int) | La durata del token in secondi (24 ore). |
scopes (array) | Elenco degli endpoint autorizzati per l'API Key corrente. |
Errori
Se si verifica un errore durante l'autenticazione, i seguenti codici di stato HTTP possono essere restituiti:
401 | Unauthorized: L'API Key non è valida o non ha i permessi necessari per accedere all'endpoint richiesto. |
---|---|
400 | Bad Request: La richiesta non è valida o mancano parametri obbligatori nel body della richiesta. |
Token di accesso
Il token di accesso deve essere incluso nell'intestazione HTTP `Authorization` di tutte le richieste successive, preceduto dalla stringa `Bearer`:curl -X GET https://api.qapla.it/v2/endpoint \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json"
Errori
Tutti gli errori restituiti dalle API Qapla' sono rappresentati tramite codici di stato HTTP standard.Ogni codice indica il tipo di errore riscontrato durante l'elaborazione della richiesta, fornendo un'indicazione chiara e conforme agli standard su eventuali problemi di autenticazione, validazione o utilizzo non corretto degli endpoint.
Codici HTTP
400 |
Bad Request: La richiesta non è valida o mancano parametri obbligatori nel body della richiesta. |
---|---|
401 |
Unauthorized: L'API Key non è valida o non ha i permessi necessari per accedere all'endpoint richiesto. |
403 |
Forbidden: Accesso negato. L'API Key non ha i permessi necessari o l'utente non è autorizzato. |
404 |
Not Found: L'endpoint specificato non esiste o la risorsa richiesta non è stata trovata. |
405 |
Method Not Allowed: Il metodo HTTP utilizzato (GET, POST, PUT, DELETE) non è supportato per questo endpoint. |
406 |
Not Acceptable: Il server non è in grado di generare una risposta nella lingua o nel formato richiesto dal client. |
409 |
Conflict: La richiesta non può essere completata a causa di un conflitto con lo stato attuale della risorsa. |
423 |
Locked: La risorsa richiesta è bloccata e non può essere modificata o accessibile. |
429 |
Too Many Requests: Il numero massimo di richieste è stato superato. Attendere prima di riprovare. |
500 |
Internal Server Error: Errore interno del server durante l'elaborazione della richiesta. |
503 |
Service Unavailable: Il servizio non è al momento disponibile. Riprova più tardi. |
Body
Il body JSON dell'errore.status | Il tipo di errore. |
---|---|
code | Il codice interno dell'errore. |
message | La descrizione dell'errore. |
Header
X-Error-Message | Il testo descrittivo dell'errore |
---|
Limiti di utilizzo
Il sistema di gestione delle richieste utilizza un algoritmo di Token Bucket per limitare il numero di chiamate API in un determinato intervallo di tempo, con i seguenti parametri:
Capacità del bucket | 120 | Numero massimo di richieste consentite in un determinato periodo di tempo. |
---|---|---|
Token per secondo | 2 | Il sistema si ricarica a un tasso di 2 richieste al secondo. |
Una richiesta multipla (ad esempio, per 100 spedizioni od ordini) viene valutata come 100 token.
HTTP Response Status Codes
Se viene superato il limite di utilizzo, la risposta sarà:
429
Too Many Requests
Abuso
L'abuso dell'API può portare al blocco temporaneo o permanente dell'API Key associata.
Parcel
Una Parcel (collo) viene identificata univocamente con:
- Canale, rappresentato dal Bearer Token
- Riferimento ordine (reference)
- Origine dell'ordine (origin)
POSTParcel
Permette di caricare uno o più parcel (colli) ad un riferimento ordine, questo prima che venga caricato un odine o creata una spedizione.L'ordine o la spedizione (etichetta) creata "erediteranno" i colli precedentemente caricati.
L'api può produrre se richiesta un'etichetta/segnacollo provvisoria in formato ZPL.
NB
L'autenticazione avviene tramite il Bearer Token ottenuto con il servizio di autenticazione.
POSThttps://api.qapla.it/v2/parcel
Body
Il body della richiesta deve essere un JSON contenente i seguenti parametri:*Parametro obbligatorio
reference*(string) | Il riferimento univoco dell'ordine che verrà successivamente caricato. |
---|---|
origin(string) |
L'origine dell'ordine, per esempio: shopify, amazon. Può essere nullo ed il sistema inserirà "API".
amazon, carrefour_es, cdiscount, ebay, ecwid, eprice, ibs, magento, magento2, manomano_de, manomano_es, manomano_fr, manomano_gb, manomano_it, prestashop, privalia_es, privalia_it, shopify, spartoo_be, spartoo_cn, spartoo_de, spartoo_es, spartoo_fr, spartoo_gb, spartoo_gr, spartoo_it, spartoo_nl, spartoo_pl, spartoo_pt, storeden, vtex, woocommerce, worten_es, worten_pt, mediaMarkt_de, modivo_pl, bricobravo, miravia_es
Confrontarsi con il nostro customer care per identificare il valore corretto.
|
weight length width height(float) |
Valori in kg e cm, con un massimo di 2 decimali delle dimensioni e del peso del collo.
NB
|
content(string) | Eventuale contenuto del collo. |
originCountry(string) | Il codice ISO 3166-1 alpha-2 del paese di origine del collo. |
code(string) | Il codice interno del cliente. |
notes(string) | Eventuali note da stampare sull'etichetta segnacollo provvisoria. |
Header
I parametri nell'header della richiesta devono essere impostati come segue:x-label-format(string) | ZPL Per ottenere l'etichetta/segnacollo in formato ZPL. |
---|
Body
hash(string) | L'hash univoco per ogni parcel/collo. Utilizzato per identificare nelle api GET e DEL univocamente il collo. | ||||
---|---|---|---|---|---|
number(int) | Il numero progressivo. | ||||
label |
L'etichetta nel formato richiesto (disponibile solo ZPL)
|
||||
totalParcelCount(int) | Il numero totale di colli caricati. |
Errori
Tutti gli errori restituiti dalle API Qapla' sono rappresentati tramite codici di stato HTTP standard.GETParcel
Permette di recuperare i dati di una singola parcel a partire dall'hash identificativo.GEThttps://api.qapla.it/v2/parcel/{PARCEL-HASH}
Parametri
hash(string) | L'hash identificativo della parcel |
---|
Body
number(int) | Il numero progressivo. |
---|---|
weight(float) | Il peso in Kg con un massimo di 2 decimali. |
length(float) | La lunghezza in cm con un massimo di 2 decimali. |
width(float) | La larghezza in cm con un massimo di 2 decimali. |
height(float) | L'altezza in cm con un massimo di 2 decimali. |
code(string) | Il codice interno. |
notes(string) | Eventuali note da stampare in etichetta. |
content(string) | Il contenuto della spedizione. |
originCountry(string) | Il codice ISO del paese di origine. |
labelFormat(string) | Il formato dell'etichetta. |
label(string) | Il contenuto dell'etichetta. |
createdAt(string) | La data di creazione. |
updatedAt(string) | La data di aggiornamento. |
DELETEParcel
Permette di cancellare una singola parcel identificata dall'hash.DELETEhttps://api.qapla.it/v2/parcel/{PARCEL-HASH}
Parametri
hash(string) | L'hash identificativo della parcel |
---|
Body
status(string) | Lo stato della richiesta |
---|---|
message(string) | Il messaggio di risposta |
deletedHash(string) | L'hash della parcel eliminata |
timestamp(string) | La data e l'ora della richiesta |
affectedRows(int) | Il numero di righe interessate |
Parcels
- Canale, rappresentato dal Bearer Token
- Riferimento ordine (reference)
- Origine dell'ordine (origin)
GETParcels
Restituisce la lista dei colli in base al riferimento ordine e all'origine.GEThttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}
Parametri
reference(string) | Il riferimento ordine. |
---|---|
origin(string) | L'origine dell'ordine. |
Body
totalParcelCount(int) | Il numero totale di colli. | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
parcels(array) | L'elenco dei colli.
|
DELETEParcels
Permette di cancellare tutti i colli di un ordine.DELETEhttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}
Parametri
reference(string) | Il riferimento ordine. |
---|---|
origin(string) | L'origine dell'ordine. |
Body
status(string) | Lo stato della richiesta |
---|---|
message(string) | Il messaggio di risposta |
deletedReference(string) | Il riferimento dell'ordine cancellato |
deletedOrigin(string) | L'origine dell'ordine cancellato |
timestamp(string) | La data e l'ora della richiesta |
affectedRows(int) | Il numero di righe interessate |