La tua prima spedizione
Quattro chiamate portano una spedizione dal prezzo alla consegna: quotazione, ordine, lettera di vettura e tracking.
Le operazioni usate qui sono contrassegnate in arrivo. Il flusso e le forme sono il contratto pubblicato; possono ancora cambiare finché le operazioni non sono rilasciate.
1. Ottieni le offerte
Descrivi la spedizione e chiedi una quotazione. Ricevi una offerta per ogni corriere disponibile per te, dal prezzo migliore. Ogni offerta ha un offer_code che puoi ordinare una sola volta.
Crea una quotazione
curl -X POST "https://api.parcelabs.com/easyparcel/quotations" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"content_description": "Biscotti",
"packages": [{ "quantity": 1, "total_weight_kg": 3, "length_cm": 20, "width_cm": 30, "height_cm": 15 }],
"sender": { "postal_code": "00175", "city": "ROMA", "province": "RM", "country_code": "IT" },
"recipient": { "postal_code": "20121", "city": "MILANO", "province": "MI", "country_code": "IT" }
}'I servizi opzionali (contrassegno, assicurazione, ritiro) compaiono in ogni offerta con costo e limiti. Un coupon si può verificare prima con POST /coupon-checks.
2. Acquista la spedizione
Ordina l'offerta scelta e aggiungi i dati completi di mittente e destinatario. L'Idempotency-Key rende la chiamata sicura da ripetere: dopo un timeout invia di nuovo la stessa chiave e lo stesso corpo e ottieni la prima risposta, non un secondo acquisto.
Crea una spedizione da un'offerta
curl -X POST "https://api.parcelabs.com/easyparcel/shipments" \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: 6f1c1f0e-0000-4000-8000-000000000001" \
-H "Content-Type: application/json" \
-d '{
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"sender": { "name": "Test Sender", "address": "Via Esempio 1", "postal_code": "00175", "city": "Roma", "province": "RM", "country_code": "IT", "email": "sender@example.com", "mobile": "0000000001" },
"recipient": { "name": "Test Recipient", "address": "Via Esempio 2", "postal_code": "20121", "city": "Milano", "province": "MI", "country_code": "IT", "email": "recipient@example.com", "mobile": "0000000002" }
}'Il prezzo è addebitato sul tuo credito prepagato. Qui un ordine e la sua spedizione sono la stessa cosa: c'è una sola risorsa, shipments, e un solo id. Se conosci già il corriere puoi saltare il passo 1 e inviare carrier_code al posto di offer_code: quotazione, ordine e lettera di vettura avvengono in una sola chiamata.
3. Ottieni la lettera di vettura
La lettera di vettura (LDV, il documento di trasporto con l'etichetta) è generata in modo asincrono. Se la spedizione risponde waybill_status: PENDING esiste comunque: leggi la LDV più tardi, oppure attendi il webhook shipment.waybill_ready (vedi Webhook).
Leggi la lettera di vettura
curl "https://api.parcelabs.com/easyparcel/shipments/1234567/waybill" \
-H "X-API-Key: $API_KEY"La risposta contiene il waybill_number, l'etichetta e, quando c'è, un link firmato al borderò di ritiro (manifest_url).
4. Segui la spedizione
Leggi il tracking di una spedizione, cerca più LDV insieme oppure elenca il tracking delle spedizioni recenti. Vedi solo spedizioni tue o della tua rete: tutto il resto è NOT_FOUND.
Traccia una spedizione
curl "https://api.parcelabs.com/easyparcel/tracking/EX0000000001" \
-H "X-API-Key: $API_KEY"Invece di interrogare di continuo puoi ricevere ogni cambiamento sul tuo endpoint con il webhook tracking.updated dei clienti Order-Direct. I codici di stato del corriere che trovi in tracking_events sono elencati in Codici di stato del corriere.