DOCS

Informe a Zonos sobre os seus envios postais

Envie dados de encomendas e de transporte relativos a envios com destino aos Estados Unidos e à União Europeia.

Duas chamadas, iguais para todos os destinos.

Chamada↕Envia↕Quando↕
brokerageManifestLinesCreateEncomendas: mercadorias, partes, referências. Máximo de 100 por pedidoNa aceitação da encomenda
brokerageManifestCreateO transporte, indicando os ids de encomenda da chamada 1Na entrega à transportadora

Nenhuma das chamadas bloqueia a outra. Utilize manifestLinesLink para encomendas aceites depois de o transporte já existir.

Guarde o id devolvido pela chamada 1; é obrigatório para a chamada 2.

O landed cost é calculado de forma assíncrona. Uma resposta de sucesso confirma a receção, não a cotação. Os dados dos itens e das partes são validados durante o cálculo, pelo que deve enviar os campos abaixo mesmo quando a API aceita a sua ausência.

Alguns destinos acrescentam uma sobretaxa PDDP. Consulte Sobretaxas PDDP por destino.

Os destinos fora dos EUA dispõem de uma alternativa com uma única chamada.

Legenda dos campos 

Etiqueta↕Significado↕
ObrigatórioA API rejeita o pedido sem este campo.
Obrigatório para a UETem de ser enviado em todas as encomendas com destino à UE. A API pode aceitar uma encomenda sem ele, mas a cotação pode ficar incorreta ou falhar e o envio não fica em conformidade.
Obrigatório para os EUATem de ser enviado em todas as encomendas com destino aos EUA. Sem ele, não é possível apresentar a declaração aduaneira.
RecomendadoNão é necessário para a cotação, mas é utilizado pelos correios e pelas alfândegas de destino. Envie-o sempre que o tiver.
OpcionalEnvie-o quando for aplicável.

Passo 1: informe-nos sobre as encomendas 

Campos da encomenda

Campo↕Requisito↕Notas↕
trackingNumberObrigatórioNúmero de seguimento do objeto.
currencyCodeObrigatórioMoeda de todos os valores dos itens da encomenda.
endUseObrigatórioDOCUMENTS, GIFT, FOR_RESALE, NOT_FOR_RESALE ou RETURN.
itemsObrigatórioPelo menos um item. Consulte campos do item.
partiesObrigatórioUma parte ORIGIN e uma parte DESTINATION. Consulte campos das partes.
shippingCostObrigatório para a UECusto de envio da encomenda. Os direitos aduaneiros e o IVA da UE são calculados sobre o valor CIF, pelo que um custo de envio em falta é tratado como zero.
shippingCostCurrencyObrigatório para a UEMoeda de shippingCost. Assume USD por predefinição quando omitido.
taxIdNumberOpcionalO número IOSS, quando a venda foi efetuada ao abrigo do IOSS. Consulte IOSS.
consignmentWeightRecomendadoPeso bruto da encomenda em quilogramas. Envie o mesmo valor em todas as linhas que partilham um número de seguimento. Não é utilizado para calcular os direitos aduaneiros.
referenceNumberRecomendadoA sua referência única para a encomenda, utilizada para evitar duplicados. Consulte encomendas duplicadas.
shipperAccountIdRecomendadoO ID da organização Zonos ou o seu ID externo da conta verificada do expedidor. Sem ele, a encomenda é atribuída a si e não ao comerciante que está por trás dela.
postalOperatorCodeOpcionalSubstitui a predefinição ao nível do pedido no caminho curto. Ignorado nos restantes casos.
declarationIdOpcionalUma declaração Zonos já criada para esta encomenda. Normalmente é obtida a partir da ordem de compra.

Campos do item

Uma entrada por linha de mercadorias. Uma encomenda com três classificações é uma encomenda com três entradas.

