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↕
brokerageManifestLinesCreate
Encomendas: mercadorias, partes, referências. Máximo de 100 por pedido
Na aceitação da encomenda
brokerageManifestCreate
O transporte, indicando os ids de encomenda da chamada 1
Na 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.
Tem 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 EUA
Tem de ser enviado em todas as encomendas com destino aos EUA. Sem ele, não é possível apresentar a declaração aduaneira.
Recomendado
Não é necessário para a cotação, mas é utilizado pelos correios e pelas alfândegas 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
Custo 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.
shippingCostCurrency
Obrigatório para a UE
Moeda de shippingCost. Assume USD por predefinição quando omitido.
taxIdNumber
Opcional
O número IOSS, quando a venda foi efetuada ao abrigo do IOSS. Consulte IOSS.
consignmentWeight
Recomendado
Peso 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.
referenceNumber
Recomendado
A sua referência única para a encomenda, utilizada para evitar duplicados. Consulte encomendas duplicadas.
shipperAccountId
Recomendado
O 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.
postalOperatorCode
Opcional
Substitui a predefinição ao nível do pedido no caminho curto. Ignorado nos restantes casos.
declarationId
Opcional
Uma 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↕
quantity
Obrigatório
Número de unidades.
countryOfOrigin
Obrigatório
Código de país ISO de 2 letras. O país de fabrico, não o de expedição postal.
amount
Obrigatório
Valor unitário. Envie exatamente um de amount ou totalAmount.
totalAmount
Obrigatório
Valor total de todas as unidades. Quando enviado em vez 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). Ver abaixo.
hsCode
Obrigatório para os EUA
Código SH ou pautal, por linha de mercadorias. Preferencialmente 10 dígitos, no mínimo 6.
customsDescription
Opcional
Descrição específica para fins aduaneiros, quando difere de description.
provinceOfOrigin
Opcional
Província ou estado de origem, quando um país o exige.
Utilizado como gtin quando não é enviado nenhum gtin.
name
Opcional
Nome abreviado do produto.
documentId
Opcional
Associa um documento que já carregou.
productComposition
Opcional
Materiais que compõem o produto. Cada entrada necessita de material e percentage.
marketplace
Opcional
Marketplace 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
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.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 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.
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.
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
}}
As encomendas fora dos EUA podem dispensar o transporte. Passe o código do operador juntamente 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, 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.
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.
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:
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".
API de envios postais
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.
brokerageManifestLinesCreatebrokerageManifestCreateNenhuma das chamadas bloqueia a outra. Utilize
manifestLinesLinkpara encomendas aceites depois de o transporte já existir.Guarde o
iddevolvido 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
Passo 1: informe-nos sobre as encomendas
Campos da encomenda
trackingNumbercurrencyCodeendUseDOCUMENTS,GIFT,FOR_RESALE,NOT_FOR_RESALEouRETURN.itemspartiesORIGINe uma parteDESTINATION. Consulte campos das partes.shippingCostshippingCostCurrencyshippingCost. AssumeUSDpor predefinição quando omitido.taxIdNumberconsignmentWeightreferenceNumbershipperAccountIdpostalOperatorCodedeclarationIdCampos do item
Uma entrada por linha de mercadorias. Uma encomenda com três classificações é uma encomenda com três entradas.
quantitycountryOfOriginamountamountoutotalAmount.totalAmountamount, o valor unitário étotalAmount / quantity.descriptionmeasurementsWEIGHTpor unidade ouTOTAL_WEIGHTpara todas as unidades, não ambos). Ver abaixo.hsCodecustomsDescriptiondescription.provinceOfOriginskuproductIdgtinupcgtinquando não é enviado nenhumgtin.namedocumentIdproductCompositionmaterialepercentage.marketplacenameeurl.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,unitOfMeasureevalue. 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,HEIGHTouALCOHOL_BY_VOLUMEunitOfMeasure:GRAM,KILOGRAM,OUNCE,POUND,LITER,MILLILITER,CENTIMETER,METER,MILLIMETER,INCH,FOOT,YARDouPERCENTAGEComposição do produto. Cada entrada recebe
materialepercentage, bem como os campos opcionaiscountryOfMeltAndPour,countryOfCast,primaryCountryOfSmeltesecondaryCountryOfSmelt.Campos das partes
Cada parte tem um
type(ORIGINpara o expedidor,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 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.
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 envia no item, pelo que quanto mais enviar aqui, mais completa fica a declaração.
merchantProductIdentifier(MPID)productId, recorrendo askuem faltamanufacturerStandardizedProductIdentifier(S PID)gtinmanufacturerNonStandardizedProductIdentifier(NS PID)manufacturerProductIdlccProviderProductIdentifieré definido a partir do nosso id de item.manufacturerIdentifiernão é enviado.Restrições:
gtinaceita apenas dígitos.05012345678900, não0-50123-45678-9.gtinouupc, não ambos. Um UPC é um GTIN-12;upcé normalizado paragtin.manufacturerProductIdpermite 70 caracteres. Todos os restantes campos de identificador são truncados aos 50.Passo 2: informe-nos sobre o transporte
Enviado na entrega à transportadora, indicando os ids de encomenda do passo 1.
postalOperatorCodecarrierCodeserviceNumberarrivalDatedestinationCodetransportationModeAIR,SEA,ROADouRAIL. AssumeAIRpor predefinição.vesselNameoriginCodeawbPrefixawbNumberweightweightUnitweight.amountA carta de porte aéreo é opcional. A chave do transporte é derivada de
carrierCode,serviceNumbere da data.Envie
destinationCodeeoriginCodeno formato que já utiliza. A Zonos mantém o mapeamento para as listas de portos aduaneiros.mutation BrokerageManifestCreate($input: ManifestInput!, $lineIds: [ID!]!) {brokerageManifestCreate(input: $input, lineIds: $lineIds) {idcarrierCodeserviceNumberdestinationCodearrivalDate}}Uma expedição marítima utiliza a mesma chamada com
transportationMode: SEA, um SCAC emcarrierCode, o número da viagem emserviceNumber, umvesselNamee 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.
mutation BrokerageManifestLinesCreate($postalOperatorCode: PostalOperatorCode$input: [ManifestLineInput!]!) {brokerageManifestLinesCreate(postalOperatorCode: $postalOperatorCodeinput: $input) {idtrackingNumber}}postalOperatorCodefornece 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
taxIdNumberquando 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.Valores CIF
Os direitos aduaneiros e o IVA da UE são calculados sobre o valor CIF: mercadorias mais custo de envio. Envie
shippingCosteshippingCostCurrencyem 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
DESTINATIONcom 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.
administrativeAreaCoderecebe 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:
Notas gerais
Encomendas duplicadas
referenceNumbertem 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
amountoutotalAmountpor 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.upcsemgtin, o UPC é utilizado como GTIN."KILOGRAM".Esta página foi útil?