Melhores práticas

Principais dicas para que você possa desenvolver um fluxo de listagens mais completo para o vendedor, evitando atritos durante o processo.

Listando itens na Amazon: dicas importantes

Tipos de produtos (Product Types)

A Amazon está em processo de migração de Product Types (categorias) para habilitar o uso dessas categorias na API Listing Items e na API Product Type Definitions. Para categorias que ainda não foram lançadas nessa nova API, você somente pode criar novos itens de listagens para ofertas (matching), editar termos de vendas para itens de listagens ou excluir itens de listagens. No entanto, você não pode criar novos itens de listagens com dados do produto (processo de listagem de novo produto) até que a categoria apropriada seja lançado nessas APIs.

Para manter-se atualizado sobre quantas categorias já estão disponíveis nessas novas APIs você pode usar a operação searchDefinitionsProductTypes. Abaixo, veja um exemplo de como consultar a operação searchDefinitionsProductTypes no marketplace do Brasil para saber quantas categorias já estão disponíveis nessa API. Note que no dia 25/11/2022 a busca retornou 816 categorias já migradas.

Exemplo de retorno da operação searchDefinitionsProductTypes para busca de categorias disponíveis para usar API de itens de listagem e na API de definições de tipo de produto no marketaplace do Brasil.

Após chamar a operação acima uma vez você pode automatizar esse processo com a notificação PRODUCT_TYPE_DEFINITIONS_CHANGE. Essa notificação avisará sempre que tiver uma nova categoria migrada ou uma nova versão de alguma categoria já migrada antes.
Consulte o Guia de caso de uso da API de notificações v1 para obter informações sobre como configurar um destino e criar assinaturas.

Inscreva-se nas notificações de listagens

Cada um dos fluxos de trabalho descritos nos guias de listagem pode resultar em alterações de status assíncronas ou problemas em seus skus. Ao assinar e monitorar as notificações LISTINGS_ITEM_STATUS_CHANGE e LISTINGS_ITEM_ISSUES_CHANGE, você tem o poder de criar fluxos de trabalho orientados a eventos que reagem em tempo real à medida que essas alterações ocorrem. Isto é, toda vez que o status de um sku mudar no inventário do vendedor a Amazon enviará a notificação LISTINGS_ITEM_STATUS_CHANGE. Já a notificação LISTINGS_ITEM_ISSUES_CHANGE, será enviada sempre que houver uma alteração nos problemas associados ao sku no inventário do vendedor.

Consulte o Guia de caso de uso da API de notificações v1 para obter informações sobre como configurar um destino e criar assinaturas.

Atualizações parciais vs. completas

Use a operação patchListingsItem para fazer atualizações parciais em uma lista de produtos. A vantagem de usar a operação patchListingsItem é que você só precisa incluir os atributos que estão mudando (e são editáveis, isto é, que estejam como "editable" = false na API de definitions). No entanto, também é possível adicionar, substituir ou excluir atributos usando a operação putListingsItem. Se você optar por usar a operação putListingsItem, deverá preencher previamente o JSON de atualização com a saída do [getListingsItem] (/amazon-portuguese/reference/listagem-listar-itens) para todos os atributos do produto (incluindo atributos não editáveis) para evitar erros de envio. Isso significa essencialmente substituir os dados de atributo de toda a listagem. Por esse motivo, usar a operação putListingsItem é mais adequado para uma atualização completa e a operação patchListingsItem para atualizações parciais.

Por exemplo:
Se você vai atualizar preço e estoque de um sku, recomenda-se que use a operação patchListingsItem enviando somente os dados que deseja atualizar.

PATCH /listings/2020-09-01/items/{sellerId}/{sku}

Operação: patchListingsItem

JSON

{
"productType":"PRODUCT",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/fulfillment_availability",
      "value":[
        {
          "quantity":3,
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "marketplace_id": "A2Q3Y263D00KWC",
          "currency": "BRL",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 5.00
                }
              ]
            }
          ],
        }
      ]
    }
  ]
}

Melhore o desempenho de seus envios

Esteja você enviando dados em massa com o JSON_LISTINGS_FEED, individualmente com a API Listings Items ou uma combinação de ambos, seus tempos gerais de processamento são afetados pelo volume de dados que você envia. O envio repetido de dados duplicados aumenta seus backlogs de processamento desnecessariamente e resulta em tempos de processamento mais longos. Sugerimos que envie no seu JSON de atualização, usando a operação patchListingsItem, somente os campos que estão realmente mudando, assim você usará com mais eficiência a capacidade disponível da API e reduzirá as demoras no processamento. Por exemplo, caso o SKU 123 esteja mudando só o preço, não faz sentido que você envie o preço e todos os demais dados dele, como nome, marca etc. Enviando só o preço você estará informando somente um campo para a Amazon o que agilizará o tempo de processamento da atualização.

Evite contratempos para vendedores grandes e tenha desenvolvido a API de listagem de items e a JSON_LISTINGS_FEED para operarem juntas

A API Listings Items aceita atualizações de listagens uma de cada vez. Para casos de uso mais adequados para uploads em massa, a API de feed JSON_LISTINGS_FEED é a ideal.

O JSON_LISTINGS_FEED é o equivalente em massa da API listagem de items, oferecendo os mesmos recursos e esquemas fornecidos pela API de definitions. Sugerimos que tenha sempre implementado os dois fluxos: o unitário e o em massa.

