Guias de uso
Documentação GlobalDeveloper HubSuporteStatus da API

Caso de uso

Suggest Edits

Introdução

O Delivery By Amazon (também conhecido como DBA ou EasyShip) é o programa de entrega pela Amazon. É um serviço que irá beneficiar o seller por meio da nossa rede de provedores de serviços logísticos parceiros, impactando positivamente o negócio do seller e os clientes.

Com o DBA, o seller irá vender os produtos dele, embalar, emitir e enviar a nota fiscal (em casos de vendedores CNPJ) para a Amazon, imprimir a etiqueta e nós, Amazon, seremos responsáveis por entregá-los aos clientes, com condições mais atraentes, entregas rápidas e 100% rastreáveis e com mais opções de frete grátis.

Conceitos básicos

  • O DBA é um programa aberto para os sellers. Qualquer seller que tiver o interesse consegue rapidamente se cadastrar pelo seller central.

  • Não há necessidade de conversão dos produtos por meio do envio de um feed específico. Uma vez que o seller se cadastra no programa e os produtos deles estão elegíveis para o programa (ex: não é hazmat, etc) a Amazon fará a conversão dos produtos automaticamente. Os produtos não elegíveis permanecerão no programa “SelfShip” (envio pelo seller).

  • O cadastro de produto, gestão de inventário, preço, continuam como era antes em produtos de “SelfShip” (envio pelo seller). Não há nenhuma mudança.

  • Os pedidos devem ser importados através da API de Orders.

  • Os xmls das notas fiscais devem ser encaminhados para a Amazon através da API Shipment Invoicing v2022-07-01 (obrigatório somente para vendedores CNPJ).

  • Por meio da API Easy Ship, você consegue agendar a coleta de pedidos, ter acesso às etiquetas de envio (Shipping Label) / lista de postagens (post list) para emissão e aos ids de rastreios.

  • Os produtos NÃO recebem selo prime. O selo prime só é liberado em produtos do programa Seller Flex ou FBA Classic.

Fluxogramas

Fluxograma de importação de pedidos

Esse fluxo consiste em importar os pedidos DBA com as informações necessárias. Saiba mais detalhes nos tópicos 2 e 3.

Fluxograma da nota fiscal

Esse fluxo consiste em submeter e consultar o status da nota fiscal na Amazon. Saiba mais detalhes no tópico 4.

Fluxograma de agendamento de coleta e emissão de etiqueta de envio

Esse fluxo consiste em imprimir a etiqueta de envio e a Post List. O agendamento da coleta acontecerá de forma automática. Saiba mais detalhes no tópico 5.

Notificação de orders

Você pode usar a notificação ORDER_STATUS_CHANGE para manter o gerenciamento dos seus pedidos. Se optar por usá-la saiba que você receberá uma notificação na sua fila SQS toda vez que um pedido for criado, sofrer alteração de status ou for cancelado.

Exemplo de notificação

{
    "NotificationVersion": "1.0",
    "NotificationType": "ORDER_STATUS_CHANGE",
    "PayloadVersion": "1.0",
    "EventTime": "2020-07-13T19:42:04.284Z",
    "Payload": {
        "OrderStatusChangeNotification": {
            "SellerId": "AXXXXXXXXXXXXX",
            "MarketplaceId": " A2Q3Y263D00KWC",
            "AmazonOrderId": "333-7777777-7777777",
            "PurchaseDate": 1595882000633,
            "OrderStatus": "Unshipped",
            "DestinationPostalCode": "48110",
            "SupplySourceId": "55448834-0d79-5155-75c4-8529543a7c31",
            "OrderItemId": "OIID34853450",
            "SellerSKU": "SellerSKUID1",
            "Quantity": 45,
            "FulfillmentChannel": "MFN"
        }
    },
    "NotificationMetadata": {
        "ApplicationId": "app-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
        "SubscriptionId": "subscription-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
        "PublishTime": "2020-07-13T19:42:04.284Z",
        "NotificationId": "d0e9e693-c3ad-4373-979f-ed4ec98dd746"
    }
}

❗️

Importante

Você pode optar por fazer o gerenciamento dos pedidos DBA usando essa notificação paralelamente com a API de Orders ou optar por fazer o gerenciamento de pedidos somente chamando a API de orders, isto é, sem usar a notificação.

❗️

Importante

Para usar a notificação você precisar de uma fila SQS cadastrada. Caso não tenha uma, acesse esse material para saber mais

❗️

Importante

A inscrição na notificação é por seller, portanto, caso você decida fazer o gerenciamento dos pedidos usando essa notificação tenha em mente que cada seller que entrar no programa deverá ser inscrito nesse notificationType, na sua fila, para que assim você receba essas atualizações via SQS.Para saber mais sobre como inscrever um seller na notificationType, clique aqui.

❗️

Importante

Essa notificação não é exclusiva para o programa DBA, ou seja, ao inscrever o seller nela você receberá notificações de pedidos com o FulfillmentChannel = “MFN” (relacionados aos programas “SelfShip” e “DBA”) e pedidos com o FulfillmentChannel = “AFN” (relacionados aos programas “FBA Onsite” e “FBA Classic”)

❗️

Importante

