DOCS

Comunica a Zonos le tue spedizioni postali

Invia i dati dei pacchi e dei mezzi di trasporto per le spedizioni dirette negli Stati Uniti e nell'Unione Europea.

Due chiamate, uguali per ogni destinazione.

Chiamata↕Invia↕Quando↕
brokerageManifestLinesCreatePacchi: merci, parti, riferimenti. Massimo 100 per richiestaAll'accettazione del pacco
brokerageManifestCreateIl mezzo di trasporto, con gli id dei pacchi della chiamata 1Alla consegna al vettore

Nessuna delle due chiamate blocca l'altra. Usa manifestLinesLink per i pacchi accettati dopo che il mezzo di trasporto è già stato creato.

Conserva l'id restituito dalla chiamata 1: è necessario per la chiamata 2.

Il landed cost viene calcolato in modo asincrono. Una risposta di successo conferma l'accettazione, non la quotazione. I dati degli articoli e delle parti vengono convalidati durante il calcolo, quindi invia i campi indicati di seguito anche quando l'API ne accetta l'assenza.

Alcune destinazioni applicano un supplemento PDDP. Consulta Supplementi PDDP per destinazione.

Le destinazioni diverse dagli Stati Uniti dispongono di un'alternativa con una sola chiamata.

Legenda dei campi 

Etichetta↕Significato↕
ObbligatorioL'API rifiuta la richiesta se manca.
Obbligatorio per l'UEDeve essere inviato per ogni pacco diretto nell'UE. L'API può accettare un pacco senza di esso, ma la quotazione può risultare errata o non riuscire e la spedizione non è conforme.
Obbligatorio per gli USADeve essere inviato per ogni pacco diretto negli Stati Uniti. Senza di esso non è possibile presentare una dichiarazione doganale.
ConsigliatoNon necessario per la quotazione, ma utilizzato dalle poste e dalle dogane di destinazione. Invialo ogni volta che è disponibile.
FacoltativoInvialo quando applicabile.

Passaggio 1: comunicaci i dati dei pacchi 

Campi del pacco

Campo↕Requisito↕Note↕
trackingNumberObbligatorioNumero di tracciamento dell'articolo.
currencyCodeObbligatorioValuta di tutti i valori degli articoli del pacco.
endUseObbligatorioDOCUMENTS, GIFT, FOR_RESALE, NOT_FOR_RESALE o RETURN.
itemsObbligatorioAlmeno un articolo. Consulta i campi dell'articolo.
partiesObbligatorioUna parte ORIGIN e una parte DESTINATION. Consulta i campi delle parti.
shippingCostObbligatorio per l'UECosto di spedizione del pacco. Dazi e IVA UE sono calcolati sul valore CIF, quindi un costo di spedizione mancante viene considerato pari a zero.
shippingCostCurrencyObbligatorio per l'UEValuta di shippingCost. Se omesso, il valore predefinito è USD.
taxIdNumberFacoltativoIl numero IOSS, quando la vendita è avvenuta in regime IOSS. Consulta IOSS.
consignmentWeightConsigliatoPeso lordo del pacco in chilogrammi. Invia lo stesso valore su ogni riga che condivide un numero di tracciamento. Non viene utilizzato per calcolare i dazi.
referenceNumberConsigliatoIl tuo riferimento univoco per il pacco, utilizzato per evitare duplicati. Consulta Pacchi duplicati.
shipperAccountIdConsigliatoL'ID organizzazione Zonos o il tuo ID esterno per l'account verificato del mittente. Senza di esso il pacco viene attribuito a te anziché al merchant che lo ha spedito.
postalOperatorCodeFacoltativoSostituisce il valore predefinito a livello di richiesta nel percorso breve. Ignorato altrove.
declarationIdFacoltativoUna dichiarazione Zonos già creata per questo pacco. Normalmente viene ricavata dall'ordine.

Campi dell'articolo

