> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/produtos/integracao-produtos.md).

# > Integração Produto

{% hint style="danger" %}
**Todo recurso desenvolvido deve ser** [**homologado**](https://desenvolvedores.skyhub.com.br/processo-de-homologacao) **pelo time responsável pela API da Americanas.**
{% endhint %}

## 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.

{% hint style="info" %}
Todas as tarefas necessárias para a homologação do recurso de produtos podem ser consultadas na guia Validações > [Produtos](https://desenvolvedores.skyhub.com.br/processo-de-homologacao/validacoes/produtos-validacao) na seção Processo de Homologação.
{% endhint %}

### 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](/produtos/criacao-de-produto.md): Para a homologação será necessário criar produtos simples e variáveis;
* [Atualização](/produtos/atualizacao-produto.md): Serão solicitadas atualizações de determinados campos tanto para SKUs simples quanto para variações;
* [Exclusão](/produtos/excluir-produto.md): 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](/produtos/categorizacao/consultar-atributos-por-categoria.md).

{% hint style="info" %}
**SKU** é a unidade de estoque vendida, a sigla significa ***Stock Keeping Unit**,* sendo na prática o ID único de cada produto.
{% endhint %}

### 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;\
   \- <mark style="color:red;">Não utilize caracteres especiais</mark> 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;\
   \- <mark style="color:red;">**Utilize sempre SKUs exclusivos em todos os produtos:**</mark> <mark style="color:red;">Nunca repita um SKU em outro produto, mesmo que seja de produtos excluídos e mesmo entre produtos simples e variáveis</mark>.<br>
3. **Informe sempre o peso do produto:**\
   \- Utilize sempre a unidade de medida em **quilograma (Kg)**, por exemplo, 3.0 para três quilos;<br>
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.<br>
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.

   &#x20;

### 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.&#x20;

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;&#x20;
* **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:

{% content-ref url="/pages/-MG4Gis5UfYeVHsMwz1j" %}
[Criação de Produto](/produtos/criacao-de-produto.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MG4KKKK7iO8kF9S7J30" %}
[Atualização de Produto](/produtos/atualizacao-produto.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MGPs\_Se8fX9P-Bng5q3" %}
[Consulta de Produto](/produtos/consulta-produto.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MG4JxT8yc3BFw4grZQU" %}
[Exclusão de Produto](/produtos/excluir-produto.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MG4Glj0PPvakqUVOzYu" %}
[Outros Recursos de Produtos](/produtos/outros-recursos-de-produtos.md)
{% endcontent-ref %}