Spedizioni
Una spedizione è ciò che acquisti: da un'offerta quotata, oppure direttamente da un corriere. Un ordine e la sua spedizione sono una sola risorsa con un solo id.
Create a shipment
In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.
Buys a shipment. Two ways, exactly one of offer_code or carrier_code:
- From an offer (
offer_code): orders an offer from a previous quotation. Postal data and packages come from the quotation. - Direct (
carrier_code): quotation, order and waybill in one call (legacy Order-Fast, Order-Faster and Order-Direct). Order-Direct customers use the direct carriers and the services markedorder-direct.
The price is charged to your prepaid credit (nothing is charged with a test key, livemode: false). The waybill is generated asynchronously: if waybill_status is PENDING, the shipment exists anyway; read it later with GET /shipments/{shipment_id}/waybill or wait for the shipment.waybill_ready webhook. Set label.inline to receive the label in the response.
Autenticazione: la tua chiave API nell'header X-API-Key.
Parametri
- Name
Idempotency-Key- Type
- string
- obbligatorio
- Description
Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with
Idempotent-Replayed: true; same key with a different body is 422IDEMPOTENCY_KEY_REUSED; while the first call is running, 409IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400IDEMPOTENCY_KEY_REQUIRED.length ≥ 1, length ≤ 255.
Corpo della richiesta ShipmentFromOffer | ShipmentDirect
Il corpo deve corrispondere a uno dei modelli del suo tipo.
Risposte
201Shipment created.Shipment400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error409State conflict. Codes:OFFER_ALREADY_ORDERED,CUSTOMER_ALREADY_EXISTS(email or tax code already registered),INVITATION_ALREADY_ACCEPTED,IDEMPOTENCY_KEY_IN_USE.Error410Version retired. CodeVERSION_RETIRED.Error422The request is well formed but a business rule refuses it. Codes:INSUFFICIENT_CREDIT,SERVICE_NOT_AVAILABLE,CARRIER_NOT_AVAILABLE,IDEMPOTENCY_KEY_REUSED, ...Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Direct purchase with customs data
{
"carrier_code": "SDAM",
"shipment_type": "EXPORT",
"goods_type": "GOODS",
"content_description": "Various goods",
"client_reference": "CLIENT-REF-0001",
"packages": [
{
"quantity": 1,
"total_weight_kg": 1,
"length_cm": 22,
"width_cm": 20,
"height_cm": 24
}
],
"services": {
"cash_on_delivery": {
"amount": 1000,
"payment_method": "CASH"
},
"insurance": {
"amount": 500
}
},
"sender": {
"name": "Test Sender",
"address": "Via Esempio 1",
"postal_code": "00175",
"city": "Roma",
"province": "RM",
"country_code": "IT",
"email": "sender@example.com",
"mobile": "0000000001",
"contact_name": "Test Sender",
"tax_code": "AAAAAA00A00A000A"
},
"recipient": {
"name": "Test Recipient",
"address": "Via Esempio 2",
"postal_code": "10001",
"city": "New York",
"province": "--",
"country_code": "US",
"email": "recipient@example.com",
"mobile": "0000000002",
"state_code": "NY"
},
"customs": {
"items": [
{
"hs_code": "3004.90.10",
"description": "Generic medicine",
"quantity": 2,
"value": 15,
"weight_kg": 0.1,
"export_reason": "SALE"
}
]
},
"label": {
"format": "A4",
"inline": true
}
}Risposta 201
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"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"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}List shipments
In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.
Lists your shipments, newest first. Without dates it returns today's. Use offer_code, client_reference or waybill_number to find a single shipment (the legacy getorder).
Autenticazione: la tua chiave API nell'header X-API-Key.
Parametri
- Name
created_from- Type
- string (date)
- Description
First day (inclusive),
YYYY-MM-DD. Default: today.
- Name
created_to- Type
- string (date)
- Description
Last day (inclusive),
YYYY-MM-DD. Default: today.
- Name
customer_id- Type
- string
- Description
Only shipments of this customer of your network.
- Name
offer_code- Type
- string
- Description
Find by offer code.
- Name
client_reference- Type
- string
- Description
Find by your reference.
- Name
waybill_number- Type
- string
- Description
Find by waybill.
- Name
status- Type
- array of string
- Description
Filter by status (repeat or comma-separate).
- Name
page- Type
- integer
- Description
Page number, starting at 1.
Predefinito:
1. ≥ 1.
- Name
per_page- Type
- integer
- Description
Items per page, 1 to 100.
Predefinito:
15. ≥ 1, ≤ 100.
Risposte
200A page of shipments.ShipmentList400Malformed or invalid request. Codes:VALIDATION_ERROR(withdetails.errors),INVALID_JSON,IDEMPOTENCY_KEY_REQUIRED,UNSUPPORTED_VERSION.Error401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Risposta 200
{
"data": [
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"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"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}
],
"meta": {
"total": 38,
"page": 1,
"per_page": 15
}
}Get a shipment
In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.
Returns one shipment with sender, recipient, packages, services, price and document links.
Autenticazione: la tua chiave API nell'header X-API-Key.
Parametri
- Name
shipment_id- Type
- string
- obbligatorio
- Description
Shipment id.
Risposte
200The shipment.Shipment401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Risposta 200
{
"id": "1234567",
"status": "PROCESSING",
"livemode": true,
"offer_code": "offer_example_0001",
"client_reference": "REF-0001",
"customer_notes": "Test purchase",
"content_description": "Biscuits",
"customer_id": null,
"carrier": {
"code": "SDAM",
"family": "SDA",
"name": "SDA",
"logo_url": "https://assets.example.com/carriers/sda.png"
},
"delivery_type": "ECONOMY",
"shipment_type": "DOMESTIC",
"goods_type": "GOODS",
"waybill_status": "READY",
"waybill_number": "EX0000000002",
"child_waybill_numbers": [],
"tracking_url": "https://tracking.example.com/EX0000000002",
"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"
},
"packages": [
{
"quantity": 1,
"total_weight_kg": 3,
"length_cm": 20,
"width_cm": 30,
"height_cm": 15
}
],
"services": {
"advanced_tracking": true
},
"pickup": {
"requested": true,
"status": "BOOKED",
"booking_code": "PK0000000001",
"message": null
},
"price": {
"list_price": {
"amount": "10.62",
"currency": "EUR"
},
"total": {
"amount": "6.90",
"currency": "EUR"
},
"vat_rate": 22
},
"documents": {
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000002.pdf",
"expires_at": "2026-12-09T10:35:12+00:00"
},
"created_at": "2026-12-09T09:35:12+00:00"
}Get the waybill of a shipment
In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.
Returns the waybill (LDV) number and links. Add include_content to get the PDF base64 encoded and include_parcels for the single parcel waybills of multi-parcel shipments. The waybill and manifest links are signed and valid for one hour (expires_at), like the links in documents: they are not static file URLs.
Autenticazione: la tua chiave API nell'header X-API-Key.
Parametri
- Name
shipment_id- Type
- string
- obbligatorio
- Description
Shipment id.
- Name
include_content- Type
- boolean
- Description
Return the waybill PDF base64 encoded.
Predefinito:
false.
- Name
include_parcels- Type
- boolean
- Description
Return the single parcel waybills base64 encoded.
Predefinito:
false.
Risposte
200The waybill.Waybill401Missing, invalid or expired API key. Codes:API_KEY_MISSING,API_KEY_INVALID,API_KEY_EXPIRED.Error403Authenticated but not allowed. Codes:FEATURE_NOT_ENABLED(reserved feature not enabled for the customer),IP_NOT_ALLOWED(the key is restricted to other addresses),ACCOUNT_INACTIVE,CUSTOMER_OUT_OF_SCOPE.Error404The resource does not exist or is not visible to the caller. Codes:NOT_FOUNDand resource-specific ones (SHIPMENT_NOT_FOUND,QUOTATION_NOT_FOUND,CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error410Version retired. CodeVERSION_RETIRED.Error429Daily or burst limit exceeded. CodeDAILY_LIMIT_EXCEEDEDorRATE_LIMIT_EXCEEDED. WaitRetry-Afterseconds.Error500Unexpected error. CodeSERVER_ERROR;details.correlation_idrepeats the correlation id.Error502The carrier or an internal dependency failed. CodeUPSTREAM_ERROR. Safe to retry reads; retry writes with the sameIdempotency-Key.Error
Richiesta
Caricamento...
Risposta 200
{
"shipment_id": "1234567",
"client_reference": "REF-0002",
"waybill_number": "EX0000000003",
"waybill_url": "https://files.example.com/waybills/EX0000000003.pdf",
"manifest_url": "https://files.example.com/manifests/EX0000000003.pdf",
"pickup_code": "PK0000000001",
"expires_at": "2026-12-09T10:35:12+00:00"
}Modelli
Oggetti usati dalle richieste e dalle risposte di questa pagina.
ShipmentFromOffer
Buy a quoted offer. Postal data and packages come from the quotation; send the names, street addresses and contacts. Legacy order.
- Name
offer_code- Type
- string
- obbligatorio
- Alias italiano:
codice_offerta - Description
Offer to buy, from a previous
POST /quotations. An offer can be ordered once.
- Name
client_reference- Type
- string
- Alias italiano:
custom - Description
Your own reference for the shipment. Returned in the response and by webhooks; filterable. Not unique: use
Idempotency-Keyto deduplicate.length ≤ 64.
- Name
customer_notes- Type
- string
- Alias italiano:
note_cliente - Description
Note visible to you on the order.
- Name
customer_id- Type
- string
- Alias italiano:
idcustomer - Description
Customer in your network the shipment is bought for.
- Name
coupon_code- Type
- string
- Alias italiano:
coupon - Description
Discount coupon. Check it first with
POST /coupon-checks.
- Name
sender- Type
- Party
- obbligatorio
- Alias italiano:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- obbligatorio
- Alias italiano:
destinatario - Description
Recipient.
- Name
services- Type
- Services
- Alias italiano:
accessori - Description
Services to buy.
- Name
pickup- Type
- Pickup
- Alias italiano:
ritiro - Description
Courier pickup.
- Name
customs- Type
- Customs
- Alias italiano:
dogana - Description
Customs data for international shipments.
- Name
label- Type
- LabelOptions
- Alias italiano:
etichetta - Description
Label options.
Party
Sender or recipient of a shipment.
- Name
name- Type
- string
- obbligatorio
- Alias italiano:
nominativo - Description
Person or company name.
- Name
contact_name- Type
- string
- Alias italiano:
contatto - Description
Contact person, if different from
name.
- Name
address- Type
- string
- obbligatorio
- Alias italiano:
indirizzo - Description
Street and house number.
- Name
postal_code- Type
- string
- obbligatorio
- Alias italiano:
cap - Description
Postal code.
- Name
city- Type
- string
- obbligatorio
- Alias italiano:
localita - Description
City or town.
- Name
province- Type
- string
- Alias italiano:
provincia - Description
Italian province code. Use
--for foreign addresses.
- Name
state_code- Type
- string
- Alias italiano:
codice_stato - Description
State or province code, required for US and CA.
- Name
country_code- Type
- string
- obbligatorio
- Alias italiano:
nazione - Description
ISO 3166-1 alpha-2 country code.
- Name
email- Type
- string (email)
- Alias italiano:
email - Description
Email address. Trimmed and lower-cased by the server.
- Name
phone- Type
- string
- Alias italiano:
telefono - Description
Landline phone number.
- Name
mobile- Type
- string
- Alias italiano:
cellulare - Description
Mobile phone number.
- Name
tax_code- Type
- string
- Alias italiano:
codicefiscale - Description
Tax code or VAT number.
- Name
service_point_code- Type
- string
- Alias italiano:
codice_punto - Description
Code of a service point (PUDO) from
GET /service-points. Onrecipient: deliver there. Onsender: drop-off point, or origin of a reverse shipment.
Services
Optional services. Availability and price depend on the carrier; an unavailable service is refused with SERVICE_NOT_AVAILABLE.
- Name
cash_on_delivery- Type
- object
- Alias italiano:
contrassegno - Description
Cash on delivery. Presence of the object requests the service; omit it to not buy it.
- Name
insurance- Type
- object
- Alias italiano:
assicurazione - Description
Insurance. Presence requests the service.
- Name
floor_delivery- Type
- boolean
- Alias italiano:
consegnaalpiano - Description
Delivery to the floor.
- Name
appointment_delivery- Type
- boolean
- Alias italiano:
consegnasuappuntamento - Description
Delivery by appointment.
- Name
prior_notice- Type
- boolean
- Alias italiano:
priornotice - Description
Prior notice. QUESTION FOR CLAUDIO: the legacy docs disagree (quotation/order: FDA prior notice for the USA only; order-fast: prior phone notice). Keep one meaning.
- Name
advanced_tracking- Type
- boolean
- Alias italiano:
trackingavanzato - Description
Advanced tracking.
- Name
assigned_port- Type
- boolean
- Alias italiano:
porto_assegnato - Description
Assigned port: charges paid by the recipient.
- Name
reverse- Type
- boolean
- Alias italiano:
reso - Description
Reverse shipment (return).
- Name
paperless- Type
- boolean
- Alias italiano:
paperless - Description
No printed label: QR code only. Forces the label format to
A4.
MoneyAmount
Amount in EUR sent in a request, as a JSON number with a dot as decimal separator (never a comma). Up to two decimals.
Pickup
Courier pickup request.
- Name
requested- Type
- boolean
- obbligatorio
- Alias italiano:
prenotazione - Description
Book a courier pickup. Must be requested together with the shipment; it cannot be added later. Not available from service points: send
false.
- Name
location- Type
- string
- Alias italiano:
ritirodove - Description
Where the courier collects.
Valori ammessi:
SENDER,SERVICE_POINT. Predefinito:SENDER.
- Name
address- Type
- Party
- Alias italiano:
indirizzo_ritiro - Description
Pickup address when it differs from
sender.
- Name
available_from- Type
- string (date)
- Alias italiano:
disponibile_dal - Description
Date from which the goods are available.
- Name
available_time- Type
- string
- Alias italiano:
disponibile_ora - Description
Time from which the goods are available (HH:MM, Europe/Rome).
- Name
time_slot- Type
- string
- Alias italiano:
fascia - Description
Coarse slot (order-direct style).
Valori ammessi:
ALL_DAY,MORNING,AFTERNOON.
- Name
morning_from- Type
- string
- Alias italiano:
ritiro_mattina_dalle - Description
Morning window start (HH:MM).
- Name
morning_to- Type
- string
- Alias italiano:
ritiro_mattina_alle - Description
Morning window end (HH:MM).
- Name
afternoon_from- Type
- string
- Alias italiano:
ritiro_pomeriggio_dalle - Description
Afternoon window start (HH:MM).
- Name
afternoon_to- Type
- string
- Alias italiano:
ritiro_pomeriggio_alle - Description
Afternoon window end (HH:MM).
- Name
notes- Type
- string
- Alias italiano:
note - Description
Notes for the courier.
Customs
Customs data for international shipments.
- Name
items- Type
- array of CustomsItem
- Alias italiano:
hscodes - Description
Goods declared. Required for destinations with customs (non-EU).
- Name
documents- Type
- array of CustomsDocument
- Alias italiano:
documenti - Description
Customs documents.
CustomsItem
- Name
hs_code- Type
- string
- obbligatorio
- Alias italiano:
hscode - Description
HS or TARIC code, 6 to 10 digits, dots allowed. The first 6 digits are validated against the WCO database. Find one with
GET /tariff-codes.
- Name
description- Type
- string
- obbligatorio
- Alias italiano:
descrizione - Description
Description of the goods.
- Name
quantity- Type
- integer
- obbligatorio
- Alias italiano:
quantita - Description
Number of items.
≥ 1.
- Name
value- Type
- MoneyAmount
- obbligatorio
- Alias italiano:
importo - Description
Value of the goods in EUR (line total).
- Name
weight_kg- Type
- number
- obbligatorio
- Alias italiano:
peso - Description
Weight of the goods in kg.
> 0.
- Name
export_reason- Type
- string
- obbligatorio
- Alias italiano:
motivo_esportazione - Description
Reason for export.
Valori ammessi:
SALE,GIFT,SAMPLE,RETURN,REPAIR,PERSONAL_EFFECTS.
CustomsDocument
- Name
type- Type
- string
- obbligatorio
- Alias italiano:
tipo_documento - Description
Document type.
EXTRAcan be repeated. For UPS and DHL the documents are attached to the shipment automatically (paperless).Valori ammessi:
EXPORT_DECLARATION,PROFORMA_INVOICE,COMMERCIAL_INVOICE,EXTRA.
- Name
file_name- Type
- string
- Alias italiano:
nome_file - Description
File name (useful for
EXTRA).
- Name
content_base64- Type
- string
- obbligatorio
- Alias italiano:
contenuto_base64 - Description
PDF content, base64 encoded, max 15 MB.
LabelOptions
How to produce the label.
- Name
format- Type
- string
- Alias italiano:
formato - Description
Label format:
A4PDF,1011PDF 10x11 cm,ZPLthermal printers.Valori ammessi:
A4,1011,ZPL. Predefinito:A4.
- Name
inline- Type
- boolean
- Alias italiano:
incluso - Description
Return the label content in the response as
label.content_base64. Defaultfalse; fetch it later withGET /shipments/{shipment_id}/waybill.Predefinito:
false.
- Name
printed_note- Type
- string
- Alias italiano:
nota_stampata - Description
Note printed on the label, upper-cased by the server.
length ≤ 20.
- Name
print_reference_barcode- Type
- boolean
- Alias italiano:
barcode_riferimento - Description
Print
client_referenceas a barcode on the label.
ShipmentDirect
Buy directly from a carrier without a prior quotation. Legacy order-fast, order-faster and order-direct. Order-Direct customers use direct carriers (for example PDB-P2H) and the services marked order-direct.
- Name
carrier_code- Type
- string
- obbligatorio
- Alias italiano:
vettore - Description
Carrier service code. Quotation, order and waybill happen in one call.
- Name
shipment_type- Type
- string
- obbligatorio
- Alias italiano:
tipo_spedizione - Description
Shipment direction.
Valori ammessi:
DOMESTIC,EXPORT,IMPORT.
- Name
goods_type- Type
- string
- obbligatorio
- Alias italiano:
cosa_spedire - Description
What is shipped.
Valori ammessi:
GOODS,DOCUMENTS,PALLETS.
- Name
content_description- Type
- string
- obbligatorio
- Alias italiano:
contenuto - Description
Description of the contents.
- Name
packages- Type
- array of Package
- obbligatorio
- Alias italiano:
colli - Description
Packages.
items ≥ 1.
- Name
client_reference- Type
- string
- Alias italiano:
custom - Description
Your own reference for the shipment. Returned in the response and by webhooks; filterable. Not unique: use
Idempotency-Keyto deduplicate.length ≤ 64.
- Name
customer_notes- Type
- string
- Alias italiano:
note_cliente - Description
Note visible to you on the order.
- Name
customer_id- Type
- string
- Alias italiano:
idcustomer - Description
Customer in your network the shipment is bought for.
- Name
coupon_code- Type
- string
- Alias italiano:
coupon - Description
Discount coupon. Check it first with
POST /coupon-checks.
- Name
sender- Type
- Party
- obbligatorio
- Alias italiano:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- obbligatorio
- Alias italiano:
destinatario - Description
Recipient.
- Name
services- Type
- Services
- Alias italiano:
accessori - Description
Services to buy.
- Name
pickup- Type
- Pickup
- Alias italiano:
ritiro - Description
Courier pickup.
- Name
customs- Type
- Customs
- Alias italiano:
dogana - Description
Customs data for international shipments.
- Name
label- Type
- LabelOptions
- Alias italiano:
etichetta - Description
Label options.
Package
A line of identical packages. For packages with different sizes or weights send several lines.
- Name
quantity- Type
- integer
- Alias italiano:
nr_colli - Description
Number of identical packages in this line.
Predefinito:
1. ≥ 1.
- Name
total_weight_kg- Type
- number
- obbligatorio
- Alias italiano:
peso - Description
TOTAL weight in kg of all packages in this line (not per package). Example: 3 packages of 5 kg each is
15.> 0.
- Name
length_cm- Type
- integer
- obbligatorio
- Alias italiano:
profondita - Description
Length of one package in cm (legacy
profondita/depth).≥ 1.
- Name
width_cm- Type
- integer
- obbligatorio
- Alias italiano:
larghezza - Description
Width of one package in cm.
≥ 1.
- Name
height_cm- Type
- integer
- obbligatorio
- Alias italiano:
altezza - Description
Height of one package in cm.
≥ 1.
ParceLabsVersion
CorrelationId
KeyLocale
Location
Postal location used to price a shipment.
- Name
postal_code- Type
- string
- obbligatorio
- Alias italiano:
cap - Description
Postal code.
- Name
city- Type
- string
- obbligatorio
- Alias italiano:
localita - Description
City or town.
- Name
province- Type
- string
- Alias italiano:
provincia - Description
Italian province code. Use
--for foreign addresses.
- Name
state_code- Type
- string
- Alias italiano:
codice_stato - Description
State or province code. Required for US and CA destinations, otherwise omit.
- Name
country_code- Type
- string
- obbligatorio
- Alias italiano:
nazione - Description
ISO 3166-1 alpha-2 country code.
IdempotentReplayed
Shipment
- Name
id- Type
- string
- obbligatorio
- Alias italiano:
id_ordine - Description
Shipment identifier (opaque string, currently the order id).
- Name
status- Type
- string
- obbligatorio
- Alias italiano:
stato - Description
Order status.
PROCESSING: paid, to be processed.ANOMALY: entered with anomalies.REFUND_REQUESTED: seePOST /refund-requests.Valori ammessi:
ANOMALY,PROCESSING,PROCESSED,ARCHIVED,REFUND_REQUESTED,CANCELLED.
- Name
livemode- Type
- boolean
- obbligatorio
- Alias italiano:
live - Description
falsefor a test key: nothing was charged.
- Name
offer_code- Type
- string · nullable
- Alias italiano:
codice_offerta - Description
Offer the shipment was bought from.
- Name
client_reference- Type
- string · nullable
- Alias italiano:
custom - Description
Your reference.
- Name
customer_notes- Type
- string · nullable
- Alias italiano:
note_cliente - Description
Order note.
- Name
content_description- Type
- string · nullable
- Alias italiano:
contenuto - Description
Contents.
- Name
customer_id- Type
- string · nullable
- Alias italiano:
idcustomer - Description
Customer in your network.
- Name
carrier- Type
- Carrier
- obbligatorio
- Alias italiano:
corriere - Description
Carrier.
- Name
delivery_type- Type
- string · nullable
- Alias italiano:
consegna - Description
Service level.
Valori ammessi:
ECONOMY,EXPRESS,null.
- Name
shipment_type- Type
- string
- Alias italiano:
tipo_spedizione - Description
Direction.
Valori ammessi:
DOMESTIC,EXPORT,IMPORT.
- Name
goods_type- Type
- string
- Alias italiano:
cosa_spedire - Description
Goods type.
Valori ammessi:
GOODS,DOCUMENTS,PALLETS.
- Name
waybill_status- Type
- string
- obbligatorio
- Alias italiano:
stato_ldv - Description
The waybill is generated asynchronously.
PENDING: retry later or wait for theshipment.waybill_readywebhook. The shipment exists anyway.Valori ammessi:
PENDING,READY.
- Name
waybill_number- Type
- string · nullable
- Alias italiano:
lettera_vettura - Description
Carrier waybill (LDV) number, null while
PENDING.
- Name
child_waybill_numbers- Type
- array of string
- Alias italiano:
ldv_figlie - Description
Waybills of the single parcels of a multi-parcel shipment.
- Name
tracking_url- Type
- string (uri) · nullable
- Alias italiano:
url_tracking - Description
Public tracking link.
- Name
sender- Type
- Party
- Alias italiano:
mittente - Description
Sender.
- Name
recipient- Type
- Party
- Alias italiano:
destinatario - Description
Recipient.
- Name
packages- Type
- array of Package
- Alias italiano:
colli - Description
Packages.
- Name
services- Type
- ServicesResult
- Alias italiano:
accessori - Description
Services bought.
- Name
pickup- Type
- PickupResult
- Alias italiano:
ritiro - Description
Pickup outcome.
- Name
price- Type
- object
- Alias italiano:
prezzo - Description
What the shipment cost.
- Name
documents- Type
- object
- Alias italiano:
documenti - Description
Document links.
- Name
label- Type
- LabelResult
- Alias italiano:
etichetta - Description
Label content, present only when
label.inlinewas true.
- Name
created_at- Type
- string (date-time)
- obbligatorio
- Alias italiano:
data - Description
Creation time.
Carrier
- Name
code- Type
- string
- obbligatorio
- Alias italiano:
vettore - Description
Carrier service code, for example
SDAM,PDBT4,INPOST.
- Name
family- Type
- string
- Alias italiano:
famiglia - Description
Carrier family, for example
SDA,PDB.
- Name
name- Type
- string
- Alias italiano:
nome_vettore - Description
Display name.
- Name
logo_url- Type
- string (uri)
- Alias italiano:
logo_vettore - Description
Logo image URL.
ServicesResult
Services bought, as returned in a response: amounts are Money objects.
- Name
cash_on_delivery- Type
- object
- Alias italiano:
contrassegno - Description
Cash on delivery. Presence of the object requests the service; omit it to not buy it.
- Name
insurance- Type
- object
- Alias italiano:
assicurazione - Description
Insurance. Presence requests the service.
- Name
floor_delivery- Type
- boolean
- Alias italiano:
consegnaalpiano - Description
Delivery to the floor.
- Name
appointment_delivery- Type
- boolean
- Alias italiano:
consegnasuappuntamento - Description
Delivery by appointment.
- Name
prior_notice- Type
- boolean
- Alias italiano:
priornotice - Description
Prior notice. QUESTION FOR CLAUDIO: the legacy docs disagree (quotation/order: FDA prior notice for the USA only; order-fast: prior phone notice). Keep one meaning.
- Name
advanced_tracking- Type
- boolean
- Alias italiano:
trackingavanzato - Description
Advanced tracking.
- Name
assigned_port- Type
- boolean
- Alias italiano:
porto_assegnato - Description
Assigned port: charges paid by the recipient.
- Name
reverse- Type
- boolean
- Alias italiano:
reso - Description
Reverse shipment (return).
- Name
paperless- Type
- boolean
- Alias italiano:
paperless - Description
No printed label: QR code only. Forces the label format to
A4.
Money
An amount of money. Responses always use this object; requests send a plain number (see MoneyAmount).
- Name
amount- Type
- string
- obbligatorio
- Alias italiano:
importo - Description
Decimal amount as a string with exactly two decimals. Never a float.
- Name
currency- Type
- string
- obbligatorio
- Alias italiano:
valuta - Description
ISO 4217 currency. v1 is EUR only.
Valori ammessi:
EUR.
PickupResult
Pickup outcome with the requested window echoed.
- Name
requested- Type
- boolean
- obbligatorio
- Alias italiano:
prenotazione - Description
Whether a pickup was requested.
- Name
status- Type
- string
- obbligatorio
- Alias italiano:
stato - Description
PENDING: requested, booking code not available yet.Valori ammessi:
NOT_REQUESTED,PENDING,BOOKED,FAILED.
- Name
booking_code- Type
- string · nullable
- Alias italiano:
codice_ritiro - Description
Pickup booking code, when booked.
- Name
message- Type
- string · nullable
- Alias italiano:
messaggio - Description
Explanation when
statusisFAILED.
- Name
location- Type
- string
- Alias italiano:
ritirodove - Description
Where the courier collects.
Valori ammessi:
SENDER,SERVICE_POINT. Predefinito:SENDER.
- Name
available_from- Type
- string (date)
- Alias italiano:
disponibile_dal - Description
Date from which the goods are available.
- Name
available_time- Type
- string
- Alias italiano:
disponibile_ora - Description
Time from which the goods are available (HH:MM, Europe/Rome).
- Name
morning_from- Type
- string
- Alias italiano:
ritiro_mattina_dalle - Description
Morning window start (HH:MM).
- Name
morning_to- Type
- string
- Alias italiano:
ritiro_mattina_alle - Description
Morning window end (HH:MM).
- Name
afternoon_from- Type
- string
- Alias italiano:
ritiro_pomeriggio_dalle - Description
Afternoon window start (HH:MM).
- Name
afternoon_to- Type
- string
- Alias italiano:
ritiro_pomeriggio_alle - Description
Afternoon window end (HH:MM).
LabelResult
- Name
format- Type
- string
- obbligatorio
- Alias italiano:
formato - Description
Format of the content.
Valori ammessi:
A4,1011,ZPL.
- Name
content_base64- Type
- string
- obbligatorio
- Alias italiano:
ldv_base64 - Description
Label file, base64 encoded.
BadRequest
Unauthorized
Forbidden
NotFound
Conflict
Gone
Unprocessable
TooManyRequests
ServerError
BadGateway
ShipmentList
PageMeta
Pagination metadata.
- Name
total- Type
- integer
- obbligatorio
- Description
Total number of items matching the filters.
- Name
page- Type
- integer
- obbligatorio
- Description
Current page, starting at 1.
- Name
per_page- Type
- integer
- obbligatorio
- Description
Items per page.
Waybill
- Name
shipment_id- Type
- string
- obbligatorio
- Alias italiano:
id_ordine - Description
Shipment identifier.
- Name
client_reference- Type
- string · nullable
- Alias italiano:
custom - Description
Your reference.
- Name
waybill_number- Type
- string
- obbligatorio
- Alias italiano:
waybill_number - Description
Waybill (LDV) number.
- Name
waybill_url- Type
- string (uri)
- obbligatorio
- Alias italiano:
url_ldv - Description
Signed link to the waybill PDF, valid for one hour.
- Name
manifest_url- Type
- string (uri) · nullable
- Alias italiano:
url_bordero - Description
Signed link to the pickup manifest PDF, valid for one hour.
- Name
expires_at- Type
- string (date-time) · nullable
- Alias italiano:
scade_il - Description
When the links stop working.
- Name
pickup_code- Type
- string · nullable
- Alias italiano:
pickup_code - Description
Pickup booking code.
- Name
content_base64- Type
- string
- Alias italiano:
waybill_base64 - Description
Waybill PDF, base64 encoded. Only with
include_content=true.
- Name
parcel_waybills- Type
- array of object
- Alias italiano:
single_waybills - Description
Single parcel waybills. Only with
include_parcels=true.
- Name
documents- Type
- array of object
- Alias italiano:
documenti - Description
Attached customs documents.