Você pode deletar as notificações que receber na sua fila com FulfillmentChannel = “AFN” caso não tenha esses programas desenvolvidos.

❗️

Importante

Notificações "OrderStatus": "Upcoming" podem ser excluídas e ignoradas. Comecem a reserva de estoque/importação dos pedidos somente a partir do recebimento da notificação de "OrderStatus": "Pending."

Fluxo de importação de pedidos

Após receber as notificações de pedidos, é necessário importá-los para a sua plataforma. Para fazer isso você deve utilizar a API de Orders chamando 2 endpoints:

  • GetOrders
  • GetOrderItems

❗️

Importante

Caso não utilize a notificação basta criar uma rotina de importação de pedidos sem colocá-la no fluxo. Atente-se aos limites de requests de cada chamada.

RDT

Antes de rodar a API de Orders é necessário gerar um RDT (Restricted Data Token) que funcione para esta API para poder acessar dados sensíveis.

RDT para o GetOrders

Exemplo de requisição 

https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken

{
    "restrictedResources": [
        {
            "method": "GET",
            "path": "/orders/v0/orders/{order-id}/orderItems",
            "dataElements": [
                "buyerInfo"
            ]
        }
    ]
}

Exemplo de reposta 

{
    "payload": {
        "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
        "expiresIn": 3600
    }
}

RDT para o GetOrderItems

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken

{
    "restrictedResources": [
        {
            "method": "GET",
            "path": "/orders/v0/orders/{order-id}/orderItems",
            "dataElements": [
                "buyerInfo"
            ]
        }
    ]
}

Exemplo de resposta

{
    "payload": {
        "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
        "expiresIn": 3600
    }
}

Orders API – GetOrders

Path

GET /orders/v0/orders?AmazonOrderIds={AmazonOrderIds}&MarketplaceIds={MarketplaceIds}

Descrição

Essa API retorna os dados de pedidos criados ou atualizados durante o prazo indicado pelos parâmetros especificados. Você também pode aplicar uma série de critérios de filtragem para restringir a lista de pedidos retornados. Se o NextToken estiver presente, ele deve ser usado para recuperar os pedidos em vez de outros critérios. Use o valor retornado na chamada de RDT para popular o xamzaccess-token.

Plano de uso

Rate (Requisições por segundo)Busrt
0.016720

Parâmetros

  • Alguns parâmetros disponíveis. Para ver todos os parâmetros disponíveis nessa chamada, clique aqui:
TipoNomeDescriçãoSchemaRequerido
QueryMarketplaceIdsMarketplace id do país específico. Nesse caso usar o do Brasil: A2Q3Y263D00KWCArray de stringSim
QueryEasyShipShipmentStatusesUma lista de valores EasyShipShipmentStatus. Usado para selecionar pedidos DBA com status que correspondam aos valores especificados. Se EasyShipShipmentStatus for especificado, somente os pedidos Amazon DBA serão retornados.
Valores possíveis:
• PendingSchedule: O pacote está aguardando o agendamento da coleta.
• PendingPickUp: A Amazon ainda não coletou o pacote do seller.
• PendingDropOff: O seller tem que entregar o pacote para a transportadora.
• LabelCanceled: O seller cancelou o agendamento.
• PickedUp: A Amazon já coletou o pacote do seller.
• DroppedOff: O pacote foi entregue pelo seller para a transportadora.
• Delivered: O pacote foi entregue ao comprador.
• RejectedByBuyer: O pacote foi rejeitado pelo comprador.
• Undeliverable: O pacote não pode ser entregue.
• ReturningToSeller: O pacote não foi entregue ao comprador e está sendo devolvido ao seller.
• ReturnedToSeller: O pacote não foi entregue ao comprador e foi devolvido ao seller.
• Lost: O pacote está perdido.
• OutForDelivery: O pacote está fora para entrega.
• Damaged: O pacote foi danificado pela transportadora		stringNão
QueryNextTokenUm token de string retornado na resposta de sua solicitação anteriorstringNão
QueryAmazonOrderIdsUma lista de valores AmazonOrderId. Um AmazonOrderId é um identificador de pedido definido pela Amazon, no formato 3-7-7.
Contagem máxima: 50		Array de strinNão

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/orders/v0/orders?AmazonOrderIds=701-5250991-
8194635&MarketplaceIds=A2Q3Y263D00KWC

Exemplo de resposta

