Guias de uso
Documentação GlobalDeveloper HubSuporteStatus da API

Guia de uso

Suggest Edits

Introdução

O FBA Classic é o programa de armazenamento e entrega pela Amazon. É através deste programa de FBA que o vendedor consegue o selo Prime (entrega grátis para compradores membros).

Conceitos básicos

  • A gestão de inventário no FBA Classic é feita exclusivamente pelo vendedor (sem utilizar integração) através do Seller Central. Ou seja, o desenvolvedor NÃO deve enviar nenhum feed de estoque para uma oferta FBA Classic. Se o desenvolvedor fizer isso, ele estará duplicando os produtos do vendedor: o produto existirá tanto como uma oferta em FBA Classic quanto uma oferta MFN.

  • As notas fiscais são geradas pela Amazon.

  • Não existe API para importar os XML das notas fiscais das vendas dentro do programa. Caso seja necessário, o seller fará essa etapa manualmente.

  • A gestão do fluxo de pedidos é feita com auxílio das APIs de reports (relatórios) na Amazon.
    O processo consiste em baixar uma lista de Order Ids através das APIs de reports e, uma vez com
    isso em mãos, chamar o getOrders e getOrderItems para importar todos os dados do pedido.

1. Fluxograma

Fluxograma de importação de pedidos

O processo consiste em baixar uma lista de Order Ids através das APIs de reports e, com isso em
mãos, chamar o getOrders e getOrderItems para todos os pedidos da lista.

1366

🚧

Muito importante

  • Fluxo de importação deve rodar num intervalo de 6 em 6 horas (os reports não são atualizados em real time, então não é necessário rodar em intervalos curtos).

  • Para createReport, não coloque um intervalo de datas maior do que 2 ou 3 dias, para evitar erros de geração do arquivo.

  • Uma vez que um pedido venha no report, procure mantê-lo em sua base por 1 mês. OrderIDs mais antigos sairão do relatório, mas é importante mantê-los sua plataforma para fornecer uma boa experiência ao seller

2. Busca de pedidos

🚧

Você deve conceder permissão para o uso do SQS

Essa permissão deve ser feita através do console AWS

É importante subscrever cada seller do programa de FBA Classic na notificação REPORT_PROCESSING_FINISHED. Ao fazer isso, o integrador receberá uma notificação no SQS sempre que o relatório de processamento de pedidos for finalizado.

Criando uma Subscription

Ao chamar esta API, o desenvolvedor está inscrevendo o seller em sua fila no SQS. Inscrevendo-o no notification_type de REPORT_PROCESSING_FINISHED você receberá notificações de criação ou cancelamento de qualquer relatório.

Para chamar esta Endpoint, o desenvolvedor precisa saber qual é o destinationId de sua fila.

🚧

Caso não tenha o destinationId

O destinationId é um campo que o integrador deve ter salvo em banco, caso não tenha um destinationId, verifique a documentação de Notificações.

Segue exemplo de como conseguir este token (que será necessário para chamar a API de createDestination).

Exemplo de chamada

Chamada POST

POST: https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions/REPORT_PROCESSING_FINISHED

Body 

{
   "payloadVersion":"1.0",
   "destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2" //Exemplo de destinationId
}

Exemplo de resposta 

{
   "payload":{
      "subscriptionId":"7fcacc7e-727b-11e9-8848-1681be663d3e",
      "payloadVersion":"1.0",
      "destinationId":"3acafc7e-121b-1329-8ae8-1571be663aa2"
   }
}

Criando um destination

É necessário chamar esta API para criar um destinationId. Com este destinationId, é possível chamar a API de subcription e começar a receber as notificações.

Algumas APIs de Notification são denominadas de Operações Grantless e precisam de um token especial para ser executada.

Exemplo de chamada 

POST: https://sellingpartnerapi-na.amazon.com/notifications/v1/destinations

Body

{
   "name":"YourDestinationName",
   "resourceSpecification":{
      "sqs":{
         "arn":"arn:aws:sqs:us-east-2:444455556666:queue1" //ID da fila
      }
   }
}

Exemplo de resposta 