Una voce per ogni riga di merci. Un pacco contenente tre classificazioni è un unico pacco con tre voci.

Campo↕Requisito↕Note↕
quantityObbligatorioNumero di unità.
countryOfOriginObbligatorioCodice paese ISO di 2 lettere. Il paese di fabbricazione, non quello di spedizione.
amountObbligatorioValore unitario. Invia esattamente uno tra amount e totalAmount.
totalAmountObbligatorioValore complessivo di tutte le unità. Se inviato al posto di amount, il valore unitario è totalAmount / quantity.
descriptionObbligatorioDescrizione semplice delle merci.
measurementsObbligatorioIncludi una voce di peso netto (WEIGHT per unità o TOTAL_WEIGHT per tutte le unità, non entrambe). Vedi sotto.
hsCodeObbligatorio per gli USACodice HS o tariffario, per riga di merci. Preferibilmente 10 cifre, minimo 6.
customsDescriptionFacoltativoDescrizione specifica per la dogana, quando diversa da description.
provinceOfOriginFacoltativoProvincia o stato di origine, dove richiesto da un paese.
skuConsigliatoIl tuo SKU. Consulta gli identificativi prodotto.
productIdConsigliatoIl tuo identificativo prodotto.
gtinConsigliatoGlobal Trade Item Number, solo cifre.
upcFacoltativoUtilizzato come gtin quando non viene inviato alcun gtin.
nameFacoltativoNome breve del prodotto.
documentIdFacoltativoCollega un documento che hai già caricato.
productCompositionFacoltativoMateriali che compongono il prodotto. Ogni voce richiede material e percentage.
marketplaceFacoltativoMarketplace su cui è stato venduto l'articolo, come name e url.

Il codice HS e il paese di origine sono per riga di merci. Un pacco contenente merci con classificazioni diverse richiede un codice e un'origine per ciascuna. Un unico codice per un pacco misto non può essere dichiarato negli Stati Uniti.

Misure. Ogni voce richiede type, unitOfMeasure e value. Il peso è netto e copre tutte le unità di quella riga, quindi non moltiplicarlo per la quantità. È il peso su cui vengono calcolati i dazi.

  • type: WEIGHT, TOTAL_WEIGHT, VOLUME, LENGTH, WIDTH, HEIGHT o ALCOHOL_BY_VOLUME
  • unitOfMeasure: GRAM, KILOGRAM, OUNCE, POUND, LITER, MILLILITER, CENTIMETER, METER, MILLIMETER, INCH, FOOT, YARD o PERCENTAGE

Composizione del prodotto. Ogni voce accetta material e percentage, più i campi facoltativi countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt e secondaryCountryOfSmelt.

Campi delle parti

Ogni parte ha un type (ORIGIN per il mittente, DESTINATION per il destinatario), una person e una location.

Campo↕Origine (mittente)↕Destinazione (destinatario)↕
location.countryCodeObbligatorioObbligatorio
location.line1ObbligatorioObbligatorio
location.locality (città)ObbligatorioObbligatorio
location.postalCodeConsigliatoObbligatorio (eccetto Irlanda)
location.administrativeAreaCodeFacoltativoObbligatorio per USA e Canada
person.firstNameObbligatorioObbligatorio
person.lastNameObbligatorioObbligatorio
person.emailObbligatorio per l'UEObbligatorio per l'UE
person.companyNameFacoltativoFacoltativo
person.phoneFacoltativoFacoltativo

Entrambe le parti sono indicate nella dichiarazione doganale. Parti incomplete sono la causa più comune di mancato sdoganamento.

I codici postali di origine sono consigliati, non obbligatori: Hong Kong, gli Emirati Arabi Uniti e il Qatar non ne hanno. I codici postali dei destinatari nell'UE sono obbligatori, tranne che in Irlanda.

administrativeAreaCode accetta il codice di due lettere: TX, non TEXAS.

Esempio

