> Integração Produto

Nesta seção mostraremos a trilha para realização da integração de produtos, composta da criação, atualização e exclusão de itens, além de recursos adicionais relacionados

Todo recurso desenvolvido deve ser homologado pelo time responsável pela API da Americanas.

Passos para integração de produtos

Os passos para integração do recurso de produtos são:

1. Criação de itens simples e variáveis;

2. Categorização conforme regras criadas na Americanas Marketplace;

3. Correta inclusão de atributos que não estão definidos em nossa estrutura padrão;

4. Criação de produtos variáveis contendo atributos específicos, como cor, tamanho e voltagem;

5. Atualização de produtos simples e variáveis;

6. Exclusão de SKU.

Todas as tarefas necessárias para a homologação do recurso de produtos podem ser consultadas na guia Validações > Produtos na seção Processo de Homologação.

O que será validado durante o processo de homologação?

O processo de homologação de um recurso tem como objetivo garantir que a plataforma/ERP encontra-se apta para a integração com a API da Americanas. Para este processo serão validados os conteúdos das requisições (method, headers e body), assim como a execução de ações obrigatórias para a integração.

Para o recurso de produtos as validações compreendem os seguintes aspectos:

• Criação: Para a homologação será necessário criar produtos simples e variáveis;

• Atualização: Serão solicitadas atualizações de determinados campos tanto para SKUs simples quanto para variações;

• Exclusão: Para a homologação será validada a exclusão de um item, onde o mesmo deverá se manter deletado e o código SKU não poderá ser reaproveitado.

Visão geral dos tipos de produtos para e-commerce

Para que um produto seja anunciado em sites de e-commerce é necessário conhecer alguns aspectos para escolher a melhor estratégia de anúncio.

De um modo geral existem dois tipos de produtos, simples e variável, conforme a seguir:

1. Produto simples: É aquele composto de um SKU simples sem variações do mesmo item, por exemplo: livros, DVDs e outros;

2. Produto variável: É aquele composto por dois ou mais SKU's, possuindo um atributo diferenciador como voltagem, tamanho, sabor e outros para distinguir as variações do mesmo produto. Atributos de variação são definidos pela Americanas Marketplace, conforme podemos verificar em Consultar Atributos por Categoria.

SKU é a unidade de estoque vendida, a sigla significa Stock Keeping Unit, sendo na prática o ID único de cada produto.

Pré-requisitos para produtos

Pré-requisitos para a integração de produtos em ambiente de teste e produção

Seguir um padrão no cadastro de produtos é uma prática muito importante, então listamos alguns desses requisitos para uma integração bem sucedida com o marketplace.

1. Campos obrigatórios para o envio de itens para a API: Os seguintes campos são obrigatórios na API e o não envio desses atributos implicará em retorno de erro: - SKU; - Título (name); - Descrição (description); - Dimensões (height, width e length); - Peso (weight). É imprescindível a observância dos demais requisitos abaixo para sucesso na integração com o marketplace:

2. Utilize um padrão para a criação dos códigos SKUs: - Utilize uma sequência numérica ou alfanumérica; - Certifique-se que o SKU não possua espaços em branco, normalmente oriundos de cópia direta de editores como Excel e outros; - Não utilize caracteres especiais como barra (/), asterisco (*), vírgula (,), ponto (.), porcentagem (%) e diversos outros, como por exemplo ($, #, (, ), @, !, ¨) e etc. Não podemos mapear todas as tratativas realizadas pelo marketplace ao receber caracteres especiais para o SKU, em alguns casos é possível que haja a troca do SKU por um outro registro e, no pior dos casos, podem haver recusas para a integração do item; - Utilize sempre SKUs exclusivos em todos os produtos: Nunca repita um SKU em outro produto, mesmo que seja de produtos excluídos e mesmo entre produtos simples e variáveis.

3. Informe sempre o peso do produto: - Utilize sempre a unidade de medida em quilograma (Kg), por exemplo, 3.0 para três quilos;

4. Informe sempre as dimensões do produto: - Utilize sempre a unidade de medida em centímetros (Cm), por exemplo, 20.0 para vinte centímetros.

5. Informe ao menos uma imagem por produto: - Um produto sem imagem não pode ser anunciado, portanto, é necessário que seja enviada ao menos uma imagem no produto.

Pré-requisitos para a homologação

Serão desconsiderados, principalmente, os SKUs que apresentaram erros durante o envio da requisição para a API - como, por exemplo, retorno de erro por ausência de um campo obrigatório - ou que apresentarem mais de um método POST, que deve ser utilizado exclusivamente para a criação.

Para a homologação com a API da Americanas também serão validados todos os campos que constituem a estrutura de um produto, sendo:

• SKU (sku): Código único responsável pela identificação do produto e por este motivo não pode ser repetido em outro item;

• Nome (name): Breve título capaz de refletir de forma objetiva a proposta do item (por exemplo: Camiseta branca);

• Descrição (description): A descrição deve conter mais caracteres que o título definido e precisa trazer o detalhamento do produto criado. Neste campo não são aceitas tags HTML (com exceção de <p> e <br> devidamente abertas e fechadas) e expressão regular;

• Status (status): Campo que irá definir se um produto está ativo (enabled) ou inativo (disabled) para a venda;

• Quantidade (qty): Número inteiro que representa o estoque do item;

• Preço (price): Valor de venda do produto;

• Preço promocional (promotional_price): Em ambiente de produção, caso o produto não possua ou deseje não trabalhar com "promotional_price", ele deve ser nulo. Para a homologação, o preenchimento do campo é validado;

• Crossdocking ( crossdocking ): Define o tempo de expedição do produto;

• Custo (cost): Custo do produto para o lojista;

• Peso (weight): Deverá ser considerado com quilograma (kg) e informado como inteiro, por exemplo, 3.0 será considerado três quilos;

• Altura (height): Todas as dimensões deverão ser considerados em centímetro (cm), por exemplo, 20.0 será considerado como 20 centímetros;

• Largura (width): Todas as dimensões deverão ser considerados em centímetro (cm);

• Comprimento (length): Todas as dimensões deverão ser considerados em centímetro (cm);

• Marca (brand): Será validado se o campo foi preenchido como string;

• EAN (ean): Será validado se o campo foi preenchido como string contendo de 13 a 14 números;

• NBM (nbm): Para a homologação será validado se o campo foi preenchido como string contendo de 8 a 10 caracteres;

• Imagens (images): Todas as imagens encaminhadas para a API devem estar no formato https e o servidor não pode ter redirecionamentos;

• Especificações (specifications): Responsável por receber todas as informações adicionais para um produto, como voltagem, tamanho, cor, entre outros atributos disponíveis.

Navegue pelas guias abaixo e acompanhe o detalhamento de cada ação de produto:

Criação de ProdutoAtualização de ProdutoConsulta de ProdutoExclusão de ProdutoOutros Recursos de Produtos