{
  "payload": {
    "resource": {
      "sqs": {
        "arn": "arn:aws:sqs:us-east-1:112233445566:sp_api_queue"
      },
        "eventBridge": null
    },
      "destinationId": "b48425e5-acec-465d-945a-cabb67bb249a",
      "name": "sp_api_queue"
  }
}

Fluxo de importação de pedidos

Esta API retorna um reportId. Use o valor retornado para chamar getReport na próxima etapa.

Exemplo de chamada 

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports

❗️

Importante

Não coloque um intervalo maior do que 3 dias, pois isso pode gerar erros ao criar o relatório.

Body

//Exemplo marketplace Brasil
{
    "marketplaceIds": [
        "A2Q3Y263D00KWC"
    ],
    "reportType": "GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL",
    "reportOptions": {},
    "dataStartTime": "2021-01-14T05:21:30.960Z",
    "dataEndTime": "2021-01-14T19:05:56.269Z"
}

//----------------------------------------------------//

//Exemplo para vários Markets
{
  "reportType": "GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL",
  "dataStartTime": "2019-12-10T20:11:24.000Z",
  "dataEndTime": "2019-12-10T20:11:24.000Z",
  "marketplaceIds": [
    "A2Q3Y263D00KWC",
    "ATVPDKIKX0DER"
  ]
}

Exemplo de resposta 

{
"reportId": "55939018857"
}

getReport

Ao concluir a etapa anterior, você obteve um reportId. Chame a API de getReport para gerar um
reportDocumentId (este parâmetro será usado posteriormente).

Exemplo de chamada

Chamada GET

GET https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports/{reportId}

Exemplo: https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports/55939018857

Verifique o status do pedido

TiposDescrição
IN_PROGRESSPedido em processamento
DONEPedido concluído
CANCELLEDPedido cancelado

Exemplo de resposta 

{
  "reportType": "GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL ",
  "processingEndTime": "2021-08-18T20:11:51+00:00",
  "processingStatus": "DONE",
  "marketplaceIds": [
    "A2Q3Y263D00KWC"
  ],
  "reportDocumentId": "amzn1.spdoc.1.3.0f4d4dfe-fb81-4dcb-acab-c9a30c9d446c.T2ET7HJ8HQGEHM.107",
  "reportId": "54058018857",
  "dataEndTime": "2021-08-18T00:00:00+00:00",
  "createdTime": "2021-08-18T20:11:33+00:00",
  "processingStartTime": "2021-08-18T20:11:39+00:00",
  "dataStartTime": "2021-08-17T00:00:00+00:00"
}

Lendo a notificação REPORT_PROCESSING_FINISHED

Para saber se o report foi processado ou não, leia suas notificações em banco. Para identificar as notificações prontas, no payload da notificação, filtre por:

reportType: GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL
processingStatus: DONE

Para todas as notificações que tiverem estes parâmetros no payload, salve o valor do campo reportDocumentId e depois, delete essa notificação da fila.

Ao concluir a etapa anterior, você obteve um reportDocumentId. Chame a API de getReportDocument para gerar a url de download do arquivo.

Exemplo de chamada 

GET: https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/documents/{url do report}

Exemplo: https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/documents/amzn1.spdoc.1.3.0f4d4dfe-fb81-4dcbacab-c9a30c9d446c.T2ET7HJ8HQGEHM.107

Exemplo de resposta 

{
  "reportDocumentId": "amzn1.spdoc.1.3.0f4d4dfe-fb81-4dcb-acab-c9a30c9d446c.T2ET7HJ8HQGEHM.107",
  "url": "https://tortuga-prod-na.s3-external-1.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.f09ca40c-10c0-481baf4c-14d910cd25ff.T220M406H2L14T?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210818T201634Z&XAmz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Credential=AKIA5U6MO6RAFBOQNLTF%2F20210818%2Fus-east1%2Fs3%2Faws4_request&X-AmzSignature=55e71645a895f01b9dc7875cf89da6f0031a2bf1b7b19a8399daac9328fcb067"
}

Exemplo de notificação 

