Novo Listing Amazon

Este artigo interno explica o funcionamento do Novo Listing Amazon no ANYMARKET, incluindo mudanças no vínculo de categorias, vínculo de variações por categoria, valores de variação, uso do schema do productType e criação de produtos pela Listings API da Amazon.

No novo fluxo, a criação de produtos na Amazon passa a utilizar a API de listing mais recente, com envio em JSON, validações baseadas no schema do productType e etapas adicionais para reduzir erros de publicação.

Neste artigo:

• Pré-requisitos
• Como funciona o Novo Listing Amazon
• Passo a passo do fluxo de categorias, variações e criação de produtos
• Boas práticas
• Dúvidas comuns

Pré-requisitos

Antes de analisar ou operar o novo fluxo de listing da Amazon, valide se:

• A integração Amazon está configurada corretamente no ANYMARKET;
• O produto possui EAN informado, quando aplicável;
• A categoria do produto está vinculada à categoria Amazon correspondente;
• As variações e os valores de variação foram vinculados conforme a categoria;
• Os atributos obrigatórios e condicionais do schema do productType foram preenchidos;
• Há acesso ao Kibana para consulta de logs no OUTPUT e LOGSTASH, quando necessário.

Como funciona o Novo Listing Amazon

Quando um produto é enviado para a Amazon, o ANYMARKET realiza uma chamada informando o EAN do produto para verificar se já existe algum item no catálogo da Amazon com esse EAN.

• Se já existir produto cadastrado para o EAN, o seller deve seguir com o fluxo de Match;
• Se não existir produto cadastrado para o EAN, o item poderá seguir como novo produto, ou seja, New ASIN.

Com o novo listing, os vínculos de categoria, variação e valores de variação passam a ser orientados pelo schema da Amazon, que define os campos obrigatórios, combinações possíveis de variação e validações necessárias para cada productType.

Passo a passo do fluxo de categorias, variações e criação de produtos

1. Vínculo de categorias

Fluxo antigo

No fluxo antigo, as categorias, productTypes e RBNs da Amazon eram consultados manualmente e cadastrados no ANYMARKET. Em alguns casos, era necessário criar atividades de Serviço Fábrica para inserir novos productTypes ou RBNs.

A lista de categorias era atualizada automaticamente uma vez ao mês, e o seller precisava selecionar o RBN para concluir o vínculo de categorias.

Novo fluxo

No novo listing, a consulta de categorias, productTypes e RBNs passa a ser automática. O ANYMARKET busca a árvore de categorias disponível na Amazon por meio do report GET_XML_BROWSE_TREE_DATA e carrega essa lista para que o seller realize a vinculação de categorias.

Outro ponto importante é que o RBN passa a ser selecionado automaticamente pelo ANYMARKET, de acordo com a seleção feita na árvore de categorias.

Para apoiar o seller, o ANYMARKET disponibiliza o artigo da funcionalidade diretamente no painel:

Como cadastrar e vincular categorias

Ponto de atenção: para categorias que já estavam vinculadas e cujo RBN continua ativo na Amazon, a migração foi realizada automaticamente, sem necessidade de novo vínculo.

Como a lista de categorias é buscada periodicamente na Amazon, algumas categorias e RBNs podem ser descontinuados. Quando isso ocorre, o vínculo antigo fica obsoleto, sendo necessário realizar o vínculo de categoria novamente.

2. Vínculo de variações

Fluxo antigo

No fluxo antigo da Amazon, o vínculo de variação era realizado de forma geral. Era possível vincular uma variação do ANYMARKET a uma variação da Amazon, como Tamanho no ANYMARKET com Tamanho na Amazon, independentemente da categoria.

Novo fluxo

No novo fluxo de listing da Amazon, o vínculo de variação passa a ser realizado por categoria. Dessa forma, uma variação do ANYMARKET precisa ser vinculada à variação específica daquela categoria na Amazon.

Exemplo:

• A variação Tamanho do ANYMARKET deve ser vinculada ao Tamanho de Camiseta na categoria de camisetas;
• A mesma variação Tamanho deve ser vinculada ao Tamanho do Tênis na categoria de tênis.

Esse vínculo deixa de ser realizado no menu:

Cadastro > Tipos de variação

E passa a ser realizado em:

Cadastro > Categorias > Vincular categorias > Vincular Variação

Para entender mais sobre essa funcionalidade, acesse:

Amazon: vínculo de variação por categoria

Exemplo real: categoria de camisetas

No Seller Central da Amazon, a categoria de camisetas apresenta as variações disponíveis para o productType SHIRT. No ANYMARKET, a nova experiência apresenta as opções de variação disponíveis para vínculo nessa mesma categoria.

Exemplo real: categoria de tênis

3. Dependência de variações