{
    "payload": {
        "Orders": [
            {
                "BuyerInfo": {
                    "BuyerEmail": "[email protected]",
                    "BuyerCounty": "Bela Vista"
                },
                "AmazonOrderId": "752-2219524-7348619",
                "EarliestDeliveryDate": "2022-06-02T03:00:00Z",
                "EarliestShipDate": "2022-05-31T03:00:00Z",
                "SalesChannel": "Amazon.com.br",
                "AutomatedShippingSettings": {
                    "HasAutomatedShippingSettings": false
                },
                "OrderStatus": "Unshipped",
                "NumberOfItemsShipped": 0,
                "OrderType": "StandardOrder",
                "IsPremiumOrder": false,
                "IsPrime": false,
                "FulfillmentChannel": "MFN",
                "NumberOfItemsUnshipped": 1,
                "HasRegulatedItems": false,
                "IsReplacementOrder": "false",
                "IsSoldByAB": false,
                "LatestShipDate": "2022-06-01T02:59:59Z",
                "ShipServiceLevel": "Std EZ Local",
                "DefaultShipFromLocationAddress": {
                    "AddressLine2": "São Paulo",
                    "StateOrRegion": "SÃO PAULO",
                    "AddressLine1": "São Paulo, 123",
                    "Phone": "555 555-5555",
                    "PostalCode": "01135020",
                    "City": "São Paulo",
                    "CountryCode": "BR",
                    "Name": "Alexander"
                },
                "IsISPU": false,
                "MarketplaceId": "AZXD3QD5B39HD",
                "LatestDeliveryDate": "2022-06-07T02:59:59Z",
                "PurchaseDate": "2022-05-30T15:33:14Z",
                "ShippingAddress": {
                    "StateOrRegion": "Sao Paulo",
                    "PostalCode": "01319-900",
                    "City": "Sao Paulo",
                    "CountryCode": "BR"
                },
                "IsAccessPointOrder": false,
                "PaymentMethod": "Other",
                "IsBusinessOrder": false,
                "OrderTotal": {
                    "CurrencyCode": "BRL",
                    "Amount": "43.18"
                },
                "PaymentMethodDetails": [
                    "GiftCertificate"
                ],
                "IsGlobalExpressEnabled": false,
                "LastUpdateDate": "2022-05-30T16:19:05Z",
                "ShipmentServiceLevelCategory": "Standard",
                "ElectronicInvoiceStatus": "NotFound"
            },
            {
                "BuyerInfo": {
                    "BuyerEmail": "[email protected]",
                    "BuyerCounty": "Bela Vista"
                },
                "AmazonOrderId": "952-1394384-6312625",
                "EarliestDeliveryDate": "2022-06-02T03:00:00Z",
                "EarliestShipDate": "2022-05-31T03:00:00Z",
                "SalesChannel": "Amazon.com.br",
                "AutomatedShippingSettings": {
                    "HasAutomatedShippingSettings": false
                },
                "OrderStatus": "Unshipped",
                "NumberOfItemsShipped": 0,
                "OrderType": "StandardOrder",
                "IsPremiumOrder": false,
                "IsPrime": false,
                "FulfillmentChannel": "MFN",
                "NumberOfItemsUnshipped": 1,
                "HasRegulatedItems": false,
                "IsReplacementOrder": "false",
                "IsSoldByAB": false,
                "LatestShipDate": "2022-06-01T02:59:59Z",
                "ShipServiceLevel": "Std EZ Local",
                "DefaultShipFromLocationAddress": {
                    "AddressLine2": "São Paulo",
                    "StateOrRegion": "SÃO PAULO",
                    "AddressLine1": "São Paulo, 123",
                    "Phone": "555 555-5555",
                    "PostalCode": "01137766",
                    "City": "São Paulo",
                    "CountryCode": "BR",
                    "Name": "testename"
                },
                "IsISPU": false,
                "MarketplaceId": "A2Q3Y263D00KWC",
                "LatestDeliveryDate": "2022-06-07T02:59:59Z",
                "PurchaseDate": "2022-05-30T15:34:18Z",
                "ShippingAddress": {
                    "StateOrRegion": "Sao Paulo",
                    "PostalCode": "01319-900",
                    "City": "Sao Paulo",
                    "CountryCode": "BR"
                },
                "IsAccessPointOrder": false,
                "PaymentMethod": "Other",
                "IsBusinessOrder": false,
                "OrderTotal": {
                    "CurrencyCode": "BRL",
                    "Amount": "43.18"
                },
                "PaymentMethodDetails": [
                    "GiftCertificate"
                ],
                "IsGlobalExpressEnabled": false,
                "LastUpdateDate": "2022-05-30T16:20:07Z",
                "ShipmentServiceLevelCategory": "Standard",
                "EasyShipShipmentStatus": "PendingSchedule",
                "ElectronicInvoiceStatus": "Accepted"
            }
        ],
        "NextToken": "UGYYhHsRleGaJqJYLDm0ZAmQazDrhw3C09uoReIMT5lUojdU4H46tsNI3HOI22PIxqXyQLkGMBs8VhF73Xgy+9f32XRKG2brqFgiT4dRcg7+pDWtTzLT/mSM0rf71Y7MInTAy+XKVmRZBY+oaVuycwQFure81U/CbNnRLnMRDB36YUM3QLuNukElRijvo92f2GLmUGyr9UGnxD0RJmrryegoU0IPZxXH5ONIrrUMtTIpzs55mWnSB8egkQf5MvgMBO/reDY2s/VSsSZnYLBv5zJkJrX4f/3IIYkgmdzyCpNQzRAUqdu/lLe5xTjsfs3Wh6eH2mzao0flzT+NbaI3vyAULdxUEMyQQAxFNyFufa3Qls5+H7qLvj6KB3gIU8fN3wU5DX8pYxW ut/lzAoWkIMwoUFiWgZyU65VjUQZRinL52R7aRQ/Y22iMYFXG9yK6G4I/dhxbeqPnp7zXB4uNUJjuV2l U3LFiOJgwRc5hsrPZjTnVM/HGQ==",
        "CreatedBefore": "2022-06-09T20:14:38Z"
    }
}

