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.

POST/shipments

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 marked order-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 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_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.Shipment
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

POST
/shipments
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"
}
GET/shipments

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.ShipmentList
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

GET
/shipments
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/shipments/{shipment_id}

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.Shipment
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

GET
/shipments/{shipment_id}
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/shipments/{shipment_id}/waybill

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.Waybill
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated 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.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

GET
/shipments/{shipment_id}/waybill
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-Key to 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. On recipient: deliver there. On sender: 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. EXTRA can 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: A4 PDF, 1011 PDF 10x11 cm, ZPL thermal 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. Default false; fetch it later with GET /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_reference as 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-Key to 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: see POST /refund-requests.

    Valori ammessi: ANOMALY, PROCESSING, PROCESSED, ARCHIVED, REFUND_REQUESTED, CANCELLED.

  • Name
    livemode
    Type
    boolean
    obbligatorio
    Alias italiano: live
    Description

    false for 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 the shipment.waybill_ready webhook. 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.inline was 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 status is FAILED.

  • 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

  • Name
    data
    Type
    array of Shipment
    obbligatorio
    Description
  • Name
    meta
    Type
    PageMeta
    obbligatorio
    Description

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.

Was this page helpful?