DOCS

Informe a Zonos sobre seus envios postais

Envie dados de encomendas e de transporte para 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 solicitaçãoNo aceite da encomenda
brokerageManifestCreateO transporte, indicando os ids de encomenda da chamada 1Na entrega à transportadora

Nenhuma chamada bloqueia a outra. Use manifestLinesLink para encomendas aceitas depois que o transporte já existir.

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

O landed cost é calculado de forma assíncrona. Uma resposta de sucesso confirma o recebimento, não a cotação. Os dados de itens e partes são validados durante o cálculo, portanto envie os campos abaixo mesmo quando a API aceitar a ausência deles.

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

Destinos fora dos EUA têm uma alternativa com uma única chamada.

Legenda dos campos 

Rótulo↕Significado↕
ObrigatórioA API rejeita a solicitação sem ele.
Obrigatório para a UEDeve ser enviado para toda encomenda 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 EUADeve ser enviado para toda encomenda com destino aos EUA. Não é possível registrar uma declaração aduaneira sem ele.
RecomendadoNão é necessário para a cotação, mas é usado pelos correios e pela alfândega de destino. Envie-o sempre que o tiver.
OpcionalEnvie-o quando se aplicar.

Etapa 1: informe-nos sobre as encomendas 

Campos da encomenda

Campo↕Requisito↕Observações↕
trackingNumberObrigatórioNúmero de rastreamento do item.
currencyCodeObrigatórioMoeda de todos os valores de 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 UEValor do frete da encomenda. As tarifas e o IVA da UE são calculados sobre o valor CIF, portanto um custo de frete ausente é tratado como zero.
shippingCostCurrencyObrigatório para a UEMoeda de shippingCost. O padrão é USD quando omitido.
taxIdNumberOpcionalO número IOSS, quando a venda foi feita sob o IOSS. Consulte IOSS.
consignmentWeightRecomendadoPeso bruto da encomenda em quilogramas. Envie o mesmo valor em todas as linhas que compartilham um número de rastreamento. Não é usado para calcular tarifas.
referenceNumberRecomendadoSua referência exclusiva para a encomenda, usada para evitar duplicatas. Consulte encomendas duplicadas.
shipperAccountIdRecomendadoO ID da organização Zonos ou seu ID externo da conta verificada do remetente. Sem ele, a encomenda é atribuída a você, e não ao comerciante por trás dela.
postalOperatorCodeOpcionalSubstitui o padrão definido no nível da solicitação no caminho curto. Ignorado nos demais casos.
declarationIdOpcionalUma declaração Zonos já criada para esta encomenda. Normalmente é obtida a partir do pedido.

Campos do item

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

Campo↕Requisito↕Observações↕
quantityObrigatórioNúmero de unidades.
countryOfOriginObrigatórioCódigo de país ISO de 2 letras. O país de fabricação, não o de postagem.
amountObrigatórioValor unitário. Envie exatamente um entre amount e totalAmount.
totalAmountObrigatórioValor total de todas as unidades. Quando enviado no lugar 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). Veja abaixo.
hsCodeObrigatório para os EUACódigo HS ou tarifário, por linha de mercadorias. 10 dígitos preferencialmente, 6 no mínimo.
customsDescriptionOpcionalDescrição específica para a alfândega, quando diferente de description.
provinceOfOriginOpcionalProvíncia ou estado de origem, quando um país o exige.
skuRecomendadoSeu SKU. Consulte identificadores de produto.
productIdRecomendadoSeu identificador de produto.
gtinRecomendadoGlobal Trade Item Number, somente dígitos.
upcOpcionalUsado como gtin quando nenhum gtin é enviado.
nameOpcionalNome curto do produto.
documentIdOpcionalVincula um documento que você já enviou.
productCompositionOpcionalMateriais que compõem o produto. Cada entrada precisa de material e percentage.
marketplaceOpcionalMarketplace em que o item foi vendido, como name e url.

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

Medidas. Cada entrada precisa de type, unitOfMeasure e value. O peso é líquido e abrange todas as unidades daquela linha, portanto não multiplique pela quantidade. Este é o peso sobre o qual as tarifas são calculadas.

  • 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, além dos opcionais countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt e secondaryCountryOfSmelt.

Campos das partes

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

Campo↕Origem (remetente)↕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 falha no desembaraço.

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. Códigos postais de 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.

Envie no item↕O que é↕
productIdSeu próprio identificador de produto
skuSua unidade de manutenção de estoque
gtinO GTIN canônico
manufacturerProductIdO código de peça do 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 você envia no item, portanto quanto mais você enviar aqui, mais completa fica a declaração.