Parâmetros importantes na resposta 200 http code:

O campo “ElectronicInvoiceStatus” é o status da nota fiscal eletrônica. Segue lista com o significado de cada “ElectronicInvoiceStatus”:

  • NotRequired = Não é necessário o envio da nota fiscal nesse caso.

  • NotFound = Pendente a submissão da nota fiscal. Não encontrado nenhuma submissão.

  • Processing = Validação da Nota Fiscal está em processamento.

  • Accepted = Validação da Nota Fiscal foi realizada com sucesso e aceita pela Amazon.

  • Errored = Houve um erro com a validação da nota (provavelmente algo com InvalidDigestValue ou InvalidSignature). Tentar novamente.

O campo “EasyShipShipmentStatus” é o status do pedido Amazon DBA. Este campo está disponível apenas para pedidos Amazon DBA. Segue lista com o significado de cada “EasyShipShipmentStatus”:

  • PendingSchedule: O pacote está aguardando o agendamento da coleta.

  • PendingPickUp: A Amazon ainda não coletou o pacote do seller.

  • PendingDropOff: O seller tem que entregar o pacote para a transportadora.

  • LabelCanceled: O seller cancelou o agendamento.

  • PickedUp: A Amazon já coletou o pacote do seller.

  • DroppedOff: O pacote foi entregue pelo seller para a transportadora.

  • Delivered: O pacote foi entregue ao comprador.

  • RejectedByBuyer: O pacote foi rejeitado pelo comprador.

  • Undeliverable: O pacote não pode ser entregue.

  • ReturningToSeller: O pacote não foi entregue ao comprador e está sendo devolvido ao seller.

  • ReturnedToSeller: O pacote não foi entregue ao comprador e foi devolvido ao seller.

  • Lost: O pacote está perdido.

  • OutForDelivery: O pacote está fora para entrega.

  • Damaged: O pacote foi danificado pela transportadora

Para saber sobre todos os possíveis retornos e o que cada um significa veja mais aqui.

❗️

Importante

Use o GetOrders ou GetOrder para diferenciar qual pedido é “DBA” e qual é “SelfShip”. Se o pedido tiver o campo “ElectronicInvoiceStatus” ou o campo “EasyShipShipmentStatus” significa que ele é DBA

❗️

Importante

O campo “EasyShipShipmentStatus” não aparece em pedidos com “OrdersStatus” igual a "Pending" ou "Canceled".

❗️

Importante

Diferencie na sua plataforma os pedidos com tags específicas de cada programa. Um pedido DBA não deve seguir o mesmo fluxo de processamento de um pedido “SelfShip”, por exemplo, e isso deve ficar visível para o seller na sua plataforma.

❗️

Importante

É recomendado realizar a reserva de estoque para pedidos com OrderStatus = “Pending”. Veja mais aqui

❗️

Importante

Chamadas que contenham acesso aos dados restritos precisam que o integrador use o RDT token no lugar do access token. Saiba mais aqui ou veja o tópico 3.1.

❗️

Importante

Se você quer buscar um OrderId por vez id você pode usar o GetOrder (veja mais aqui). Lembre-se de se atentar aos limites de requests disponibilizados pela Amazon para evitar throttling.

Orders API – GetOrderItems

Path

GET orders/v0/orders/{orderId}/orderItems

Descrição

Retorna as informações do comprador e do item do pedido especificado. Se o NextToken for fornecido, ele deve ser usado para recuperar a próxima página de itens do pedido. Use o valor retornado na chamada de RDT para popular o xamz-access-token. Observação: quando um pedido está no OrderStatus Pending (o pedido foi feito, mas o pagamento não foi autorizado), a operação getOrderItems não retorna informações sobre preços, impostos, taxas de envio, status do presente ou promoções para os itens do pedido no pedido. Depois que um pedido sai do estado OrderStatus (isso ocorre quando o pagamento foi autorizado) e entra no estado Unshipped, Partially Shipped, or Shipped, a operação getOrderItems retorna informações sobre preços, impostos, taxas de envio, status do presente e promoções para os itens do pedido.

Plano de uso

Rate (Requisições por segundo)Burst
0.530

Parâmetros:

  • Alguns parâmetros disponíveis. Para ver todos os parâmetros disponíveis nessa chamada, clique aqui:
TipoNomeDescriçãoSchemaRequerido
PathorderIdO identificador de pedido definido pela Amazon, no formato 3-7-7.stringSim
QueryNextTokenUm token de string retornado na resposta de sua solicitação anteriorstringSim
QueryAmazonOrderIdsUma lista de valores AmazonOrderId. Um AmazonOrderId é um identificador de pedido definido pela Amazon, no formato 3-7-7.
Contagem máxima: 50		Array de stringNão

Exemplo de requisição:

https://sellingpartnerapi-na.amazon.com/orders/v0/orders/701-8504864-5617063/orderItems

Exemplo de resposta:

{
    "payload": {
        "OrderItems": [
            {
                "ProductInfo": {
                    "NumberOfItems": "1"
                },
                "BuyerInfo": {},
                "ItemTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "QuantityShipped": 0,
                "ItemPrice": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.20"
                },
                "ASIN": "B07JM9487B",
                "SellerSKU": "puff",
                "Title": "Puff Infantil Banana Grande Unissex em Corino",
                "IsGift": "false",
                "ConditionSubtypeId": "New",
                "IsTransparency": false,
                "QuantityOrdered": 2,
                "PromotionDiscountTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "ConditionId": "New",
                "PromotionIds": [
                    "VPC-526970-153018660 Coupon"
                ],
                "PromotionDiscount": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "OrderItemId": "45975081693602"
            },
            {
                "ProductInfo": {
                    "NumberOfItems": "1"
                },
                "BuyerInfo": {},
                "ItemTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "QuantityShipped": 0,
                "ItemPrice": {
                    "CurrencyCode": "BRL",
                    "Amount": "20.00"
                },
                "ASIN": "B084Q59N8W",
                "SellerSKU": "B084Q59N8W",
                "Title": "Luminária de Mesa Articulavel Pixar Garra Base Quarto Preta",
                "ShippingTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "IsGift": "false",
                "ShippingPrice": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.25"
                },
                "ConditionSubtypeId": "New",
                "ShippingDiscount": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "ShippingDiscountTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "IsTransparency": false,
                "QuantityOrdered": 1,
                "PromotionDiscountTax": {
                    "CurrencyCode": "BRL",
                    "Amount": "0.00"
                },
                "ConditionId": "New",
                "PromotionIds": [
                    "VPC-526970-153018660 Coupon"
                ],
                "PromotionDiscount": {
                    "CurrencyCode": "BRL",
                    "Amount": "15.00"
                },
                "OrderItemId": "09400181061466"
            }
        ]
    }
}

Para saber sobre todos os possíveis retornos e o que cada um significa veja mais aqui.

❗️

Importante

Chamadas que contenham acesso aos dados restritos precisam que o integrador use o RDT token no lugar do access token. Saiba mais aqui ou veja o tópico 3.1.

❗️

Importante

Lembre-se de se atentar aos limites de requests disponibilizados pela Amazon para evitar throttling.

Fluxo da nota fiscal

Após importar os pedidos para a sua plataforma é necessário validar se o pedido precisa que a nota fiscal seja enviada para a Amazon e, se sim, que você envie e consulte o status de processamento. Para fazer isso, você deve utilizar a API de Shipment Invoicing v2022-07-01 chamando 2 endpoints:

  • submitInvoiceByOrderId
  • getInvoiceStatusByOrderId

❗️

Importante

Sellers CPF a Amazon aceita a declaração de contéudo ao invés da Nota fiscal, isto é, a nota fiscal nesse caso não é obrigatória. Portanto, o fluxo de nota fiscal só deve ser realizado para orders com o campo ElectronicInvoiceStatus diferente de “NotRequired”.

❗️

Importante

Para pedidos com ElectronicInvoiceStatus igual a “NotRequired” pular para o fluxo de agendamento de coleta e emissão de etiqueta de envio (tópico 5).

Shipment Invoicing API – submitInvoiceByOrderId

Path

POST /delivery/2022-07-01/invoice

Descrição

A API de submitInvoice permite com que o desenvolvedor envie o XML da nota fiscal em base 64 para a Amazon. Para o campo x-amz-access-token, utilizar o access token normal (não é o RDT).

Plano de uso

Rate (Requisições por segundo)Burst
1.13325

Parâmetros

TipoNomeDescriçãoSchemaRequerido
PathorderIdO identificador de pedido definido pela Amazon, no formato 3-7-7.stringSim
BodyinvoiceContentBase64 encode do XML da notastringSim
BodymarketplaceIdMarketplace id do país específico. Nesse caso usar o do Brasil: A2Q3Y263D00KWCstringSim
BodycontentMD5ValueSoma MD5 para validar os dados da nota fiscal. Para obter mais informações sobre como calcular esse valor, consulte Trabalhando com somas de verificação Content-MD5.stringSim
BodyinvoiceTypeO tipo da nota fiscal. Envie sempre como “Outbound”stringSim
BodyprogramTypeO tipo de programa. Envie sempre como “EasyShip”stringSim

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/delivery/2022-07-01/invoice?orderId=701-3301310-5485821

{
    "invoiceContent": "string",
    "marketplaceId": "string",
    "contentMD5Value": "string",
    "invoiceType": "Outbound",
    "programType": "EasyShip"
}

Exemplo de resposta

{}

❗️

Importante

A resposta, em caso de 200 http code vem vazia.

Shipment Invoicing API – getInvoiceStatusByOrderId

❗️

Importante

A Amazon processa a nota fiscal de forma assíncrona. Portanto, execute essa operação por volta de 5 minutos depois da submissão da nota fiscal para pegar um processamento concluído.

❗️

Importante

É importante que você deixe visível o status da nota fiscal na sua plataforma. Em casos de erros deixe visível para o seller o status e a chance de reencaminhar para a Amazon uma nota corrigida.

❗️

Importante

