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↕
brokerageManifestLinesCreate
Encomendas: mercadorias, partes, referências. Máximo de 100 por solicitação
No aceite da encomenda
brokerageManifestCreate
O transporte, indicando os ids de encomenda da chamada 1
Na 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.
Deve 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 EUA
Deve ser enviado para toda encomenda com destino aos EUA. Não é possível registrar uma declaração aduaneira sem ele.
Recomendado
Não é necessário para a cotação, mas é usado pelos correios e pela alfândega de destino. Envie-o sempre que o tiver.
Uma parte ORIGIN e uma parte DESTINATION. Consulte campos das partes.
shippingCost
Obrigatório para a UE
Valor 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.
shippingCostCurrency
Obrigatório para a UE
Moeda de shippingCost. O padrão é USD quando omitido.
taxIdNumber
Opcional
O número IOSS, quando a venda foi feita sob o IOSS. Consulte IOSS.
consignmentWeight
Recomendado
Peso 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.
referenceNumber
Recomendado
Sua referência exclusiva para a encomenda, usada para evitar duplicatas. Consulte encomendas duplicadas.
shipperAccountId
Recomendado
O 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.
postalOperatorCode
Opcional
Substitui o padrão definido no nível da solicitação no caminho curto. Ignorado nos demais casos.
declarationId
Opcional
Uma 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↕
quantity
Obrigatório
Número de unidades.
countryOfOrigin
Obrigatório
Código de país ISO de 2 letras. O país de fabricação, não o de postagem.
amount
Obrigatório
Valor unitário. Envie exatamente um entre amount e totalAmount.
totalAmount
Obrigatório
Valor total de todas as unidades. Quando enviado no lugar de amount, o valor unitário é totalAmount / quantity.
description
Obrigatório
Descrição simples das mercadorias.
measurements
Obrigatório
Inclua uma entrada de peso líquido (WEIGHT por unidade ou TOTAL_WEIGHT para todas as unidades, não ambos). Veja abaixo.
hsCode
Obrigatório para os EUA
Código HS ou tarifário, por linha de mercadorias. 10 dígitos preferencialmente, 6 no mínimo.
customsDescription
Opcional
Descrição específica para a alfândega, quando diferente de description.
provinceOfOrigin
Opcional
Província ou estado de origem, quando um país o exige.
Materiais que compõem o produto. Cada entrada precisa de material e percentage.
marketplace
Opcional
Marketplace 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
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.countryCode
Obrigatório
Obrigatório
location.line1
Obrigatório
Obrigatório
location.locality (cidade)
Obrigatório
Obrigatório
location.postalCode
Recomendado
Obrigatório (exceto Irlanda)
location.administrativeAreaCode
Opcional
Obrigatório para EUA e Canadá
person.firstName
Obrigatório
Obrigatório
person.lastName
Obrigatório
Obrigatório
person.email
Obrigatório para a UE
Obrigatório para a UE
person.companyName
Opcional
Opcional
person.phone
Opcional
Opcional
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.
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.
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
}}
Encomendas fora dos EUA podem dispensar o transporte. Passe o código do operador junto com o array.
1mutationBrokerageManifestLinesCreate(
2$postalOperatorCode: PostalOperatorCode
3$input: [ManifestLineInput!]!
4){
5 brokerageManifestLinesCreate(
6postalOperatorCode:$postalOperatorCode
7input:$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.
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.
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:
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".
API de envios postais
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.
brokerageManifestLinesCreatebrokerageManifestCreateNenhuma chamada bloqueia a outra. Use
manifestLinesLinkpara encomendas aceitas depois que o transporte já existir.Guarde o
idretornado 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
Etapa 1: informe-nos sobre as encomendas
Campos da encomenda
trackingNumbercurrencyCodeendUseDOCUMENTS,GIFT,FOR_RESALE,NOT_FOR_RESALEouRETURN.itemspartiesORIGINe uma parteDESTINATION. Consulte campos das partes.shippingCostshippingCostCurrencyshippingCost. O padrão éUSDquando omitido.taxIdNumberconsignmentWeightreferenceNumbershipperAccountIdpostalOperatorCodedeclarationIdCampos do item
Uma entrada por linha de mercadorias. Uma encomenda com três classificações é uma encomenda com três entradas.
quantitycountryOfOriginamountamountetotalAmount.totalAmountamount, o valor unitário étotalAmount / quantity.descriptionmeasurementsWEIGHTpor unidade ouTOTAL_WEIGHTpara todas as unidades, não ambos). Veja abaixo.hsCodecustomsDescriptiondescription.provinceOfOriginskuproductIdgtinupcgtinquando nenhumgtiné enviado.namedocumentIdproductCompositionmaterialepercentage.marketplacenameeurl.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,unitOfMeasureevalue. 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,HEIGHTouALCOHOL_BY_VOLUMEunitOfMeasure:GRAM,KILOGRAM,OUNCE,POUND,LITER,MILLILITER,CENTIMETER,METER,MILLIMETER,INCH,FOOT,YARDouPERCENTAGEComposição do produto. Cada entrada recebe
materialepercentage, além dos opcionaiscountryOfMeltAndPour,countryOfCast,primaryCountryOfSmeltesecondaryCountryOfSmelt.Campos das partes
Cada parte tem um
type(ORIGINpara o remetente,DESTINATIONpara o destinatário), umpersone umlocation.location.countryCodelocation.line1location.locality(cidade)location.postalCodelocation.administrativeAreaCodeperson.firstNameperson.lastNameperson.emailperson.companyNameperson.phoneAmbas 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.
administrativeAreaCoderecebe o código de duas letras:TX, nãoTEXAS.Exemplo
mutation BrokerageManifestLinesCreate($input: [ManifestLineInput!]!) {brokerageManifestLinesCreate(input: $input) {idtrackingNumberreferenceNumbertaxIdNumber}}RESPOSTA
json
{ "data": { "brokerageManifestLinesCreate": [ { "id": "line_abc123def456", "trackingNumber": "RB123456799GB", "referenceNumber": "ITM-00184413", "taxIdNumber": "IM5281234567" } ] } }Identificadores de produto
Quatro campos em cada linha de mercadorias.
productIdskugtinmanufacturerProductIdO 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.
merchantProductIdentifier(MPID)productId, comskucomo alternativamanufacturerStandardizedProductIdentifier(S PID)gtinmanufacturerNonStandardizedProductIdentifier(NS PID)manufacturerProductIdlccProviderProductIdentifieré definido a partir do nosso id de item.manufacturerIdentifiernão é enviado.Restrições:
gtinaceita somente dígitos.05012345678900, não0-50123-45678-9.gtinouupc, não ambos. Um UPC é um GTIN-12;upcé normalizado emgtin.manufacturerProductIdpermite 70 caracteres. Todos os outros campos de identificador são truncados em 50.Etapa 2: informe-nos sobre o transporte
Enviado na entrega à transportadora, indicando os ids de encomenda da etapa 1.
postalOperatorCodecarrierCodeserviceNumberarrivalDatedestinationCodetransportationModeAIR,SEA,ROADouRAIL. O padrão éAIR.vesselNameoriginCodeawbPrefixawbNumberweightweightUnitweight.amountO conhecimento aéreo é opcional. A chave do transporte é derivada de
carrierCode,serviceNumbere da data.Envie
destinationCodeeoriginCodeno formato que você já usa. A Zonos mantém o mapeamento para as listas de portos da alfândega.mutation BrokerageManifestCreate($input: ManifestInput!, $lineIds: [ID!]!) {brokerageManifestCreate(input: $input, lineIds: $lineIds) {idcarrierCodeserviceNumberdestinationCodearrivalDate}}Um despacho marítimo usa a mesma chamada com
transportationMode: SEA, um SCAC emcarrierCode, o número da viagem emserviceNumber, umvesselNamee 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.
mutation BrokerageManifestLinesCreate($postalOperatorCode: PostalOperatorCode$input: [ManifestLineInput!]!) {brokerageManifestLinesCreate(postalOperatorCode: $postalOperatorCodeinput: $input) {idtrackingNumber}}postalOperatorCodefornece 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
taxIdNumberquando 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.Valores CIF
As tarifas e o IVA da UE são calculados sobre o valor CIF: mercadorias mais frete. Envie
shippingCosteshippingCostCurrencyem 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
DESTINATIONcom 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.
administrativeAreaCoderecebe 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:
Observações gerais
Encomendas duplicadas
referenceNumberdeve 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
amountetotalAmountpor 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.upcsemgtin, o UPC é usado como GTIN."KILOGRAM".Esta página foi útil?