Guia de casos de uso da API do Easy Ship v2022-03-23

Como usar a API Easy Ship.

Versão da API: v2022-03-23

O que é a API Easy Ship?

Você pode usar a API do parceiro de vendas do Easy Ship para criar aplicativos para que os vendedores gerenciem e enviem pacotes para pedidos do Amazon Easy Ship.

Principais recursos

  • Obtenha os horários disponíveis.
  • Agende e reagende pacotes do Easy Ship para pedidos do Easy Ship.
  • Imprima etiquetas de remessa, faturas e documentos de garantia.

Tutorial: agende um pacote Easy Ship

Saiba como usar a API Easy Ship para agendar um pacote para um pedido Easy Ship.

Etapa 1. obtenha os horários disponíveis

Chame a operação listHandoverSlots para obter uma lista dos horários disponíveis para um pedido não programado do Easy Ship. Certifique-se do seguinte:

  • O ID de pedido da Amazon especificado deve ser um pedido Easy Ship e estar em estado não enviado.
  • A solicitação deve incluir o peso e as dimensões desejados da embalagem.

Pedidos que não sejam Easy Ship e pedidos em estado pendente retornarão uma resposta de erro.

Solicitação

Chame a operação listHandoverSlots.

Exemplo de solicitação:

POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot { "amazonOrderId": "933-1443575-9112638", "marketplaceId": "A21TJRUUN4KGV", "packageDimensions": { "length": 20.0, "width": 10.0, "height": 12.0, "unit": "Cm", "identifier": "test" }, "packageWeight": { "value": 100.0, "unit": "G" } }

Resposta

Uma resposta bem-sucedida inclui a lista de horários disponíveis. Cada horário especificará o método pelo qual o vendedor precisará entregar o pacote a uma transportadora da Amazon. Veja os métodos de entrega suportados para obter mais detalhes. Certifique-se de salvar o slotId, startTime, e endTime do período desejado para a próxima etapa.

Exemplo de resposta:

{ "amazonOrderId": "933-1443575-9112638", "timeSlots": [ { "handoverMethod": "Pickup", "slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=", "startTime": "2022-03-09T23:30:00Z", "endTime": "2022-03-10T02:00:00Z" }, { "handoverMethod": "Pickup", "slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=", "startTime": "2022-03-10T02:00:00Z", "endTime": "2022-03-10T04:30:00Z" } ] }

Etapa 2. crie um pacote Easy Ship

Chame a operação createScheduledPackage para criar um pacote para um pedido não programado do Easy Ship. Certifique-se do seguinte:

  • O ID de pedido da Amazon especificado deve ser um pedido Easy Ship e estar em estado não enviado.
  • A solicitação deve incluir o peso e as dimensões desejados da embalagem.

Pedidos que não sejam Easy Ship e pedidos em estado pendente retornarão uma resposta de erro.

Solicitação

Chame a operação createScheduledPackage.

Exemplo de solicitação:

POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package { "amazonOrderId": "933-1443575-9112638", "marketplaceId": "A21TJRUUN4KGV", "packageDetails": { "packageTimeSlot": { "slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=", "startTime": "2022-03-09T23:30:00Z", "endTime": "2022-03-10T02:00:00Z" } } }

Resposta

Uma resposta bem-sucedida inclui o peso e as dimensões do pacote, os detalhes da fatura (se houver), o horário selecionado e o status do pacote.

Exemplo de resposta:

{ "packageDimensions": { "identifier": "test", "unit": "Cm", "length": 20, "width": 10, "height": 12 }, "packageWeight": { "unit": "G", "value": 50 }, "invoice": { "invoiceNumber": "IN-456", "invoiceDate": "1.636404098172E9" }, "scheduledPackageId": { "amazonOrderId": "933-1443575-9112638", "packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f" }, "packageStatus": "ReadyForPickup", "packageTimeSlot": { "slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=", "startTime": "2022-03-09T23:30:00Z", "endTime": "2022-03-10T02:00:00Z" }, "trackingDetails": { "trackingId": "2045079155" } }

Tutorial: reagendar um pacote Easy Ship

Saiba como usar a API Easy Ship para reagendar um pacote para um pedido Easy Ship. Para usar o listHandoverSlots e updateScheduledPackages operações, o pedido da Amazon com o especificado orderId deve ser agendado e o Pacote Easy Ship deve ter um estado válido. Consulte Tutorial: Verifique o status de um pacote Easy Ship para obter mais detalhes.

Dica

Somente um vendedor pode atualizar o horário selecionado para um pacote Easy Ship.

Etapa 1. Obtenha os horários disponíveis para reagendamento

Chame a operação listHandoverSlots para obter uma lista dos horários disponíveis para um pedido agendado do Easy Ship.

Solicitação

Chame a operação listHandoverSlots.

Exemplo de solicitação:

POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot { "amazonOrderId": "933-1443575-9112638", "marketplaceId": "A21TJRUUN4KGV", "packageDimensions": { "length": 20.0, "width": 10.0, "height": 12.0, "unit": "Cm", "identifier": "test" }, "packageWeight": { "value": 100.0, "unit": "G" } }

