# 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 **. {% endhint %}

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

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

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

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

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

### Imagens #### Limite de imagens Existe um limite de imagens a serem enviadas para a API da Americanas. 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**. {% 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. Se no JSON as imagens forem enviadas somente no pai, as variações irão assumir as imagens do produto pai.

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

### Consumo de pedidos Para consumir pedidos, 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.md?ask= ``` 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.