API EasyParcel
L'API EasyParcel quota e acquista spedizioni, restituisce lettere di vettura e tracking, e permette alla tua rete di clienti di gestire il credito. Questo riferimento è generato dal contratto OpenAPI ed è pubblicato prima dell'implementazione.
Ogni operazione di queste pagine è contrassegnata in arrivo: il contratto è pubblicato prima dell'implementazione, così puoi pianificare l'integrazione. Le forme possono ancora cambiare finché un'operazione non è rilasciata.
URL base
Invia ogni richiesta in HTTPS. Il percorso dopo l'URL base è lo stesso ovunque: GET /shipments/{shipment_id} è sempre GET /shipments/{shipment_id} sotto l'URL base.
URL base
https://api.parcelabs.com/easyparcelContratto 321c71e (321c71e)
Autenticazione
Invia la tua chiave API nell'header X-API-Key a ogni chiamata, qualunque URL base tu usi. È l'unica credenziale: non esistono token di accesso né l'header Authorization. La chiave non è mai accettata nel percorso né nella query string. Ciò che una chiave può fare è una proprietà della chiave: GET /account elenca le funzioni abilitate. Le chiavi possono essere limitate a determinati indirizzi IP: una chiamata da un altro indirizzo riceve 403 IP_NOT_ALLOWED. Tieni la chiave sul tuo server.
Invia la tua chiave API
curl "https://api.parcelabs.com/easyparcel/account" \
-H "X-API-Key: $API_KEY"Versioni
La versione si sceglie con un header della richiesta, mai con il percorso.
- Invia l'header facoltativo
ParceLabs-Version: 2026-10-23. Il valore è una data. Senza header ottieni la versione supportata più vecchia, oggi2026-10-23. Una richiesta non passa mai da sola a una versione più recente. - Ogni risposta, errori compresi, riporta la versione risolta nell'header
ParceLabs-Version. - Una data sconosciuta riceve
400 UNSUPPORTED_VERSION, una ritirata410 VERSION_RETIRED; idetailsdell'errore elencano le versioni supportate. - Una versione in dismissione risponde normalmente e aggiunge gli header
DeprecationeSunset. - Una nuova versione nasce solo per una modifica che rompe la compatibilità. Nuovi campi, nuovi parametri facoltativi, nuove operazioni e nuovi valori in una risposta non la richiedono mai: ignora le chiavi che non conosci e accetta nuovi valori negli enum.
- Una versione vecchia resta disponibile per almeno 12 mesi dopo l'uscita di una più recente.
Lingua
Due scelte indipendenti, entrambe per ogni richiesta:
| Cosa | Header | Predefinito |
|---|---|---|
| Lingua delle chiavi JSON della risposta | ParceLabs-Key-Locale: en oppure it | en |
Lingua dei messaggi leggibili (error.message, descrizioni) | Accept-Language: en oppure it | en |
Ogni chiave del corpo di una richiesta e ogni parametro di query ha anche un alias italiano, mostrato accanto al nome inglese nel riferimento. Gli alias sono sempre accettati, qualunque sia il valore di ParceLabs-Key-Locale; se sono presenti sia la chiave inglese sia il suo alias, vince quella inglese. La modalità italiana rinomina solo le chiavi: i valori degli enum (DOMESTIC), currency, i codici di errore e i nomi degli header restano in inglese, come le chiavi della busta (error, data, meta, total, page, per_page) e i payload dei webhook.
Convenzioni
| Tema | Regola |
|---|---|
| Formato | JSON, UTF-8, chiavi snake_case. Un singolo elemento è restituito alla radice, senza involucro. |
| Elenchi | { "data": [], "meta": { "total", "page", "per_page" } }, dal più recente. Si pagina con page (da 1) e per_page (predefinito 15, al massimo 100). |
| Filtri | Parametri di query con il nome del campo. Più valori sono separati da virgole (status=IN_STORAGE,REQUESTED). Gli intervalli di date usano *_from e *_to, estremi inclusi, YYYY-MM-DD. |
| Null | Una chiave senza valore è presente con null. Le chiavi sconosciute in una richiesta sono respinte con VALIDATION_ERROR. |
| Timestamp | ISO 8601 con offset, in UTC. Le date sono YYYY-MM-DD; gli orari di ritiro sono HH:MM in Europe/Rome. |
| Importi | Risposte: { "amount": "6.90", "currency": "EUR" }, con l'importo come stringa decimale a due decimali. Richieste: un numero JSON. Solo EUR. |
| Enum | Parole UPPER_SNAKE (DOMESTIC, OUT_FOR_DELIVERY). |
| Paesi | ISO 3166-1 alpha-2, maiuscolo. |
| Identificativi | Stringhe opache: non interpretarle mai. |
| Nomi ed email | Rifilati e normalizzati prima del salvataggio. Le email sono in minuscolo. |
Lo status HTTP è l'unica fonte di verità: 2xx riuscito, 4xx è colpa della richiesta (non riprovare uguale), 5xx e 429 si possono riprovare. Una risorsa di un altro cliente risponde 404, mai 403. Gli errori sono descritti nella pagina Errori.
Idempotenza e correlazione
- Idempotenza. Le scritture che spendono denaro o creano record portano un header
Idempotency-Key(va bene un UUID, al massimo 255 caratteri). È obbligatorio suPOST /shipments,POST /customers,POST /credit-transferse sullo svincolo di una giacenza; facoltativo suPOST /quotations,POST /refund-requestsePOST /proofs-of-delivery. Un nuovo tentativo con la stessa chiave e lo stesso corpo restituisce la prima risposta conIdempotent-Replayed: true, per 24 ore. La stessa chiave con un corpo diverso dà422 IDEMPOTENCY_KEY_REUSED; una chiamata ancora in corso dà409 IDEMPOTENCY_KEY_IN_USE. - Correlazione. Invia
X-Correlation-Id(al massimo 64 caratteri,A-Za-z0-9._-) per seguire una chiamata tra sistemi. Se lo ometti viene generato, ed è riportato in ogni risposta. Indicalo al supporto per un errore5xx.
Limiti di richieste
Le quotazioni hanno un limite giornaliero per chiave, e ogni endpoint un limite di raffica. Quando uno è superato la risposta è 429 con DAILY_LIMIT_EXCEEDED o RATE_LIMIT_EXCEEDED, un header Retry-After e i campi RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Attendi Retry-After prima di riprovare.
Operazioni
Tutte le operazioni del riferimento pubblico, con il loro stato. Le funzioni riservate ai clienti abilitati (Order-Direct, Order-Faster, svincolo delle giacenze e richieste di storno) hanno pagine dedicate nel menu.
GET /accountGet account and key informationIn arrivoPOST /quotationsCreate a quotationIn arrivoGET /quotations/{quotation_id}Get a quotationIn arrivoPOST /coupon-checksCheck a discount couponIn arrivoPOST /shipmentsCreate a shipmentIn arrivoGET /shipmentsList shipmentsIn arrivoGET /shipments/{shipment_id}Get a shipmentIn arrivoGET /shipments/{shipment_id}/waybillGet the waybill of a shipmentIn arrivoGET /tracking/{tracking_number}Get tracking by waybillIn arrivoGET /tracking/lookupFind tracking by waybill, reference or offer codeIn arrivoGET /trackingTrack several shipmentsIn arrivoGET /shipments/{shipment_id}/trackingGet tracking of a shipmentIn arrivoGET /service-pointsSearch service points (PUDO)In arrivoGET /tariff-codesSearch TARIC codes by descriptionIn arrivoPOST /customersCreate a customer in your networkIn arrivoPOST /customers/{customer_id}/invitationsSend a customer invitation againIn arrivoGET /balanceGet your prepaid balanceIn arrivoGET /customers/{customer_id}/balanceGet the balance of a customerIn arrivoPOST /credit-transfersMove credit to a customerIn arrivoWEBHOOK shipment.waybill_readyWaybill readyIn arrivo