Resposta

Uma resposta bem-sucedida inclui a lista de horários disponíveis. Certifique-se de salvar o slotId, startTime, e endTime do slot desejado para a próxima etapa.

Exemplo de resposta:

{ "amazonOrderId": "933-1443575-9112638", "timeSlots": [ { "handoverMethod": "Pickup", "slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=", "startTime": "2022-03-09T23:30:00Z", "endTime": "2022-03-10T02:00:00Z" }, { "handoverMethod": "Pickup", "slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=", "startTime": "2022-03-10T02:00:00Z", "endTime": "2022-03-10T04:30:00Z" } ] }

Etapa 2. atualizar um pacote Easy Ship

Chame a operação updateScheduledPackages para atualizar o horário de um pacote Easy Ship.

Solicitação

Chame a operação updateScheduledPackages.

Exemplo de solicitação:

PATCH https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package { "marketplaceId":"A21TJRUUN4KGV", "updatePackageDetailsList":[ { "scheduledPackageId":{ "amazonOrderId":"933-1443575-9112638", "packageId":"b4be5116-98b1-6f20-a47b-03de178cfb4f" }, "packageTimeSlot":{ "slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=", "startTime": "2022-03-10T02:00:00Z", "endTime": "2022-03-10T04:30:00Z" } } ] }

Resposta

Uma resposta bem-sucedida inclui os detalhes do pacote e o horário atualizado.

Exemplo de resposta:

{ "packages": [ { "packageDimensions": { "identifier": "test", "unit": "Cm", "length": 20, "width": 10, "height": 12 }, "packageWeight": { "unit": "G", "value": 50 }, "invoice": { "invoiceNumber": "IN-456", "invoiceDate": "1.636404098172E9" }, "scheduledPackageId": { "amazonOrderId": "933-1443575-9112638", "packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f" }, "packageStatus": "ReadyForPickup", "packageTimeSlot": { "slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=", "startTime": "2022-03-10T02:00:00Z", "endTime": "2022-03-10T04:30:00Z" }, "trackingDetails": { "trackingId": "2045079155" } } ] }

Tutorial: verifique o status de um pacote Easy Ship

Saiba como usar a API Easy Ship para verificar o status de um pacote Easy Ship. Essa operação permite que o vendedor veja o peso, as dimensões, o intervalo de tempo e outros detalhes especificados de um pacote Easy Ship.

O status de um pacote é atualizado à medida que os eventos ocorrem no pacote. Exemplos de alguns desses eventos incluem

  • Um pacote é fornecido para uma transportadora da Amazon.
  • Um pacote foi entregue a um comprador.
  • Um pacote foi cancelado.
  • Um pacote foi perdido em trânsito.

É útil verificar o status atual de um pacote antes de reagendá-lo, pois os pacotes não podem ser reagendados após serem entregues a uma transportadora da Amazon. As operações de reagendamento falharão com um código InvalidOrderState se for tentado em um pacote Easy Ship em um estado inválido. Veja packageStatus para conferir todos os diferentes estados de um pacote.

Etapa 1. Obtenha um pacote Easy Ship

Chame a operação getScheduledPackage para obter os detalhes de um pacote Easy Ship.

Solicitação

Chame a operação getScheduledPackage.

Exemplo de solicitação:

GET https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package?marketplaceId=A21TJRUUN4KGV&amazonOrderId=933-6451079-5067861

Resposta

Uma resposta bem-sucedida inclui os detalhes do pacote.

Exemplo de resposta:

{ "packageDimensions":{ "unit":"Cm", "length":20, "width":10, "height":12 }, "packageWeight":{ "unit":"G", "value":50 }, "invoice":{ "invoiceNumber":"IN-442" }, "scheduledPackageId":{ "amazonOrderId":"933-6451079-5067861", "packageId":"88be1771-923c-d581-5e29-e8a310916185" }, "packageStatus":"ReadyForPickup", "packageTimeSlot":{ "slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=", "startTime": "2022-03-10T02:00:00Z", "endTime": "2022-03-10T04:30:00Z" }, "trackingDetails": { "trackingId": "2045079155" } }

Tutorial: lidar com itens de pedidos que exigem números de série

Alguns itens em um pedido do Amazon Easy Ship exigem números de série para que a Amazon possa gerar documentos de garantia para eles. Saiba como usar a API Easy Ship para descobrir quais itens exigem números de série.

Etapa 1. Obtenha uma lista de pedidos que exigem números de série

Chame a operação getOrderItems, especificando o ID do pedido da Amazon para o pedido para o qual você deseja criar um pacote programado.

A Amazon devolve os itens em ordem, marcando os itens que exigem um número de série com SerialNumberRequired=true.

Etapa 2. Agende pacotes Easy Ship com números de série

Chame a operação createScheduledPackage usando PackageItems para especificar números de série para todos os itens marcados SerialNumberRequired=true na Etapa 1. Não especifique números de série para itens marcados SerialNumberRequired=false.

