Spedizioni

Preventivo spedizioni

L’endpoint POST /api/v1/integrations/shipments/quote calcola i preventivi di tutti i corrieri disponibili per una spedizione, ordinati per totalPriceWithVat crescente. Usa lo stesso motore tariffario dell’app E-Manager (get_best_carriers_v5).

Tracking spedizioni

Due endpoint separati consentono di consultare il tracking strutturato delle spedizioni della company. Entrambi richiedono lo scope shipments:tracking.

Per numero tracking

GET /api/v1/integrations/shipments/tracking/by-tracking-number/{trackingNumber} Restituisce un oggetto singolo con metadati spedizione, ordine, corriere, destinatario (senza email/telefono), timeline eventi e spedizioni correlate opzionali. La ricerca accetta:

numero tracking principale (con normalizzazione spazi/punto e prefisso MUL)
tracking su etichette secondarie
identificativi alternativi: reference, parcelId, marketplaceOrderId, marketplaceOrderNumber

Per numero ordine marketplace

GET /api/v1/integrations/shipments/tracking/by-order-number/{orderNumber} Il parametro orderNumber corrisponde a orders.marketplace_order_number (non al numero ordine interno E-Manager). Match esatto sul valore indicato. Restituisce un array di oggetti tracking per tutte le spedizioni collegate agli ordini corrispondenti. HTTP 404 se non esistono ordini o spedizioni per la company dell’API key.

Esempio risposta tracking

{
  "trackingNumber": "CK662764245",
  "status": "In transito",
  "shipmentDate": "2024-06-10T08:00:00.000Z",
  "expectedDeliveryDate": "2024-06-17T18:00:00.000Z",
  "deliveredDate": null,
  "parcelNumber": 1,
  "weight": "2.50",
  "volume": "12000.00",
  "trackingUrl": "https://gls-group.com/IT/it/servizi-online/ricerca-spedizioni?type=NAT&match=CK662764245",
  "orderNumber": "ORD-2024-001",
  "marketplaceOrderNumber": "MKT-2048-12345",
  "carrier": { "name": "GLS", "logoUrl": "https://cdn.example.com/gls.png" },
  "recipient": {
    "companyName": "Rossi S.r.l.",
    "address": "Via Roma 1",
    "postalCode": "10121",
    "city": "Torino",
    "province": "TO",
    "country": "Italia",
    "countryCode": "IT"
  },
  "timeline": [
    {
      "timestamp": "2024-06-15T14:30:00.000Z",
      "statusCode": "03",
      "label": "In transito",
      "description": "Spedizione in viaggio verso il hub",
      "location": "Milano, MI",
      "note": null
    }
  ],
  "relatedShipments": [
    { "id": 54300, "type": "parent", "trackingNumber": "CK662764200", "carrierName": "GLS", "createdAt": null }
  ]
}

Esempi curl tracking

curl -s "https://service.e-manager.io/api/v1/integrations/shipments/tracking/by-tracking-number/CK662764245" \
  -H "Authorization: Bearer em_YOUR_API_KEY"

curl -s "https://service.e-manager.io/api/v1/integrations/shipments/tracking/by-order-number/MKT-2048-12345" \
  -H "Authorization: Bearer em_YOUR_API_KEY"

Flusso consigliato (preventivo)

Scegli il magazzino

Recupera warehouseId da GET /api/v1/integrations/warehouses (modalità manuale) oppure usa un orderId esistente.

Richiedi il preventivo

Invia POST /api/v1/integrations/shipments/quote con scope shipments:quote.

Scegli il corriere

Dal risultato, usa carrierCompanyId del preventivo scelto per la creazione spedizione (endpoint futuro o flusso ordini).

Modalità di input

Modalità A — da ordine

{ "orderId": 12345 }

E-Manager carica automaticamente indirizzo, magazzino, peso/volume, COD e assicurazione dall’ordine.

Modalità B — manuale

{
  "warehouseId": 10,
  "destinationZip": "20121",
  "destinationCountryCode": "IT",
  "totalWeight": 2.5,
  "totalVolume": 12000,
  "cod": { "active": true, "amount": 50.0 },
  "insurance": { "active": false }
}

In alternativa a totalWeight/totalVolume, puoi inviare un array parcels:

{
  "warehouseId": 10,
  "destinationZip": "20121",
  "destinationCountryCode": "IT",
  "parcels": [
    { "weight": 1.2, "length": 30, "depth": 20, "height": 10 }
  ]
}

