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.
-
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.
UsoEasyshipDocuments.xsd
para formar o conteúdo do documento do feed.FeedType.
EspecifiquePOST_EASYSHIP_DOCUMENTS
ao chamar a operaçãocreateFeed
.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:
<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:
<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.
-
Chame a operação
getReport
. Ao especificar o parâmetroreportId
, use o valorReportReferenceId
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çãogetReportDocument
na etapa seguinte. -
Chame a operação
getReportDocument
, especificandoreportDocumentId
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.
Marketplace | Região | Supported handover methods | Get time slots | Create package | Update package | Get package status | Shipping label | Fatura | Garantia | Bulk Package Scheduling |
---|---|---|---|---|---|---|---|---|---|---|
México | NA | Pickup and Dropoff | Somente pedidos não agendados | Compatível | Não suportado | Compatível | Compatível | Não suportado | Não suportado | Não suportado |
Índia | EU | Pickup ou todos | Pedidos agendados e não programados | Compatível | Compatível | Compatível | Compatível | Compatível | Compatível | Não suportado |
Turquia | EU | Pickup and Dropoff | Somente pedidos não agendados | Compatível | Não suportado | Compatível | Compatível | Não suportado | Não suportado | Não suportado |
Austrália | FE | Pickup ou todos | Somente pedidos não agendados | Compatível | Não suportado | Compatível | Compatível | Não suportado | Não suportado | Não suportado |
Singapura | FE | Pickup ou todos | Somente pedidos não agendados | Compatível | Não suportado | Compatível | Compatível | Não suportado | Não suportado | Não suportado |
Japão | FE | Pickup ou todos | Somente pedidos não agendados | Compatível | Não suportado | Compatível | Compatível | Não suportado | Não suportado | Não suportado |
Países Baixos | EU | Dropoff ou todos | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Compatível |
Polônia | EU | Pickup ou todos | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Não suportado | Não compatível | Compatível |
Updated 3 months ago