{
  "notificationVersion": "2020-09-04",
  "notificationType": "REPORT_PROCESSING_FINISHED",
  "payloadVersion": "1.0",
  "eventTime": "2021-10-06T13:59:49.268Z",
  "payload": {
    "reportProcessingFinishedNotification": {
      "sellerId": "AW4K9WPVX0NIV",
      "reportId": "132246018906",
      "reportType": "GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL",
      "processingStatus": "DONE",
      "reportDocumentId": "amzn1.tortuga.3.e5b9a150-90f4-411f-9f4a-77aba08ff27f.T3FJ42MLJNQ02C"
    }
  },
  "notificationMetadata": {
    "applicationId": "amzn1.sp.solution.f7a0e118-1efa-413a-b8f9-f9ab6be17199",
    "subscriptionId": "ecddb135-c898-4839-a267-fe81e2d80c43",
    "publishTime": "2021-10-06T13:59:49.316Z",
    "notificationId": "4e2fa5b9-c352-498d-a200-3933ed7b8997"
  }
}

3. Baixar relatório

Configurações

Clique na url retornada na API de getReportDocument e baixe o arquivo (separado por tabs). Os pedidos aqui devem ser importados a nível shipmentID: indicamos desta forma pois um mesmo orderID pode servir para shipments FBAOS e FBA Classic. Ou seja, em tela para o seller, deve ser mostrado os pedidos à nível shipmentID.

Importante também mencionar que este relatório traz pedidos FBA Classic e Onsite, por isso, deve
haver um filtro para separar os 2 tipos:

🚧

Importante

  • Para filtrar somente shipments Classic, busque na coluna fulfillment-center-id por somente pedidos cujos 3 primeiros caracteres forem ‘GRU’. Ignore os pedidos que não se enquadrem na regra.

  • Cruze essa lista de pedidos com os pedidos em sua base e, somente continue o fluxo para aqueles pedidos que não haviam sido importados OU que tinham status UNSHIPPED.

  • Os dados de preço, frete, desconto, já podem ser exportados da própria planilha:

  • item-price: traz o preço do produto (NÃO deve ser multiplicado pelo nº de itens)

  • shipping-price: custo do frete (NÃO deve ser multiplicado pelo nº de itens)

  • item-promotion-discount: desconto do produto (NÃO deve ser multiplicado pelo nº de itens)

  • Os campos carrier e tracking-number informam a transportadora e o código de rastreio

Exemplo para filtro e Shipment-id

No exemplo abaixo, considerar somente os pedidos das linhas 2,3,5 e 3 (desconsiderar o pedido da linha 4).

  • Perceba que os itens das linhas 2,3 e 4 são do mesmo OrderID, mas todos com shipmentIDs diferentes. Como o item da linha 4 não deve ser importado, o seller deve ver, para o mesmo orderID, 2 pedidos distintos, identificados pelo shipmentID (linhas 2 e 3).
  • Pedidos com o mesmo OrderID terão endereços de entrega iguais e informações de comprador, também iguais.
668

Chamada getOrders

Exporte esses Ids e rode a API de getOrders.

Exemplo de chamada 

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders?AmazonOrderIds={OrderId},{OrderId}&MarketplaceIds={ID da Loja}
GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders?CreatedAfter=2021-01-01T12-12-12Z&MarketplaceIds=ATVPDKIKX0DER
Exemplo: https://sellingpartnerapi-na.amazon.com/orders/v0/orders?AmazonOrderIds=702-9694551-6023421,702-6936402-3055424&MarketplaceIds=A2Q3Y263D00KWC

Exemplo de chamada para 2 OrderIDs 

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/702-9694551-6023421/orderItems

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/702-6936402-3055424/orderItems

No exemplo abaixo, considerar somente os pedidos das linhas 2 e 3 (desconsiderar os pedidos das linhas 4 e 5).

Exporte esses Ids e rode a API de getOrders.

Exemplo de requests getOrders (somente com 2 orderIds)

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders?AmazonOrderIds=702-9694551-6023421,702-6936402-3055424&MarketplaceIds=A2Q3Y263D00KWC

Updated about 2 years ago