Campo↕Requisito↕Notas↕
quantityObrigatórioNúmero de unidades.
countryOfOriginObrigatórioCódigo de país ISO de 2 letras. O país de fabrico, não o de expedição postal.
amountObrigatórioValor unitário. Envie exatamente um de amount ou totalAmount.
totalAmountObrigatórioValor total de todas as unidades. Quando enviado em vez de amount, o valor unitário é totalAmount / quantity.
descriptionObrigatórioDescrição simples das mercadorias.
measurementsObrigatórioInclua uma entrada de peso líquido (WEIGHT por unidade ou TOTAL_WEIGHT para todas as unidades, não ambos). Ver abaixo.
hsCodeObrigatório para os EUACódigo SH ou pautal, por linha de mercadorias. Preferencialmente 10 dígitos, no mínimo 6.
customsDescriptionOpcionalDescrição específica para fins aduaneiros, quando difere de description.
provinceOfOriginOpcionalProvíncia ou estado de origem, quando um país o exige.
skuRecomendadoO seu SKU. Consulte identificadores de produto.
productIdRecomendadoO seu identificador de produto.
gtinRecomendadoGlobal Trade Item Number, apenas dígitos.
upcOpcionalUtilizado como gtin quando não é enviado nenhum gtin.
nameOpcionalNome abreviado do produto.
documentIdOpcionalAssocia um documento que já carregou.
productCompositionOpcionalMateriais que compõem o produto. Cada entrada necessita de material e percentage.
marketplaceOpcionalMarketplace onde o item foi vendido, como name e url.

O código SH e o país de origem são indicados por linha de mercadorias. Uma encomenda com mercadorias de classificações diferentes necessita de um código e de uma origem para cada uma. Um único código para uma encomenda mista não pode ser declarado nos Estados Unidos.

Medições. Cada entrada necessita de type, unitOfMeasure e value. O peso é líquido e abrange todas as unidades dessa linha, pelo que não deve multiplicá-lo pela quantidade. É sobre este peso que os direitos aduaneiros são calculados.

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

Composição do produto. Cada entrada recebe material e percentage, bem como os campos opcionais countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt e secondaryCountryOfSmelt.

Campos das partes

Cada parte tem um type (ORIGIN para o expedidor, DESTINATION para o destinatário), um person e um location.

Campo↕Origem (expedidor)↕Destino (destinatário)↕
location.countryCodeObrigatórioObrigatório
location.line1ObrigatórioObrigatório
location.locality (cidade)ObrigatórioObrigatório
location.postalCodeRecomendadoObrigatório (exceto Irlanda)
location.administrativeAreaCodeOpcionalObrigatório para EUA e Canadá
person.firstNameObrigatórioObrigatório
person.lastNameObrigatórioObrigatório
person.emailObrigatório para a UEObrigatório para a UE
person.companyNameOpcionalOpcional
person.phoneOpcionalOpcional

Ambas as partes constam da declaração aduaneira. Partes incompletas são a causa mais comum de falhas no desalfandegamento.

Os códigos postais de origem são recomendados, não obrigatórios: Hong Kong, os Emirados Árabes Unidos e o Catar não os têm. Os códigos postais dos destinatários na UE são obrigatórios, exceto na Irlanda.

administrativeAreaCode recebe o código de duas letras: TX, não TEXAS.

Exemplo

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

RESPOSTA

json

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

Identificadores de produto 

Quatro campos em cada linha de mercadorias.

Enviar no item↕O que é↕
productIdO seu próprio identificador de produto
skuA sua unidade de manutenção de stock
gtinO GTIN canónico
manufacturerProductIdA referência da peça atribuída pelo fabricante

O que a Europa faz com eles

O PDDP da UE contém sete campos de identificador de produto. Três são preenchidos diretamente com o que envia no item, pelo que quanto mais enviar aqui, mais completa fica a declaração.

Campo PDDP↕Preenchido a partir de↕Limite↕
merchantProductIdentifier (MPID)productId, recorrendo a sku em falta50
manufacturerStandardizedProductIdentifier (S PID)gtinapenas dígitos
manufacturerNonStandardizedProductIdentifier (NS PID)manufacturerProductId70

lccProviderProductIdentifier é definido a partir do nosso id de item. manufacturerIdentifier não é enviado.

Restrições:

  • gtin aceita apenas dígitos. 05012345678900, não 0-50123-45678-9.
  • Envie gtin ou upc, não ambos. Um UPC é um GTIN-12; upc é normalizado para gtin.
  • manufacturerProductId permite 70 caracteres. Todos os restantes campos de identificador são truncados aos 50.
  • Omita os campos de que não dispõe. As cadeias de caracteres vazias são rejeitadas. Os sete campos têm um comprimento mínimo de um carácter.

Passo 2: informe-nos sobre o transporte 

Enviado na entrega à transportadora, indicando os ids de encomenda do passo 1.