O fluxo de vínculo de variação segue o mesmo padrão do cadastro de produtos no Seller Central da Amazon. Ao informar que o produto possui variação, pode ser necessário escolher um nível adicional de variação para completar a estrutura do produto.

No exemplo da categoria de camisetas, productType SHIRT, ao informar que o produto terá variação de tamanho, a Amazon exige que seja selecionado um segundo nível de variação, conforme as opções disponíveis para essa categoria.

No ANYMARKET, após o vínculo da variação, são apresentadas as opções requeridas para compor a estrutura de variação do produto.

Na Amazon, ao selecionar a segunda opção para completar a estrutura do produto, as demais opções passam a ser opcionais ou deixam de permitir seleção.

No ANYMARKET, essa experiência ainda não foi totalmente reproduzida. Por isso, as demais variações podem continuar sendo apresentadas como Requeridas. O fluxo está em análise para otimização futura.

Para identificar quais estruturas de variação estão disponíveis para um produto, o ANYMARKET utiliza o atributo VARIATION_THEME, disponibilizado pela Amazon no schema do productType. Esse atributo lista as possíveis combinações de variação para a categoria.

4. Vínculo dos valores de variação

Após realizar o vínculo de variação, é necessário fazer o vínculo dos valores disponíveis para essa variação.

Neste passo, o ANYMARKET segue a mesma experiência da Amazon. Para cada variação, existem atributos necessários para o vínculo de valor.

Exemplo: para vincular valores da variação Tamanho de Camisa, inicialmente são exigidos atributos como:

• Sistema de tamanho - Partes superiores;
• Classe de tamanho - Partes superiores.

Na Amazon, conforme os atributos são preenchidos, novos campos obrigatórios podem ser apresentados. Esses campos são chamados de atributos condicionais.

No ANYMARKET, ainda não há a experiência de exibir atributos condicionais progressivamente conforme a seleção dos campos anteriores. Por isso, todos os campos são apresentados em tela, sendo recomendado o preenchimento.

Caso a combinação dos valores preenchidos não seja compatível com os valores esperados pela Amazon, será apresentada uma mensagem de erro indicando inconsistência no campo.

Exemplo: o produto com Valor do tamanho - Partes superiores igual a 4 Meses pode ser incompatível com Classe de tamanho - Partes superiores igual a numérico.

No Seller Central da Amazon, os campos são apresentados de acordo com a opção selecionada anteriormente.

Após o preenchimento dos valores de variação, eles serão apresentados na tela abaixo:

Assim como no Seller Central da Amazon, é necessário preencher os valores de variação para cada valor cadastrado. Exemplo: ao preencher os campos para a variação tamanho 25, será necessário preencher novamente para a variação tamanho 26.

A vantagem no ANYMARKET é que esse vínculo é feito para a variação dentro da categoria. Assim, todos os produtos com tamanho 25 daquela categoria já estarão contemplados.

5. Criação de produtos

A criação de produtos na Amazon foi reescrita e passou a utilizar a API de listing mais recente da Amazon, com envio em JSON.

Schema para o productType

Após consultar a árvore de categorias e productTypes da Amazon, o ANYMARKET consulta o Schema do productType. O schema é um JSON com a normalização de cada tipo de produto, contendo:

• Campos obrigatórios;
• Combinações possíveis de variação, como variation_theme;
• Valores de variação e suas regras de preenchimento;
• Tipos aceitos para cada atributo.

Com base no schema da Amazon, o ANYMARKET mapeia os atributos obrigatórios para exibição nas telas de características do produto, variações e valores de variação.

Documentação de apoio da Amazon:

Caso de uso: definições de tipo de produto

O log da consulta do schema fica disponível no OUTPUT do Kibana. Exemplo de URL de consulta:

https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/SHIRT?sellerId=A3JIYPUOCASNBZ&productTypeVersion=LATEST&requirements=listing&requirementsEnforced=enforced&locale=pt_BR&marketplaceIds=A2Q3Y263D00KWC

No responseBody da consulta, é retornada uma URL com o schema. Essa URL é válida por pouco tempo, por isso o ANYMARKET coleta o conteúdo e salva a informação em um banco de dados não relacional.

Etapas para criação de um produto na Amazon

A criação do produto na Amazon passa pelas seguintes validações:

1. Validação do vínculo de categoria;
2. Vínculo das variações;
3. Vínculo dos valores de variação;
4. Validação dos atributos obrigatórios para a categoria/productType;
5. Validação interna do produto, cruzando o JSON do produto com o schema do productType;
6. Validação no VALIDATION_PREVIEW da Amazon;
7. Cadastro do produto na Amazon.

Validação de vínculos

Com base no schema da categoria/productType, o ANYMARKET valida os campos obrigatórios logo ao criar a transmissão.

Essa validação pode incluir atributos como:

• Título;
• Marca;
• EAN;
• Pontos de destaque, ou bullet points;
• Demais campos retornados no schema.

Validação interna do produto

Após validar os campos obrigatórios do schema, o ANYMARKET constrói o JSON do produto com todos os campos preenchidos e executa uma validação interna cruzando o JSON do produto com o schema.

Essa ferramenta retorna se existem atributos condicionais não preenchidos ou atributos faltantes. Nem todos os atributos condicionais aparecem como obrigatórios no schema antes dessa etapa, por isso alguns erros só são identificados nesse momento.

Para validar se o produto foi enviado para a ferramenta de validação, pesquise no LOGSTASH do Kibana por:

"Validando atributos para o productType" AND "EAN do PRODUTO"

Exemplo de mensagem apresentada na transmissão:

Ocorreu um erro ao criar anúncio com sku 1,121 na Amazon.
external_testing_certification: is missing but it is required |
is_assembly_required: is missing but it is required |
required_product_compliance_certificate: is missing but it is required |
color: is missing but it is required |
power_source_type: is missing but it is required |
batteries_included: is missing but it is required

Para preencher esses atributos, acesse o cadastro do produto e, na aba Características, informe os atributos faltantes.

Os atributos destacados com * são obrigatórios no schema. Os atributos condicionais podem não aparecer destacados.

Validação no VALIDATION_PREVIEW

Após o preenchimento dos atributos obrigatórios e a validação interna, o ANYMARKET realiza uma nova validação enviando o JSON para o mesmo endpoint de criação de produto, porém com o parâmetro:

mode=VALIDATION_PREVIEW

A Amazon valida se os atributos estão preenchidos corretamente e realiza validações adicionais, como isenção de EAN e autorização para publicação.

O log dessa chamada e as mensagens de validação ficam disponíveis no OUTPUT do Kibana. Exemplo:

https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AYV01WSGEPBGV/9136?issueLocale=pt_BR&mode=VALIDATION_PREVIEW&marketplaceIds=A2Q3Y263D00KWC

Caso seja retornado erro, ele será apresentado na transmissão.

Cadastro do produto na Amazon

Após passar pelas validações anteriores, o produto é enviado para a Amazon com maior chance de aceite.

O envio é feito por uma chamada PUT no endpoint de Listings API:

https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/A326BVZ4TY8H5C/35201?issueLocale=pt_BR&marketplaceIds=A2Q3Y263D00KWC

Para criação de novos produtos, o ANYMARKET envia o PUT com parâmetros como:

"productType": "COMPUTER"
"requirements": "LISTING"

O termo LISTING indica para a Amazon que se trata de um novo produto. Para produtos em fluxo de match, é utilizado LISTING_OFFER_ONLY.

Após o envio, a Amazon retorna erro ou sucesso de forma síncrona no response da chamada.

Exemplo de sucesso:

{
  "sku": "35201",
  "status": "ACCEPTED",
  "submissionId": "6d3b3f3c6b2c4e529d27d024834e0a53",
  "issues": []
}

Exemplo de falha:

{
  "sku": "55119",
  "status": "INVALID",
  "submissionId": "549beed9c6a5433ca4892ea6aedb6f75",
  "issues": [
    {
      "code": "90244",
      "message": "Valor enumerado inválido para o atributo merchant_shipping_group.",
      "severity": "ERROR",
      "attributeNames": [
        "merchant_shipping_group"
      ],
      "categories": [
        "INVALID_ATTRIBUTE"
      ]
    }
  ]
}

Após o produto ser aceito, ainda é possível receber erro assíncrono. Nesse caso, a Amazon notificará o ANYMARKET pela mensagem LISTINGS_ITEM_ISSUES_CHANGE. O recebimento dessa mensagem fica no LOGSTASH do Kibana.

6. Cadastro de produtos com variação

A criação de produtos com variação também passa a ser feita via JSON. É necessário enviar uma estrutura específica de atributos para indicar produto pai e produtos filhos.

Documentação de apoio:

Guia de criação e gerenciamento de listagens - família de variação

Atributos principais para família de variação

Exemplo de parentage_level para produto pai:

"parentage_level": [
  {
    "marketplace_id": "A2Q3Y263D00KWC",
    "value": "parent"
  }
]

Exemplo de parentage_level para produto filho:

"parentage_level": [
  {
    "marketplace_id": "A2Q3Y263D00KWC",
    "value": "child"
  }
]

Exemplo de relacionamento para produto pai:

"child_parent_sku_relationship": [
  {
    "marketplace_id": "A2Q3Y263D00KWC",
    "child_relationship_type": "variation"
  }
]

Exemplo de relacionamento para produto filho:

"child_parent_sku_relationship": [
  {
    "marketplace_id": "A2Q3Y263D00KWC",
    "child_relationship_type": "variation",
    "parent_sku": "parent_SKU_123"
  }
]