A Amazon gera documentos de garantia para os itens para os quais você especificou números de série. Para obter informações sobre como obter os documentos que a Amazon gera quando você cria um pacote programado, consulte Como obter a fatura, a etiqueta de endereço e os documentos de garantia.

Tutorial: Obtenha etiquetas de envio, faturas e documentos de garantia

A Amazon gera uma fatura quando um comprador faz um pedido do Amazon Easy Ship na Índia. Quando você chama a operação CreateScheduledPackage para agendar um horário do Amazon Easy Ship para o pedido, a Amazon gera uma etiqueta de endereço. Se você incluir números de série para os itens especificados em sua chamada para CreateScheduledPackage, a Amazon também gera documentos de garantia para os itens. Este tópico explica como obter faturas, etiquetas de endereço e garantias para pedidos programados do Amazon Easy Ship.

Etapa 1: enviar uma solicitação do Easy Ship Feed

Envie uma solicitação de feed para solicitar documentos para os pedidos do Easy Ship desejados. Depois que uma solicitação de feed for processada com sucesso, você poderá baixar o relatório de processamento para obter o ID de referência do relatório. Ela poderá ser usada na próxima etapa para baixar os documentos solicitados do Easy Ship.

  1. Siga o Tutorial: Enviar um feed para enviar um feed do Easy Ship. O tutorial explica todas as etapas, desde o envio do documento do feed até a verificação de que a solicitação do feed foi concluída com êxito.

    • FeedContent. Uso EasyshipDocuments.xsd para formar o conteúdo do documento do feed.
    • FeedType. Especifique POST_EASYSHIP_DOCUMENTS ao chamar a operação createFeed.
    • ReportReferenceId. Se não houver erros no relatório de processamento do feed, o valor retornado poderá ser usado na próxima etapa.

    Exemplo de documento do Easy Ship Feed:

    <?xml version="1.0" encoding="utf-8" ?> <AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd"> <Header> <DocumentVersion>1.01</DocumentVersion> <MerchantIdentifier>ABCDEFG007V</MerchantIdentifier> </Header> <MessageType>EasyShipDocument</MessageType> <Message> <MessageID>1</MessageID> <EasyShipDocument> <AmazonOrderID>933-6451079-5067861</AmazonOrderID> <DocumentType>ShippingLabel</DocumentType> <DocumentType>Invoice</DocumentType> <DocumentType>Warranty</DocumentType> </EasyShipDocument> </Message> </AmazonEnvelope>

    Exemplo do relatório de processamento do Easy Ship Feed:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <EasyShipProcessingReport> <FeedSubmissionID>98765432100</FeedSubmissionID> <MessagesProcessed>1</MessagesProcessed> <MessagesSuccessful>1</MessagesSuccessful> <MessagesWithError>0</MessagesWithError> <DocumentReportReferenceID>123456789000</DocumentReportReferenceID> </EasyShipProcessingReport>

Etapa 2: obter o PDF

Obtenha um PDF que contenha a fatura, a etiqueta de endereço e os documentos de garantia (se disponíveis) do pedido do Amazon Easy Ship.

  1. Chame a operação getReport. Ao especificar o parâmetro reportId, use o valor ReportReferenceId da Etapa 1: enviar uma solicitação de feed do Easy Ship.

    A operação retorna um valor reportDocumentId que você pode passar para a operação getReportDocument na etapa seguinte.

  2. Chame a operação getReportDocument, especificando reportDocumentId da etapa anterior. Consulte Recuperar um relatório para obter mais detalhes.

Suporte do Marketplace

As operações do Easy Ship só estão disponíveis em mercados selecionados e o suporte para operações específicas varia em cada mercado. Consulte a tabela a seguir para ver as operações suportadas pelo marketplace.

MarketplaceRegiãoSupported handover methodsGet time slotsCreate packageUpdate packageGet package statusShipping labelFaturaGarantiaBulk Package Scheduling
MéxicoNAPickup and DropoffSomente pedidos não agendadosCompatívelNão suportadoCompatívelCompatívelNão suportadoNão suportadoNão suportado
ÍndiaEUPickup ou todosPedidos agendados e não programadosCompatívelCompatívelCompatívelCompatívelCompatívelCompatívelNão suportado
TurquiaEUPickup and DropoffSomente pedidos não agendadosCompatívelNão suportadoCompatívelCompatívelNão suportadoNão suportadoNão suportado
AustráliaFEPickup ou todosSomente pedidos não agendadosCompatívelNão suportadoCompatívelCompatívelNão suportadoNão suportadoNão suportado
SingapuraFEPickup ou todosSomente pedidos não agendadosCompatívelNão suportadoCompatívelCompatívelNão suportadoNão suportadoNão suportado
JapãoFEPickup ou todosSomente pedidos não agendadosCompatívelNão suportadoCompatívelCompatívelNão suportadoNão suportadoNão suportado
Países BaixosEUDropoff ou todosNão suportadoNão suportadoNão suportadoNão suportadoNão suportadoNão suportadoNão suportadoCompatível
PolôniaEUPickup ou todosNão suportadoNão suportadoNão suportadoNão suportadoNão suportadoNão suportadoNão compatívelCompatível

Esta página ajudou você?