Campo↕Requisito↕Notas↕
postalOperatorCodeObrigatórioO seu código de operador registado.
carrierCodeObrigatórioCódigo IATA de 2 letras (aéreo) ou SCAC (rodoviário, marítimo).
serviceNumberObrigatórioNúmero do voo, da viagem marítima ou do percurso.
arrivalDateObrigatórioData e hora de chegada no formato ISO 8601.
destinationCodeObrigatórioLocal de chegada do transporte. Código de aeroporto ou de porto.
transportationModeRecomendadoAIR, SEA, ROAD ou RAIL. Assume AIR por predefinição.
vesselNameObrigatório para via marítimaO navio. A alfândega identifica um navio à chegada pelo nome, não pelo código da transportadora.
originCodeRecomendadoLocal de partida do transporte.
awbPrefixOpcionalPrefixo da carta de porte aéreo.
awbNumberOpcionalNúmero da carta de porte aéreo.
weightOpcionalPeso total do transporte.
weightUnitOpcionalUnidade de weight.
amountOpcionalValor total do transporte.

A carta de porte aéreo é opcional. A chave do transporte é derivada de carrierCode, serviceNumber e da data.

Envie destinationCode e originCode no formato que já utiliza. A Zonos mantém o mapeamento para as listas de portos aduaneiros.

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

Uma expedição marítima utiliza a mesma chamada com transportationMode: SEA, um SCAC em carrierCode, o número da viagem em serviceNumber, um vesselName e uma data de chegada com semanas, e não horas, de antecedência.

Encomendas aceites posteriormente

As encomendas aceites depois de o transporte já existir são associadas com manifestLinesLink.

MUTAÇÃO

graphql

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

Um caminho mais curto para a Europa 

As encomendas fora dos EUA podem dispensar o transporte. Passe o código do operador juntamente com o 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 fornece o que, de outro modo, seria indicado pelo transporte. Uma encomenda pode substituir a predefinição ao nível do pedido com o seu próprio valor.

As encomendas para os EUA exigem sempre um transporte: a declaração aduaneira indica a transportadora, o serviço e o porto de chegada.

Notas sobre os dados da UE 

IOSS

Envie o número IOSS em taxIdNumber quando a venda tiver sido efetuada ao abrigo do IOSS.

Formato: IM, um código de Estado-Membro da UE com 3 dígitos e, em seguida, 7 dígitos. Exemplo: IM5281234567.

  • Válido: cotado sem IVA de importação.
  • Mal formatado ou ausente: cotado com IVA de importação. Envie o número de registo ou omita o campo. Não envie números sequenciais nem contagens de linhas.

Valores CIF

Os direitos aduaneiros e o IVA da UE são calculados sobre o valor CIF: mercadorias mais custo de envio. Envie shippingCost e shippingCostCurrency em todas as encomendas para a UE. Se os omitir, o custo de envio é tratado como zero e a cotação fica subestimada.

Parte de destino

É obrigatória uma parte DESTINATION com o código de país do destinatário. É ela que determina as regras aplicáveis.

Notas sobre os dados dos EUA 

Partes completas

Ambas as partes exigem uma morada completa: nome, rua, localidade, código postal, estado e país. administrativeAreaCode recebe o código de estado de duas letras.

Classificação

É obrigatório um código pautal por linha de mercadorias: preferencialmente 10 dígitos, no mínimo 6. Os códigos de seis dígitos são completados e validados. As linhas sem código não podem ser declaradas.

O que tratamos por si

Resolvido pela Zonos a partir da configuração da sua conta e das mercadorias da encomenda:

  • Importador oficial (importer of record)
  • Garantia aduaneira e caução
  • Tipo de declaração e código do declarante
  • Direitos aduaneiros, impostos e taxas
  • Transmissão às alfândegas

Notas gerais 

Encomendas duplicadas

referenceNumber tem de ser único entre as suas encomendas. Reutilizar uma referência devolve o registo existente e move-o para o novo transporte; os respetivos itens e partes não são atualizados. Para corrigir uma encomenda, contacte a Zonos em vez de a reenviar com a mesma referência.

Valores

  • Envie exatamente um de amount ou totalAmount por item. Enviar ambos, ou nenhum, faz falhar a cotação.
  • currencyCode é definido uma vez por encomenda. Todos os valores dos itens da encomenda utilizam essa moeda.
  • Se enviar upc sem gtin, o UPC é utilizado como GTIN.
  • Os valores enum são cadeias de caracteres simples, por exemplo "KILOGRAM".

Esta página foi útil?