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-02T08:06:41Z

API Key

Per utilizzare le API, è necessario disporre di una API Key privata, che viene assegnata ai canali abilitati.

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

{"apiKey":"API_KEY"}

curl -X POST https://sso.qapla.it/auth/channel \
        -H "Content-Type: application/json" \
        -d '{"apiKey": "API_KEY"}'

Token di accesso

curl -X GET https://api.qapla.it/v2/endpoint \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json"

Errori

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

Body

Header

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:

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.

Postman Collection

POSTParcel

L'ordine o la spedizione (etichetta) creata "erediteranno" i colli precedentemente caricati.

NB
L'autenticazione avviene tramite il Bearer Token ottenuto con il servizio di autenticazione.

POSThttps://api.qapla.it/v2/parcel

GETParcel

GEThttps://api.qapla.it/v2/parcel/{PARCEL-HASH}

DELETEParcel

DELETEhttps://api.qapla.it/v2/parcel/{PARCEL-HASH}

GETParcels

GEThttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}

DELETEParcels

DELETEhttps://api.qapla.it/v2/parcels/{REFERENCE}-{ORIGIN}