orderId e i campi manuali sono mutuamente esclusivi. Non combinarli nella stessa richiesta.

Risposta di successo

HTTP 200 con array diretto (senza wrapper items):

[
  {
    "carrierCompanyId": 6,
    "carrierName": "BRT",
    "carrierCode": "BRT",
    "totalPriceWithVat": "31.51",
    "basePrice": "19.50",
    "zoneLabel": "76 - 100",
    "zoneName": "ITALIA"
  },
  {
    "carrierCompanyId": 5,
    "carrierName": "GLS",
    "carrierCode": "GLS",
    "totalPriceWithVat": "45.86"
  }
]

Ogni elemento include il breakdown completo: pesi (chargeableWeight, realWeight, volumetricWeight), componenti prezzo, opzioni corriere (carrierOptionsDetail con price, calculated, description) e totali (totalPrice, vatAmount, totalPriceWithVat, codPrice, insurancePrice).

Risposta warning

Se nessun corriere è applicabile, HTTP 200 restituisce un oggetto singolo (non un array vuoto):

{
  "warning": true,
  "code": "NO_WAREHOUSE_CARRIER",
  "message": "Nessun corriere collegato al magazzino selezionato.",
  "details": [
    "Collega almeno un corriere attivo al magazzino di partenza."
  ]
}

Codici warning

Codice	Significato
`NO_WAREHOUSE_CARRIER`	Nessun corriere collegato al magazzino di partenza.
`NO_RATE_LIST_CONFIGURED`	Corrieri collegati ma listini non configurati.
`NO_DESTINATION_RATE`	Nessuna zona tariffaria per CAP/paese destinazione.
`NO_WEIGHT_RANGE`	Peso fuori dalle fasce configurate nei listini.
`NO_APPLICABLE_CARRIER`	Nessun corriere copre la combinazione richiesta (diagnostica in `details`).

Esempi curl

Manuale

curl -s -X POST "https://service.e-manager.io/api/v1/integrations/shipments/quote" \
  -H "Authorization: Bearer em_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouseId": 10,
    "destinationZip": "20121",
    "destinationCountryCode": "IT",
    "totalWeight": 2.5,
    "totalVolume": 12000
  }'

Da ordine

curl -s -X POST "https://service.e-manager.io/api/v1/integrations/shipments/quote" \
  -H "Authorization: Bearer em_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": 12345 }'

Campi esclusi dalla risposta pubblica

Per motivi di sicurezza e semplicità, l’API non espone: carrier_id, logo_url, is_active, is_connected, delete_flag, purchase, metadati interni delle opzioni (name, option_id, is_custom) né link UI (action).

Riferimento OpenAPI

Vedi lo schema OpenAPI del preventivo per i tipi completi IntegrationsShipmentQuoteItemDto e IntegrationsShipmentQuoteWarningDto. Per il tracking, consulta Tracking per numero spedizione e Tracking per numero ordine marketplace per lo schema IntegrationsShipmentTrackingResponseDto.

Introduzione

Health

Marketplaces

Carriers

Indirizzi

Depositi

Webhook

Spedizioni

Preventivo spedizioni

Tracking spedizioni

Per numero tracking

Per numero ordine marketplace

Esempio risposta tracking

Esempi curl tracking

Flusso consigliato (preventivo)

Modalità di input

Modalità A — da ordine

Modalità B — manuale

Risposta di successo

Risposta warning

Codici warning

Esempi curl

Manuale

Da ordine

Campi esclusi dalla risposta pubblica

Riferimento OpenAPI

​Preventivo spedizioni

​Tracking spedizioni

​Per numero tracking

​Per numero ordine marketplace

​Esempio risposta tracking

​Esempi curl tracking

​Flusso consigliato (preventivo)

​Modalità di input

​Modalità A — da ordine

​Modalità B — manuale

​Risposta di successo

​Risposta warning

​Codici warning

​Esempi curl

​Manuale

​Da ordine

​Campi esclusi dalla risposta pubblica

​Riferimento OpenAPI

Preventivo spedizioni

Tracking spedizioni

Per numero tracking

Per numero ordine marketplace

Esempio risposta tracking

Esempi curl tracking

Flusso consigliato (preventivo)

Modalità di input

Modalità A — da ordine

Modalità B — manuale

Risposta di successo

Risposta warning

Codici warning

Esempi curl

Manuale

Da ordine

Campi esclusi dalla risposta pubblica

Riferimento OpenAPI