1mutation BrokerageManifestLinesCreate($input: [ManifestLineInput!]!) {
2 brokerageManifestLinesCreate(input: $input) {
3 id
4 trackingNumber
5 referenceNumber
6 taxIdNumber
7 }
8}

RISPOSTA

json

{
  "data": {
    "brokerageManifestLinesCreate": [
      {
        "id": "line_abc123def456",
        "trackingNumber": "RB123456799GB",
        "referenceNumber": "ITM-00184413",
        "taxIdNumber": "IM5281234567"
      }
    ]
  }
}

Identificativi prodotto 

Quattro campi su ogni riga di merci.

Da inviare sull'articolo↕Che cos'è↕
productIdIl tuo identificativo prodotto
skuLa tua unità di magazzino (SKU)
gtinIl GTIN canonico
manufacturerProductIdIl codice articolo del produttore

Come li utilizza l'Europa

Il PDDP dell'UE prevede sette campi di identificazione del prodotto. Tre vengono alimentati direttamente da ciò che invii sull'articolo, quindi più dati invii qui, più campi della dichiarazione vengono compilati.

Campo PDDP↕Alimentato da↕Limite↕
merchantProductIdentifier (MPID)productId, in alternativa sku50
manufacturerStandardizedProductIdentifier (S PID)gtinsolo cifre
manufacturerNonStandardizedProductIdentifier (NS PID)manufacturerProductId70

lccProviderProductIdentifier viene impostato a partire dal nostro id articolo. manufacturerIdentifier non viene inviato.

Vincoli:

  • gtin contiene solo cifre. 05012345678900, non 0-50123-45678-9.
  • Invia gtin o upc, non entrambi. Un UPC è un GTIN-12; upc viene normalizzato in gtin.
  • manufacturerProductId consente 70 caratteri. Tutti gli altri campi identificativi vengono troncati a 50.
  • Ometti i campi di cui non disponi. Le stringhe vuote vengono rifiutate. Tutti e sette hanno una lunghezza minima di un carattere.

Passaggio 2: comunicaci i dati del mezzo di trasporto 

Inviati alla consegna al vettore, indicando gli id dei pacchi del passaggio 1.

Campo↕Requisito↕Note↕
postalOperatorCodeObbligatorioIl tuo codice operatore registrato.
carrierCodeObbligatorioCodice IATA di 2 lettere (aereo) o SCAC (camion, nave).
serviceNumberObbligatorioNumero di volo, viaggio o tratta.
arrivalDateObbligatorioData e ora di arrivo in formato ISO 8601.
destinationCodeObbligatorioLuogo di arrivo del mezzo di trasporto. Codice aeroporto o porto.
transportationModeConsigliatoAIR, SEA, ROAD o RAIL. Il valore predefinito è AIR.
vesselNameObbligatorio per il trasporto marittimoLa nave. La dogana identifica una nave in arrivo dal nome, non dal codice vettore.
originCodeConsigliatoLuogo di partenza del mezzo di trasporto.
awbPrefixFacoltativoPrefisso della lettera di vettura aerea.
awbNumberFacoltativoNumero della lettera di vettura aerea.
weightFacoltativoPeso totale del mezzo di trasporto.
weightUnitFacoltativoUnità di misura di weight.
amountFacoltativoValore totale del carico.

La lettera di vettura aerea è facoltativa. La chiave del mezzo di trasporto viene ricavata da carrierCode, serviceNumber e dalla data.

Invia destinationCode e originCode nel formato che utilizzi già. Zonos gestisce la mappatura con gli elenchi dei porti doganali.

1mutation BrokerageManifestCreate($input: ManifestInput!, $lineIds: [ID!]!) {
2 brokerageManifestCreate(input: $input, lineIds: $lineIds) {
3 id
4 carrierCode
5 serviceNumber
6 destinationCode
7 arrivalDate
8 }
9}