Exemplo de variation_theme para productType SHIRT, com variação por cor e tamanho:

"variation_theme": [
  {
    "name": "COLOR_NAME/SIZE_NAME"
  }
]

Os valores possíveis para variation_theme são retornados no schema do productType.

Produto pai

Para criar um produto pai, são enviados atributos como:

• parentage_level: parent;
• child_parent_sku_relationship: variation;
• fulfillment_availability: estoque zero, pois o produto pai não possui estoque.

Observação: no conteúdo original havia um exemplo de JSON com value: child em uma seção que descrevia produto pai. Recomenda-se revisar esse trecho técnico antes de publicação final para evitar inconsistência entre descrição e payload.

Produto filho

Para criar produtos filhos, são enviados atributos como:

• parentage_level: child;
• child_parent_sku_relationship: SKU do produto pai criado na chamada anterior;
• parent_sku: por padrão, o ANYMARKET envia ANY-PARENT-idProdutoANY;
• fulfillment_availability: estoque disponível para o SKU;
• purchasable_offer: valor de venda do SKU.

Boas práticas

• Valide se o produto deve seguir como Match ou New ASIN antes da publicação.
• Refaça o vínculo de categoria quando a categoria ou o RBN antigo tiver sido descontinuado pela Amazon.
• Realize o vínculo de variação por categoria, não mais de forma global.
• Preencha os valores de variação para cada valor necessário dentro da categoria.
• Consulte o schema do productType para entender os campos obrigatórios, tipos aceitos e temas de variação.
• Preencha também atributos condicionais, mesmo quando eles não estiverem destacados com asterisco na tela.
• Use o Kibana para validar chamadas de schema, validação interna, VALIDATION_PREVIEW, criação do produto e erros assíncronos.
• Em produtos com variação, revise cuidadosamente os atributos parentage_level, child_parent_sku_relationship e variation_theme.

Dúvidas comuns

O que mudou no Novo Listing Amazon?
A criação de produtos foi reescrita para utilizar a API de listing mais recente da Amazon, com envio em JSON, validações por schema e novas regras para categorias, variações e valores de variação.

Como o ANYMARKET decide entre Match e New ASIN?
O ANYMARKET consulta a Amazon usando o EAN do produto. Se já existir item no catálogo para esse EAN, o seller deve seguir como Match. Caso contrário, o produto pode seguir como New ASIN.

O que mudou no vínculo de categorias?
O ANYMARKET passa a buscar automaticamente a árvore de categorias da Amazon pelo report GET_XML_BROWSE_TREE_DATA, e o RBN passa a ser selecionado automaticamente conforme a categoria escolhida.

Preciso refazer todos os vínculos de categoria?
Não. Categorias já vinculadas foram migradas quando o RBN continuava ativo na Amazon. Se a categoria ou RBN foi descontinuado, será necessário refazer o vínculo.

O que mudou no vínculo de variação?
O vínculo passou a ser feito por categoria. A mesma variação do ANYMARKET pode precisar ser vinculada de formas diferentes conforme a categoria Amazon.

Onde faço o vínculo de variação agora?
Em Cadastro > Categorias > Vincular categorias > Vincular Variação.

Por que preciso preencher valores de variação?
Porque a Amazon exige atributos específicos para cada valor de variação, como sistema de tamanho e classe de tamanho, dependendo da categoria e do productType.

O que são atributos condicionais?
São atributos que passam a ser exigidos conforme o preenchimento de outros campos. No ANYMARKET, eles podem aparecer em tela mesmo sem destaque de obrigatoriedade.

O que é o schema do productType?
É um JSON da Amazon que define os atributos obrigatórios, tipos aceitos, temas de variação e regras de preenchimento para um tipo de produto.

Onde encontro o log da consulta do schema?
No OUTPUT do Kibana, pesquisando pela URL de definitions da Amazon correspondente ao productType.

O que é VALIDATION_PREVIEW?
É uma validação feita pela Amazon antes da criação efetiva do produto, usando o parâmetro mode=VALIDATION_PREVIEW no endpoint de listing.

Qual a diferença entre LISTING e LISTING_OFFER_ONLY?
LISTING indica criação de novo produto. LISTING_OFFER_ONLY é utilizado para produtos em fluxo de Match.

Como são tratados erros assíncronos após o aceite do produto?
A Amazon pode enviar notificações LISTINGS_ITEM_ISSUES_CHANGE, que são registradas no LOGSTASH do Kibana e informadas na transmissão.

Quais atributos são importantes para produto com variação?
Os principais são parentage_level, child_parent_sku_relationship e variation_theme.

Em caso de dúvidas sobre o Novo Listing Amazon no ANYMARKET, acione o time responsável pela integração Amazon ou consulte os logs no Kibana para validar categorias, schema, transmissão e retorno da Amazon.