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.

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/easyparcel

Contratto 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, oggi 2026-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 ritirata 410 VERSION_RETIRED; i details dell'errore elencano le versioni supportate.
  • Una versione in dismissione risponde normalmente e aggiunge gli header Deprecation e Sunset.
  • 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:

CosaHeaderPredefinito
Lingua delle chiavi JSON della rispostaParceLabs-Key-Locale: en oppure iten
Lingua dei messaggi leggibili (error.message, descrizioni)Accept-Language: en oppure iten

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

TemaRegola
FormatoJSON, 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).
FiltriParametri 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.
NullUna chiave senza valore è presente con null. Le chiavi sconosciute in una richiesta sono respinte con VALIDATION_ERROR.
TimestampISO 8601 con offset, in UTC. Le date sono YYYY-MM-DD; gli orari di ritiro sono HH:MM in Europe/Rome.
ImportiRisposte: { "amount": "6.90", "currency": "EUR" }, con l'importo come stringa decimale a due decimali. Richieste: un numero JSON. Solo EUR.
EnumParole UPPER_SNAKE (DOMESTIC, OUT_FOR_DELIVERY).
PaesiISO 3166-1 alpha-2, maiuscolo.
IdentificativiStringhe opache: non interpretarle mai.
Nomi ed emailRifilati 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 su POST /shipments, POST /customers, POST /credit-transfers e sullo svincolo di una giacenza; facoltativo su POST /quotations, POST /refund-requests e POST /proofs-of-delivery. Un nuovo tentativo con la stessa chiave e lo stesso corpo restituisce la prima risposta con Idempotent-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 errore 5xx.

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.

Was this page helpful?

Was this page helpful?