Una spedizione via mare utilizza la stessa chiamata con transportationMode: SEA, uno SCAC in carrierCode, il numero di viaggio in serviceNumber, un vesselName e una data di arrivo a settimane anziché a ore di distanza.

Pacchi accettati successivamente

I pacchi accettati dopo la creazione del mezzo di trasporto vengono collegati con manifestLinesLink.

MUTATION

graphql

mutation ManifestLinesLink($manifestId: ID!, $lineIds: [ID!]!) {
  manifestLinesLink(manifestId: $manifestId, lineIds: $lineIds) {
    id
  }
}

Un percorso più breve per l'Europa 

I pacchi non diretti negli Stati Uniti possono saltare il mezzo di trasporto. Passa il codice operatore insieme all'array.

1mutation BrokerageManifestLinesCreate(
2$postalOperatorCode: PostalOperatorCode
3$input: [ManifestLineInput!]!
4) {
5 brokerageManifestLinesCreate(
6 postalOperatorCode: $postalOperatorCode
7 input: $input
8 ) {
9 id
10 trackingNumber
11 }
12}

postalOperatorCode fornisce ciò che altrimenti conterrebbe il mezzo di trasporto. Un pacco può sostituire il valore predefinito a livello di richiesta con un proprio valore.

I pacchi diretti negli Stati Uniti richiedono sempre un mezzo di trasporto: la dichiarazione doganale indica il vettore, il servizio e il porto di arrivo.

Note sui dati per l'UE 

IOSS

Invia il numero IOSS in taxIdNumber quando la vendita è avvenuta in regime IOSS.

Formato: IM, un codice di 3 cifre dello stato membro UE, quindi 7 cifre. Esempio: IM5281234567.

  • Valido: quotato senza IVA all'importazione.
  • Non valido o assente: quotato con IVA all'importazione. Invia il numero di registrazione oppure ometti il campo. Non inviare numeri progressivi o conteggi di righe.

Valori CIF

Dazi e IVA UE sono calcolati sul valore CIF: merci più spedizione. Invia shippingCost e shippingCostCurrency su ogni pacco diretto nell'UE. Se li ometti, la spedizione viene considerata pari a zero e la quotazione risulta sottostimata.

Parte di destinazione

È obbligatoria una parte DESTINATION con il codice paese del destinatario. Determina quali regole si applicano.

Note sui dati per gli USA 

Parti complete

Entrambe le parti richiedono un indirizzo completo: nome, via, località, codice postale, stato, paese. administrativeAreaCode accetta il codice di due lettere dello stato.

Classificazione

È obbligatorio un codice tariffario per ogni riga di merci: preferibilmente 10 cifre, minimo 6. I codici a sei cifre vengono estesi e convalidati. Le righe senza codice non possono essere dichiarate.

Di cosa ci occupiamo noi

Gestiti da Zonos in base alla configurazione del tuo account e alle merci contenute nel pacco:

  • Importatore registrato (importer of record)
  • Garanzia doganale e fideiussione
  • Tipo di dichiarazione e codice del dichiarante
  • Dazi, imposte e diritti
  • Trasmissione alla dogana

Note generali 

Pacchi duplicati

referenceNumber deve essere univoco tra tutti i tuoi pacchi. Riutilizzarne uno restituisce il record esistente e lo sposta sul nuovo mezzo di trasporto; i relativi articoli e parti non vengono aggiornati. Per correggere un pacco, contatta Zonos anziché inviarlo di nuovo con lo stesso riferimento.

Valori

  • Invia esattamente uno tra amount e totalAmount per ogni articolo. Inviarli entrambi, o nessuno dei due, fa fallire la quotazione.
  • currencyCode viene impostato una sola volta per pacco. Tutti i valori degli articoli del pacco lo utilizzano.
  • Se invii upc senza gtin, l'UPC viene utilizzato come GTIN.
  • I valori enum sono stringhe semplici, ad esempio "KILOGRAM".

Questa pagina è stata utile?