A API de criação de pedido de envio é uma API RESTful que permite criar um pedido de envio para gerar uma etiqueta de envio e código de rastreamento para um pacote.
POST /v1/shipping-orders
Exemplo de solicitação
{ "orderReferenceId": "EXMPL0001234", "currency": "EUR", "options": { "weightUnit": "g", "dimensionUnit": "mm", "label": { "format": "pdf" } }, "partner": { "clientName": "ExampleCustomer" }, "shippingMethod": { "uid": "", "carrier": "", "tier": "standard" }, "receiver": { "person": { "firstName": "Foo", "lastName": "Bar", "company": "", "email": "[email protected]", "phone": "01273552886" }, "address": { "country": "GB", "state": "East Sussex", "city": "Brighton", "postcode": "BN1 8YQ", "addressLine1": "11 London Rd", "addressLine2": "", "addressLine3": "", "street": "London Rd", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": null } }, "sender": { "person": { "firstName": "", "lastName": "", "company": "Example Company", "email": "[email protected]", "phone": "01666 123456" }, "address": { "country": "DE", "state": "", "city": "Donauwörth", "postcode": "86609", "addressLine1": "Am Wassergraben 11", "addressLine2": null, "addressLine3": null, "street": "Am Wassergraben", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": "DE123456789000", "iossNumber": null, "eoriNumber": "GB987654321000", "pcccNumber": null, "australianBusinessNumber": null } }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "grossWeight": 810, "netWeight": 760, "length": 229, "width": 200, "height": 36, "boxType": "rectangle", "volumetricWeight": 700, "items": [ { "itemReferenceId": "EXMPL0001234-0-1-ITEM1", "description": "Mug", "value": 18.42, "quantity": 4, "weight": 760, "hsCode": "44199090", "countryOfOrigin": "DE" } ] } ]}Exemplo de resposta bem-sucedida
{ "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b", "orderReferenceId": "EXMPL0001234", "shippingMethod": { "carrier": "UPS", "uid": "ups_standard_tariff" }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "trackingNumber": "EXMPL0001234TRCKNUM", "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST", "label": { "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "contentType": "application/pdf" }, "documents": [ { "documentType": "invoice", "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "contentType": "application/pdf" } ], "totalCost": { "value": 2.56, "currency": "EUR" } } ]}Exemplo de resposta de erro
{ "orderReferenceId": "EXMPL0001234", "code": "PUBLIC_API_ERROR", "message": "Processing error", "detail": { "code": "UPS_API_ERROR", "message": { "status": { "title": "Bad Request", "status": 400, "detail": "0 of 1 shipment successfully created.", "statusCode": 400 }, "items": [ { "sstatus": { "title": "Bad Request", "status": 400, "statusCode": 400 }, "validationMessages": [ { "property": "packages[0].items[0].hsCode", "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.", "validationState": "Error" } ] } ] } }, "errors": [ { "code": "IS_BLANK_ERROR", "reference": "receiver.address.country", "message": "This value should not be blank." }, { "code": "IS_BLANK_ERROR", "reference": "receiver.address.city", "message": "This value should not be blank." }, { "code": "MISSING_FIELD_ERROR", "reference": "packages[EXMPL0001234-0-1][length]", "message": "This field is missing." } ]}Request
Parameter | Tipo | Descrição |
orderReferenceId (obrigatório) | string | ID único para pedido de envio. ID fornecido por você. |
moeda (obrigatório) | string | Moeda do pedido de envio no formato de 3 letras. |
opções (opcional) | Opções | Parâmetros opcionais. |
parceiro (opcional) | Parceiro | Detalhes do parceiro. |
método de envio (obrigatório) | Método de Envio | Detalhes do método de envio. |
destinatário (obrigatório) | Destinatário | Detalhes do destinatário. |
remetente (obrigatório) | Remetente | Detalhes do remetente. |
pacotes (obrigatório) | Package[] | Detalhes do pacote. |
Opções
Parameter | Tipo | Descrição |
unidade de peso (opcional) | string | Unidade de peso. Opções disponíveis: g, kg, oz, lb. Por padrão: g. |
unidade de dimensão (opcional) | string | Unidade de comprimento. Opções disponíveis: mm, cm, in. Por padrão: mm. |
rótulo (opcional) | Label | Configurações de formato de etiqueta. |
Label
Parameter | Tipo | Descrição |
formato (opcional) | string | Formato da etiqueta. Opções disponíveis: pdf, zpl (*). Por padrão: pdf. |
Nota: Formatos diferentes de pdf podem não estar habilitados para determinadas transportadoras.
Parceiro
Parameter | Tipo | Descrição |
clientName (opcional) | string | Perfil de cliente para envio. |
Método de Envio
Parameter | Tipo | Descrição |
uid (opcional*) | string | Para ser usado para um método de envio específico, por exemplo amazon_shipping_24. |
transportadora (opcional) | string | Nome da transportadora, ex. Amazon, DHL |
nível (obrigatório*) | string | Nível da opção de envio. Opções disponíveis: standard, express. |
Nota: *Use tier para a seleção otimizada de transportadoras da Gelato. Se você usar tier, deixe uid vazio, e vice-versa.
Destinatário
Parameter | Tipo | Descrição |
pessoa (obrigatório) | Destinatário | Dados pessoais do destinatário. |
endereço (obrigatório) | Endereço | Detalhes do endereço do destinatário. |
alfândega (opcional) | Alfândega do Destinatário | Detalhes alfandegários do destinatário. |
Remetente
Parameter | Tipo | Descrição |
pessoa (obrigatório) | Remetente | Dados pessoais do remetente. |
endereço (obrigatório) | Endereço | Detalhes do endereço do remetente. |
alfândega (obrigatório para envios internacionais) | Alfândega do Remetente | Detalhes alfandegários do remetente. |
Destinatário
Parameter | Tipo | Descrição |
nome (obrigatório) | string | Nome do destinatário. |
sobrenome (obrigatório) | string | Sobrenome da pessoa destinatária. |
empresa (opcional) | string | O título da empresa. |
e-mail (opcional*) | string | Endereço de e-mail da pessoa. Isso pode ser usado para notificações de envio. |
telefone (opcional*) | string | Número de telefone da pessoa. Isso pode ser usado para notificações de envio. |
Nota: *E-mail e telefone podem ser campos obrigatórios dependendo da transportadora
Remetente
Parameter | Tipo | Descrição |
nome (opcional) | string | Nome do remetente. |
sobrenome (opcional) | string | Sobrenome da pessoa remetente. |
empresa (obrigatório) | string | O título da empresa remetente. |
e-mail (opcional*) | string | Endereço de e-mail da pessoa / empresa remetente. |
telefone (opcional*) | string | Número de telefone da pessoa / empresa remetente. |
Nota: *E-mail e telefone podem ser campos obrigatórios dependendo da transportadora
Endereço
Parameter | Tipo | Descrição |
país (obrigatório) | string | Código do país no formato de 2 letras. |
estado (opcional*) | string | Estado / município / região. |
cidade (obrigatório) | string | Cidade. |
CEP (obrigatório) | string | CEP. |
endereço linha 1 (obrigatório) | string | Primeira linha do endereço postal. Deve incluir rua e número da casa. |
linha de endereço 2 (opcional) | string | Segunda linha do endereço postal. Número do apartamento / escritório / andar. |
endereço linha 3 (opcional) | string | Terceira linha do endereço postal. |
rua (opcional*) | string | Rua (obrigatório para endereços na Alemanha). |
número da casa (opcional*) | string | Número da casa (obrigatório para endereços na DE). |
bairro (opcional*) | string | Bairro (obrigatório para endereços na AU / NZ). |
Nota: *Estes campos opcionais são obrigatórios para países e transportadoras específicos.
Alfândega do Destinatário
Parameter | Tipo | Descrição |
Número de IVA (opcional) | string | Número de IVA do destinatário. |
Alfândega do Remetente
Parameter | Tipo | Descrição |
Número de IVA (opcional*) | string | Número de IVA do remetente. |
número iossNumber (opcional*) | string | Número IOSS do remetente. |
número EORI (opcional*) | string | Número EORI do remetente. |
pcccNumber (opcional*) | string | Número PCCC do remetente. |
número de empresa australiano (opcional*) | string | Número de empresa australiano do remetente. |
Nota: *Dependendo do país do remetente e do destinatário, esses campos podem ser obrigatórios.
Pacote
Parameter | Tipo | Descrição |
packageReferenceId (obrigatório) | string | ID do pacote fornecido pelo parceiro. |
peso bruto (obrigatório) | número | Peso da embalagem + peso dos itens (em gramas por padrão). |
peso líquido (opcional) | número | Peso dos itens (em gramas por padrão). |
comprimento (obrigatório) | número | Comprimento do pacote (em mm por padrão). |
largura (obrigatório) | número | Largura do pacote (em mm por padrão). |
altura (obrigatório) | número | Altura do pacote (em mm por padrão). |
peso volumétrico (opcional) | número | Peso calculado com base no tamanho do pacote (em gramas por padrão). |
boxType (opcional) | string | Formato da caixa (ex.: retângulo, tubo). |
valor (obrigatório para envios internacionais) | número | Valor total de todos os itens na embalagem (na moeda selecionada). |
itens (obrigatório para envios internacionais) | Item[] | Matriz de itens no pacote. |
Item*
Parameter | Tipo | Descrição |
itemReferenceId (obrigatório) | string | ID fornecido pelo parceiro do item do pacote. |
descrição (obrigatório) | string | Descrição do item. |
quantidade (obrigatório) | número | Quantidade do item. |
valor (obrigatório) | número | Valor do item (na moeda selecionada). |
peso (obrigatório) | número | Peso do item (em gramas por padrão). |
código HS (obrigatório) | string | Código do Sistema Harmonizado (Wiki). |
país de origem (obrigatório) | string | Código do país no formato de 2 letras onde o item foi produzido. |
Nota: *Todos os parâmetros do Item são necessários apenas para envios internacionais.
Resposta bem-sucedida
Parameter | Tipo | Descrição |
orderId | string | ID único para pedido de envio em nosso sistema. |
orderReferenceId | string | ID exclusivo para pedido de envio fornecido por você. |
métodoDeEnvio | Método de Envio de Resposta | Método de envio utilizado para o pedido de remessa. |
pacotes | ResponsePackage[] | Pacotes utilizados para o pedido de envio. |
Método de Envio de Resposta
Parameter | Tipo | Descrição |
transportadora | string | Transportadora utilizada para criar um pedido. |
uid | string | UID do método de envio usado para criar um pedido. |
Pacote de Resposta
Parameter | Tipo | Descrição |
ID de referência do pacote | string | ID do pacote fornecido pelo parceiro. |
número de rastreamento | string | Número de rastreamento fornecido pela transportadora. |
URL de rastreamento | string | URL de rastreamento fornecida pela transportadora. |
etiqueta | Rótulo de resposta | Etiqueta de envio para o pedido de remessa. |
documentos (opcional) | ResponseDocument[] | Documentos para o pedido de envio. |
totalCost (opcional) | Custo Total da Resposta | Custo estimado para envio do pacote. |
Rótulo de resposta
Parameter | Tipo | Descrição |
nomeDoArquivo | string | Nome do arquivo da etiqueta. |
URL do arquivo | string | URL para baixar a etiqueta. |
tipo de conteúdo | string | Tipo de conteúdo da etiqueta. |
Documento de Resposta
Parameter | Tipo | Descrição |
tipoDeDocumento | string | Tipo de documento (ex.: fatura). |
nomeDoArquivo | string | Nome do arquivo do documento. |
URL do arquivo | string | URL para baixar o documento. |
tipo de conteúdo | string | Tipo de conteúdo do documento. |
Custo Total da Resposta
Parameter | Tipo | Descrição |
valor (opcional) | número | Custo estimado para envio do pacote. (opcional) |
moeda (opcional) | string | Moeda |
Resposta de erro
Parameter | Tipo | Descrição |
orderReferenceId | string | ID exclusivo para pedido de envio fornecido por você. |
código | string | Código de erro. |
mensagem | string | Mensagem de erro. |
detalhe (opcional) | objeto | Mensagem de erro detalhada (objeto JSON de uma estrutura arbitrária). |
erros (opcional) | ResponseErrorDetails[] | Matriz de erros. |
Detalhes do Erro de Resposta
Parameter | Tipo | Descrição |
código | string | Código de erro. |
mensagem | string | Mensagem de erro |
referência (opcional) | string | ID de referência. |
Próximo Passo: 🔗[GCL] Logistics API - Shipping Order Create Draft
📝 Não é o que você precisava?
Ajude-nos a melhorar este artigo, envie-nos um e-mail para [email protected] — por favor, inclua o título do artigo.