Assegure-se de que o seu aplicativo possua o role de Inventário e Rastreamento de Pedidos ( Inventory and Order Tracking ) para realizar essa chamada com sucesso.
Caso contrário, a resposta à solicitação retornará um código de status HTTP 403, acompanhado de informações detalhadas sobre o erro contidas no body da resposta.
Além disso, verifique cuidadosamente se a fatura integrada ao seu sistema está codificada em Base64, e que inclui o valor de contentMD5 no body.

Path

GET /delivery/2022-07-01/invoice/status

Descrição

Após envio da nota fiscal, é necessário saber se ela foi processada corretamente. Para o campo x-amzaccess-token, utilizar o access token normal (não é o RDT).

Plano de uso

Rate (Requisições por segundo)Burst
1.13325

Parâmetros

TipoNomeDescriçãoSchemaRequerido
QueryorderIdO identificador de pedido definido pela Amazon, no formato 3-7-7.stringSim
QuerymarketplaceIdMarketplace id do país específico. Nesse caso usar o do Brasil: A2Q3Y263D00KWCstringSim
QueryinvoiceTypeO tipo da nota fiscal. Envie sempre como “Outbound”stringSim
QueryprogramTypeO tipo de programa. Envie sempre como “EasyShip”stringSim

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/delivery/2022-07-01/invoice/status?orderId=701-3301310-5485821&marketplaceId=A2Q3Y263D00KWC&invoiceType=Outbound&programType=EasyShip

Exemplo de resposta

{
    "payload": {
        "amazonOrderId": "string",
        "invoiceStatus": " Accepted"
    }
}

Parâmetros importante no response 200 http code

NomeDescriçãoSchema
amazonOrderIdO identificador do pedidostring
invoiceStatusStatus de processamento da nota fiscalenum <
Processing
 Accepted
Errored
 NotFound
>

Segue lista com o significado de cada invoiceStatus:

  • Processing: Validação da Nota Fiscal está em processamento.

  • Accepted: O processo de validação da nota fiscal foi bem-sucedido e a nota fiscal foi aceita pela Amazon. Para casos de pedidos que não precisam de nota fiscal (orders que estiverem como ElectronicInvoiceStatus = “NotRequired” na API de Orders) sempre será retornado como NotFound aqui nesse campo.

  • Errored: Houve um erro com a validação da nota (provavelmente algo com InvalidDigestValue ou InvalidSignature). Tentar novamente.

  • NotFound: Não foi encontrado uma submissão com sucesso para os dados solicitados.

Fluxo de agendamento de coleta e emissão de etiqueta de envio

Após importar os pedidos para a sua plataforma, encaminhar a nota fiscal para a Amazon e consultar o status é necessário realizar o agendamento da coleta e emissão da etiqueta. Para fazer isso você deve utilizar a API de EasyShip chamando 1 endpoint:

  • createScheduledPackageBulk

RDT

Antes de rodar a API de Bulk EasyShip é necessário gerar um RDT (Restricted Data Token) que funcione para esta API.

RDT para o createScheduledPackageBulk

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken

{
    "restrictedResources": [
        {
            "method": "POST",
            "path": "/easyShip/2022-03-23/packages/bulk"
        }
    ]
}

Exemplo de resposta

{
    "payload": {
        "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
        "expiresIn": 3600
    }
}

Easy Ship API – createScheduledPackageBulk

❗️

Importante

Essa é uma chamada síncrona, portanto, a Amazon retornará os dados necessários (link para acessar etiqueta, data de coleta, etc) já no próprio response, incluindo os casos de orders que derem erro.

❗️

Importante

Um order-id com erro não invalida a chamada inteira. Ex: caso você encaminhe 3 pedidos e um deles está com erro, esse pedido com erro não será agendado e terá o motivo explicado no response e os demais pedidos seguirão o agendamento da coleta com sucesso.

❗️

Importante

Sempre será retornada apenas uma URL com todos os casos que deram sucesso.

Path

POST /easyShip/2022-03-23/packages/bulk

Descrição

Essa operação agenda automaticamente um horário de coleta para todos os amazonOrderIds informados como parâmetros, gerando as etiquetas de envio associadas, juntamente com outros documentos de conformidade de acordo com o marketplace (consulte a tabela de suporte de documentos do marketplace).

Em relação ao formato do arquivo da etiqueta de envio, os desenvolvedores externos podem escolher
entre PDF ou ZPL, e a Amazon criará a etiqueta de acordo.

Essa operação retorna um array composto pelos pacotes agendados e uma URL de curta duração apontando para um arquivo zip contendo as etiquetas de envio geradas e os demais documentos habilitados para seu marketplace. Se pelo menos um pedido não puder ser agendado, a Amazon adicionará a lista de rejectedOrders à resposta, que contém uma entrada para cada pedido que não conseguimos processar. Cada entrada é composta por uma mensagem de erro descrevendo o motivo da falha, para que os vendedores possam corrigir e reenviar.

❗️

Importante

Você só deve seguir com o agendamento e olhar para o campo EasyShipShipmentStatus quando o ElectronicInvoiceStatus for igual a “NotRequired” ou “Accepted”. Por exemplo, caso você tenha uma order com ElectronicInvoiceStatus = ”Errored” e EasyShipShipmentStatus = “PendingSchedule” isso significa que primeiro você deve resolver o problema da nota fiscal, enviar uma nova nota fiscal correta para a Amazon para que o status ElectronicInvoiceStatus fique como “Accepted” para depois seguir com a etapa de agendamento.

