# Copy of Melhores práticas

### Monitore a sua aplicação

#### Você monitora os status HTTP 4XX que a sua aplicação está recebendo? 

Caso receba um retorno HTTP 4XX, é necessário efetuar a requisição novamente e em paralelo analisar o erro para identificar o seu motivo e realizar as devidas correções.

Uma vez efetuada a correção, caso o erro persista, pedimos que entre em contato para que possamos analisar.

#### Você monitora os status HTTP 5XX que a sua aplicação está recebendo? 

Uma vez que o retorno do erro é HTTP 5XX, pedimos que efetue uma nova tentativa, pois o mesmo pode se tratar de uma intermitência.

Caso o erro persista, pedimos que entre em contato para que possamos analisar a causa raiz do erro.

{% hint style="info" %}
Caso necessário entrar em contato com a equipe de suporte ao desenvolvimento de nossa API, basta encaminhar as suas dúvidas para o e-mail *<mark style="color:blue;"><srv.mktp.api@americanas.io></mark>*.
{% endhint %}

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Infraestrutura SkyHub

Nossa infraestrutura está localizada nos servidores da Virginia, caso seus servidores estejam alocados em outra região podemos ter um tempo de resposta acrescido em **200ms**.

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Cuidado com o limite de requisições

Tenha cuidado para não ultrapassar os [limites de requisições](/guias-api-skyhub/limite-de-requisicoes.md) da nossa API. Caso a sua aplicação receba um HTTP 429, ela deve parar de fazer requisições por um tempo até que uma nova janela comece a contar.

{% hint style="danger" %}
Cuidado com datas com um alto volume de vendas, como a **Black Friday**. Acontece do desenvolvedor colocar mais máquinas para ter uma "integração mais rápida" e ser barrado no nosso limite de requisições.
{% endhint %}

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Atualize apenas o necessário

Alguns recursos da API, em especial a de produtos, permitem que apenas alguns campos sejam passados na requisição de atualização.&#x20;

Se deseja atualizar apenas o campo "*qty*" do produto, por exemplo, recomendamos que o faça semelhante à requisição abaixo:

```
curl --request PUT \
  --url https://api.skyhub.com.br/products/{sku}\
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-User-Email: email_de_usuario' \
  --header 'X-Api-Key: token_de_integracao' \
  --header 'X-Accountmanager-Key: token_account_da_plataforma'\
  --data '{"qty":0}'
```

Como podemos observar na requisição acima, é enviada apenas a atualização do estoque, ou seja, não é enviada a estrutura completa do produto.

Desta forma sua aplicação terá que trafegar menos dados na rede, a API terá que processar uma carga menor de dados e haverá um desempenho melhor.

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Atributo de marca

Desde Março/2025 é necessário enviar no corpo do produto o identificador da marca, obtido após uma [**consulta em lista de marcas disponíveis**](/produtos/consultar-marcas.md).

Para que o produto tenha um filtro bem definido por meio de marca, é importante que este atributo seja declarado de forma correta.

<img src="/files/3cSH0iAwTdi1KCLiZaWt" alt="" class="gitbook-drawing">

### Categorização de itens

Desde Março/2025 é necessário categorizar os itens antes de criá-los no Marketplace.

Para isso, foi [**disponibilizada uma consulta**](/produtos/categorizacao/consultar-categorias.md) onde será possível percorrer todas as categorias da Americanas Marketplace e assim enviar no JSON do produto o identificador da categoria desejada.

É uma boa prática o lojista identificar em qual nível de categoria deseja catalogar seus itens e assim enviar no corpo do produto o identificador referente ao nível escolhido.

<img src="/files/RsjjZHi64T4wtEY7ouM9" alt="" class="gitbook-drawing">

### Atributos na SkyHub

Nossa estrutura de criação de atributos não possibilita que trabalhe com a mesma **string** de um atributo com **case sensitive** tentando diferenciar essa criação. Com isso é necessário que sempre utilize em seus produtos o atributo que foi usado pela primeira vez.

\
Por exemplo, se em um primeiro momento foi criado um atributo **teste** (todas as letras em minúsculo) no array de `specifications`, precisamos que todos os seus produtos da conta recebam o atributo como **teste** (todas as letras em minúsculo). Caso em algum momento após a criação, o atributo receba uma grafia diferente - como **Teste** - não será possível indexá-lo ao produto na SkyHub.&#x20;

{% hint style="warning" %}
**IMPORTANTE – Conforme o fluxo de CONTA ÚNICA, onde a conta da loja será a mesma independente da Plataforma/ERP que estiver operando, pode ser que o padrão de um sistema não seja o mesmo de outra, por isso é importante saber que pode haver diferenças e orientar os lojistas de acordo com o atributo da maneira que você utiliza.**
{% endhint %}

{% hint style="info" %}
Ao utilizar o endpoint [*`/attributes`*](/produtos/outros-recursos-de-produtos/endpoint-atributos.md) é possível consultar quais atributos estão criados na conta.
{% endhint %}

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Atributo Garantia

Para o atributo [**Garantia**](/comunicados/comunicados-2021/atributo-garantia-prazo-limite-06-09-21.md) é esperado o valor numérico e essa informação é a representação da garantia do produto em meses, além disso o atributo deve ser criado no array `specifications` do produto na API.

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Limite de Imagens

Existe um limite de imagens a serem enviadas para a API da Americanas.&#x20;

Neste caso o total de imagens por produto passa a ser 20 tanto na estrutura do **produto simples** quanto para as **variações**. Sendo assim, caso tenha uma estrutura de **produto variável** é possível enviar 20 imagens para a variação **SKU A** e 20 imagens para a variação **SKU B**.&#x20;

{% hint style="warning" %}
Caso envie mais de 20 imagens serão consideradas somente as **20 primeiras**.
{% endhint %}

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Consulta de pedidos via API

Temos um limitador de retorno (**GET**) de no máximo 10.000 registros para consulta de pedidos.

Caso tenha mais registros para serem retornados o ideal é realizar filtros para adequar a quantidade de retorno de acordo com o limite existente.

<img src="/files/yaV8ZXMyjqLp3x556rR8" alt="" class="gitbook-drawing">

### Consumo de pedidos

Para <mark style="color:red;">consumir pedidos</mark>, todo o processo deve ser feito pelo endpoint [`/queues/orders`](/pedidos/consumo-de-pedidos-queues.md), para que a SkyHub saiba que o pedido foi integrado.

Embora seja possível listar os pedidos via GET `/orders`, este endpoint como dito deve ser utilizado apenas para listar/consultar e não para consumir.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://desenvolvedores.skyhub.com.br/guias-api-skyhub/melhores-praticas-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.