Campo PDDP↕Preenchido a partir de↕Limite↕
merchantProductIdentifier (MPID)productId, com sku como alternativa50
manufacturerStandardizedProductIdentifier (S PID)gtinsomente dígitos
manufacturerNonStandardizedProductIdentifier (NS PID)manufacturerProductId70

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

Restrições:

  • gtin aceita somente dígitos. 05012345678900, não 0-50123-45678-9.
  • Envie gtin ou upc, não ambos. Um UPC é um GTIN-12; upc é normalizado em gtin.
  • manufacturerProductId permite 70 caracteres. Todos os outros campos de identificador são truncados em 50.
  • Omita os campos que você não tem. Strings vazias são rejeitadas. Todos os sete têm comprimento mínimo de um.

Etapa 2: informe-nos sobre o transporte 

Enviado na entrega à transportadora, indicando os ids de encomenda da etapa 1.

Campo↕Requisito↕Observações↕
postalOperatorCodeObrigatórioSeu código de operador registrado.
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 trajeto.
arrivalDateObrigatórioData e hora de chegada em ISO 8601.
destinationCodeObrigatórioOnde o transporte chega. Código de aeroporto ou porto.
transportationModeRecomendadoAIR, SEA, ROAD ou RAIL. O padrão é AIR.
vesselNameObrigatório para marítimoO navio. A alfândega identifica um navio que chega pelo nome, não pelo código da transportadora.
originCodeRecomendadoDe onde o transporte partiu.
awbPrefixOpcionalPrefixo do conhecimento aéreo.
awbNumberOpcionalNúmero do conhecimento aéreo.
weightOpcionalPeso total do transporte.
weightUnitOpcionalUnidade de weight.
amountOpcionalValor total do transporte.

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

Envie destinationCode e originCode no formato que você já usa. A Zonos mantém o mapeamento para as listas de portos da alfândega.

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

Um despacho marítimo usa a mesma chamada com transportationMode: SEA, um SCAC em carrierCode, o número da viagem em serviceNumber, um vesselName e uma data de chegada a semanas, e não a horas, de distância.

Encomendas aceitas depois

Encomendas aceitas depois que o transporte já existe são vinculadas com manifestLinesLink.

MUTAÇÃO

graphql

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

Um caminho mais curto para a Europa 

Encomendas fora dos EUA podem dispensar o transporte. Passe o código do operador junto 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 o transporte carregaria de outra forma. Uma encomenda pode substituir o padrão definido no nível da solicitação com seu próprio valor.

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

Observações sobre dados da UE 

IOSS

Envie o número IOSS em taxIdNumber quando a venda tiver sido feita sob o IOSS.

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

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

Valores CIF

As tarifas e o IVA da UE são calculados sobre o valor CIF: mercadorias mais frete. Envie shippingCost e shippingCostCurrency em toda encomenda para a UE. Omiti-los faz com que o frete seja tratado como zero e subestima a cotação.

Parte de destino

Uma parte DESTINATION com o código de país do destinatário é obrigatória. Ela determina quais regras se aplicam.

Observações sobre dados dos EUA 

Partes completas

Ambas as partes exigem um endereço completo: nome, rua, localidade, código postal, estado e país. administrativeAreaCode recebe o código de estado de duas letras.

Classificação

Um código tarifário é obrigatório por linha de mercadorias: 10 dígitos preferencialmente, 6 no mínimo. Códigos de seis dígitos são estendidos e validados. Linhas sem código não podem ser registradas.

Do que cuidamos

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

  • Importador registrado
  • Garantia aduaneira e fiança
  • Tipo de declaração e código do despachante
  • Tarifas, impostos e taxas
  • Transmissão à alfândega

Observações gerais 

Encomendas duplicadas

referenceNumber deve ser exclusivo entre suas encomendas. Reutilizar um retorna o registro existente e o move para o novo transporte; seus itens e partes não são atualizados. Para corrigir uma encomenda, entre em contato com a Zonos em vez de reenviá-la com a mesma referência.

Valores

  • Envie exatamente um entre amount e totalAmount por item. Enviar ambos, ou nenhum, faz a cotação falhar.
  • currencyCode é definido uma vez por encomenda. Todos os valores de itens da encomenda o utilizam.
  • Se você enviar upc sem gtin, o UPC é usado como GTIN.
  • Valores de enum são strings simples, por exemplo "KILOGRAM".

Esta página foi útil?