Plano de uso

Rate (Requisições por segundo)Burst
15

Parâmetros

TipoNomeDescriçãoSchemaRequerido
BodymarketplaceIdMarketplace id do país específico. Nesse caso usar o do Brasil: A2Q3Y263D00KWCstringSim
BodyamazonOrderIdUm identificador de pedido definido pela Amazon. Identifica o pedido que o vendedor deseja entregar usando o Amazon DBA. Podem ser encaminhados até 25 orders id na mesma chamada.stringSim
BodylabelFormatO formato de arquivo no qual a etiqueta de envio será criada. Opções possíveis “PDF” ou “ZPL”.stringSim

Exemplo de requisição

https://sellingpartnerapi-na.amazon.com/easyShip/2022-03-23/packages/bulk

{
    "marketplaceId": "A2Q3Y263D00KWC",
    "orderScheduleDetailsList": [
        {
            "amazonOrderId": "903-1713775-3598252"
        },
        {
            "amazonOrderId": "903-5645781-4567521"
        },
        {
            "amazonOrderId": "951-9026094-1233333"
        }
    ],
    "labelFormat": "ZPL"
}

Exemplo de resposta

Essa operação também retorna o resultado da criação do pacote por pedido, portanto, se um você adicionar 25 pedidos à solicitação, a Amazon retornará uma lista contendo 25 entradas, cada uma associada a um único pedido. É importante mencionar que alguns ou todos os pedidos podem falhar. Nesse caso, a Amazon adiciona no retorno da operação uma lista contendo as mensagens de erro de cada pedido que falhou, para que os vendedores possam tomar providências para resolvê-los.

{
    "scheduledPackages": [
        {
            "scheduledPackageId": {
                "amazonOrderId": "903-1713775-3598252",
                "packageId": "1ab0f06a-9149-87e0-aba9-7098117872d6"
            },
            "packageTimeSlot": {
                "startTime": "2022-03-09T23:30:00Z",
                "endTime": "2022-03-10T02:00:00Z"
            },
            "packageDimensions": {
                "length": 5.905511805,
                "width": 3.6220472404,
                "height": 3.4645669256,
                "unit": "IN",
                "identifier": "IN_SuggestedContainerDimension"
            },
            "packageWeight": {
                "value": 8.466,
                "unit": "ounces"
            },
            "packageStatus": "ReadyForPickup",
            "trackingDetails": {
                "trackingId": "1652969339691"
            }
        },
        {
            "scheduledPackageId": {
                "amazonOrderId": "903-5645781-4567521",
                "packageId": "80c06e53-3d96-f13f-30ca-85b50b1cb4ce"
            },
            "packageTimeSlot": {
                "startTime": "2022-05-21T06:08:52.036Z",
                "endTime": "2022-05-21T10:08:52.036Z"
            },
            "packageDimensions": {
                "length": 5.905511805,
                "width": 3.6220472404,
                "height": 3.4645669256,
                "unit": "IN",
                "identifier": "IN_SuggestedContainerDimension"
            },
            "packageWeight": {
                "value": 8.466,
                "unit": "ounces"
            },
            "packageStatus": "ReadyForPickup",
            "trackingDetails": {
                "trackingId": "1652969339693"
            }
        }
    ],
    "rejectedOrders": [
        {
            "amazonOrderId": "951-9026094-1233333",
            "error": {
                "code": "InvalidInput",
                "message": "Couldn't find the order details for 951-9026094-1233333"
            }
        }
    ],
    "printableDocumentsUrl": "https://www.amazon.com/documents.zip"
}

❗️

Importante

A URL tem duração de 3 minutos.

❗️

Importante

Uma única URL é retornada para todos as orders.

❗️

Importante

Se você encaminhar uma OrderId já agendada antes o mesmo agendamento será retornado, isto é, não há sobrescrita no agendamento.

❗️

Importante

Garanta que o seu seller saberá quais orders deram certo e quais não deram, qual foi o erro e como podem corrigir essas orders.

❗️

Importante

Deixe essas etiquetas disponíveis para os seus sellers poderem fazer o download na sua plataforma.

❗️

Importante

Aqui você tem uma resposta síncrona. No momento que fizer o input já terá o resultado com a url caso pelo menos uma das orders derem sucesso ou o nó de rejected orders para aquelas que derem erro.

Parâmetros importantes na resposta 200 http code

