# 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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" 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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" alt="" class="gitbook-drawing">

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

Tenha cuidado para não ultrapassar os [limites de requisições](https://desenvolvedores.skyhub.com.br/guias-api-skyhub/limite-de-requisicoes) 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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" 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 '{
          "product": {
              "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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" 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**](https://desenvolvedores.skyhub.com.br/produtos/consultar-marcas).

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

<img src="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FpP7AKA03OOwJUIY1OZIr%2Ffile.excalidraw.svg?alt=media&#x26;token=fbed60e6-7517-42ce-a02e-fde2bd2f330e" 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**](https://desenvolvedores.skyhub.com.br/produtos/categorizacao/consultar-categorias) 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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FeFkC19JvYJsGR12UPrED%2Ffile.excalidraw.svg?alt=media&#x26;token=cbd2cb38-8303-4976-b040-cf9acdd71e3e" alt="" class="gitbook-drawing">

### Imagens

#### 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 %}

#### Imagens da variação:

Caso no JSON constem imagens no produto pai e nas variações, apenas as imagens das variações serão levadas em conta no Marketplace.&#x20;

Se no JSON as imagens forem enviadas somente no pai, as variações irão assumir as imagens do produto pai.

<img src="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" 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="https://2229754833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LMEDke_zMlYG7Bfov0H%2Fuploads%2FwmJ9m5qDUgnYMEPLIPWY%2Ffile.excalidraw.svg?alt=media&#x26;token=b2f3df4e-679e-4599-878f-d461523ea656" 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`](https://desenvolvedores.skyhub.com.br/pedidos/consumo-de-pedidos-queues), 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.