Por exemplo:
Sabendo que a API de listagem de item tem um limite de requestes de 5 req/segundo isso significa que você pode enviar até 300 requisições por minuto por vendedor e por endpoint (put, patch, delete, etc...). Apesar de ser um número bem grande de requests é importante ter implementado um job para o JSON_LISTINGS_FEED pois caso você tenha uma fila muito grande por vendedor para o uso da API de listing, você pode "desengargalar" ela usando a API de feeds em massa com JSON_LISTINGS_FEED. A API de feeds JSON_LISTINGS_FEED tem um limite de 1 req/min. Com isso em mente, garanta de criar uma fila por vendedor e a cada 5 minutos checar se ela tem mais que 1500 itens acumulados para enviar, se sim, você pode usar a API de feeds JSON_LISTINGS_FEED para enviar isso em massa.

É importante ter isso implementado principalmente para garantir que não haja impacto negativo em períodos de alto pico, como por exemplo, Black Friday que tem um alto número de atualizações de preço, estoque, subida de novas ofertas, etc. Além disso, é importante também para garantir-se em momentos de instabilidade do seu lado os quais podem acabar acumulando essas atualizações em uma fila e ficando tão grande que a API de listagem de items não dará conta de atualizar em um período ideal.

Evite problemas de incompatibilidade (mismatch) - fazer matching com um produto diferente do esperado pelo vendedor

Quando é realizada a consulta para verificar se já existe um produto cadastrado no catálogo da Amazon com base das informações fornecidas pelo vendedor (EAN, título e marca, por exemplo) e é constatado que, sim, já existe, antes de prosseguir com o matching, é importante que seja garantido que o produto que está cadastrado no catálogo da Amazon é realmente o mesmo que o vendedor deseja listar.

Por exemplo: O EAN 7897753670528 está cadastrado no catálogo da Amazon Brasil como um kit de spray e esponjas.
Vamos supor que o vendedor cadastrou esse produto na plataforma do integrador parceiro como sendo somente um spray. Com isso em mente, caso seja realizado o matching direto do produto do vendedor com o que está na Amazon haverá um problema de mismatch já que no catálogo da Amazon ele é um kit e o vendedor não tem a intenção de vender kit, somente spray. O vendedor tenderá a ter problemas nas vendas e poderá até mesmo ter a métrica de cancelamento afetada pois pode ser que ao dar matching acabe vendendo o kit com o valor de um único spray.

Para evitar esse cenário é importante ter um fluxo de prevenção desenvolvido que permita o vendedor dar um "aceito" ou um "não aceito" no produto a ser listado antes de prosseguir com o matching.

Segue o passo a passo de um fluxo sugerido:

• 1 - Consultar os dados na Amazon para ver se já existe um produto cadastrado.
• 2 - Ao indentificar que já existe um produto cadastrado e entender que trata-se de um caso de matching é sugerido que seja exibido em tela para o vendedor os dados do produto dele e os dados desse produto na Amazon (dados indicados: Imagem, título, marca e link do anúncio na Amazon).
• 3 - Com o vendedor ciente em como o produto está cadastrado na Amazon ele pode: (A) Aceitar a criação do SKU dele e realizar o matching ou (B) negar a criação do SKU dele e não realizar o matching e, ainda, caso ele entenda que os dados Amazon estão incorretos, abrir um chamado pelo link pedindo revisão dos dados dos produtos na Amazon.

📘

Subindo um produto por vez ou em massa

Ao criar os produtos e decidir anúnciá-los na Amazon (em massa ou unitariamente) você, desenvolvedor, deve validar quais dos produto são matching e criar uma espécie de relatório e mostrar em uma tela os dados do produto na Amazon versus os dados cadastrados pelo vendedor, para que o vendedor de um "aceito" ou um "não aceito".

Para uma melhor experiência, sugerimos que seja colocado um botão para aceitar todos e uma opção para aceitar ou negar um por um também.

Veja abaixo um exemplo de como poderia ser o fluxo:

Selecionando os produtos criados na plataforma do integrador para anúnciar no marketplace Amazon.

Tela de validação de matching para o vendedor decidir se deseja anunciar os seus produtos com os produtos existentes no catálogo da Amazon.

Importante pontuar que acima é somente um exemplo de tela, você pode colocar mais funcionalidades nessas telas (validação de restrições no matching, produtos com erros, validação se o SKU já existe ou não no catálogo do vendedor, entre outras).

❗️

SÓ ENVIE O PRODUTO DEPOIS QUE O VENDEDOR TIVER DADO UM ACEITE

Garanta que o vendedor aceitou o envio do matching e criação do produto, assim você terá certeza que ele está ciente do produto sendo cadastrado.

📘

Você pode criar códigos de simililaridade

Para automatizar alguns matchings, sem a necessidade de precisar do "aceite" do vendedor em todos, você pode criar algoritmos de similaridade comparando, por exemplo, o título e marca cadastrados na plataforma do integrador com o título e marca cadastrados no catálogo da Amazon. Ao atingir uma certa porcentagem de similaridade você pode realizar o matching automático, já para aqueles com baixa porcentagem você pode simplesmente redirecionar o usuário para a tela de "aceite"/"não aceite" manual, conforme mostrado no exemplo acima.

Garanta que o vendedor saiba desse cenário e esteja de acordo ou não com ter essa funcionalidade de simililaridade acontecendo na conta dele (é sugerida a criação de alguma tag para o vendedor habilitar ou desabilitar essa funcionalidade).