NomeDescriçãoSchemaAtributo pai
amazonOrderIdO identificador do pedido.stringScheduledPackageId
packageIdUm identificador definido pela Amazon para o pacote programado.stringScheduledPackageId
startTimeA data e hora de início do intervalo de tempo.DateTime string($date-time)
A datetime value in ISO 8601 format		packageTimeSlot
endTimeA data e hora de término do intervalo de tempo.DateTime string($date-time)
A datetime value in ISO 8601 format		packageTimeSlot
lengthComprimento.floatpackageDimensions
widthLargura.floatpackageDimensions
heightAltura.floatpackageDimensions
unitA unidade de medida usada para medir o comprimento.
Possível valor em “Cm”		UnitOfLengthstringpackageDimensions
identifierIdentificador para dimensões de pacote personalizadas.stringpackageDimensions
valueO peso do pacote.floatpackageWeight
unitA unidade de medida usada para medir o peso.
Possíveis valores “Grams”, “G”.		stringpackageWeight
packageStatusO status do pacote. Para saber os valores possíveis veja abaixo.stringscheduledPackages
trackingIdO identificador de rastreamento
para o pacote programado.		stringtrackingDetails
amazonOrderIdO identificador do pedido rejeitado.stringrejectedOrders
codeCódigo do erro.
Possíveis valores vejam na lista abaixo.		stringerror
messageMensagem que descreve o erro.stringerror
printableDocumentsUrlUm URL préassinado para o documento zip contendo as
etiquetas de envio e os documentos habilitados par o país.		string-

Para o nó rejectedOrders, esses são os possíveis cenários para um pedido ser rejeitado na hora do agendamento da coleta/emissão da etiqueta de envio.

{
    "code": "InvalidInput",
    "message": "Couldn't find the order details for 951-9026094-1233333"
}

{
    "code": "InternalServerError",
    "message": "We couldn't fetch the available ship methods for  amazon Order Id 951-9026094-1233333"
}

{
    "code": "TimeSlotNotAvailable",
    "message": "We couldn't find an available time slot for Amazon Order Id 951-9026094-1233333"
}

{
    "code" : "InternalServerError",
    "message" : "We couldn't schedule a package for Amazon Order Id 951-9026094-1233333"
}

Esses são os possíveis valores para o campo packageStatus:

  • ReadyForPickup: O pacote está pronto para coleta.

  • ReadyForDropOff: O pacote está pronto para ser entregue pelo seller ao ponto de coleta.

  • PickedUp: A Amazon já coletou o pacote do seller.

  • DroppedOff: O seller ja entregou o pacote para a transportadora.

  • Delivered: O pacote foi entregue ao comprador.

  • Rejected: O pacote foi rejeitado.

  • Undeliverable: O pacote não pode ser entregue.

  • ReturnedToSeller: O pacote não foi entregue ao comprador e foi devolvido ao seller.

  • ReturningToSeller: O pacote não foi entregue ao comprador e está sendo devolvido ao seller.

  • LostInTransit: O pacote está perdido em trânsito.

  • LabelCanceled: A etiqueta do pacote foi cancelada.

  • OutForDelivery: O pacote está fora para entrega.

  • DamagedInTransit: O pacote foi danificado em trânsito.

Extras

Responses http diferentes de 200

Segue a lista de possíveis erros que podem retornar em um http diferente de 200 nas chamadas apresentadas nesse documento:

HTTP codeDescrição
400"Request has missing or invalid parameters and cannot be parsed."
403"Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature."
404The resource specified does not exist.
429The frequency of requests was greater than allowed.
500An unexpected condition occurred that prevented the server from fulfilling the request.
503Temporary overloading or maintenance of the server.

De/Para dos valores do campo “packageStatus” (presente na operação “createScheduledPackageBulk”) com o campo “EasyShipShipmentStatus” (presente na operação de “GetOrders”)

Apesar de estarem com escritas diferentes em alguns casos ambos os campos querem dizer a mesma coisa: qual o status do pacote/pedido DBA.

Abaixo está o de/para dos dois campos. À esquerda os possíveis valores retornados pelo createScheduledPackageBulk no campo packageStatus e à direta os possíveis valores utilizados pelo GetOrder no campo EasyShipShipmentStatus:

packageStatusEasyShipShipmentStatus
NÃO HÁ VALORPendingSchedule
ReturningToSellerReturningToSeller
ReadyForDropOffPendingDropOff
ReadyForPickupPendingPickUp
DroppedOffDroppedOff
PickedUpPickedUp
DeliveredDelivered
RejectedRejectedByBuyer
UndeliverableUndeliverable
ReturnedToSellerReturnedToSeller
LostInTransitLost
LabelCanceledLabelCanceled
DamagedInTransitDamaged
OutForDeliveryOutForDelivery

Como cancelar um pedido DBA

Para cancelar um pedido DBA você pode encaminhar um feed usando a API de FEEDs do tipo "feedType": "POST_ORDER_ACKNOWLEDGEMENT_DATA” com o seguinte XML:

<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
    <Header>
        <DocumentVersion>1.01</DocumentVersion>
        <MerchantIdentifier>AAAAA11A0AA00A</MerchantIdentifier>
    </Header>
    <MessageType>OrderAcknowledgement</MessageType>
    <Message>
        <MessageID>1</MessageID>
        <OrderAcknowledgement>
            <AmazonOrderID>701-1111111-1111111</AmazonOrderID>
            <StatusCode>Failure</StatusCode>
        </OrderAcknowledgement>
    </Message>
</AmazonEnvelope>

Para saber mais sobre como enviar um feed acesse aqui.

❗️

Importante

Garanta de alterar apenas o campo MerchantIdentifier inserindo o seller id do seller em questão e o altere o AmazonOrderID para o identificador no pedido na Amazon que você deseja cancelar.

Updated about 1 year ago