Melhores práticas
Nesta seção é possível verificar as melhores práticas para a execução de requisições e como seguir diante erros retornados pela API
Last updated
Nesta seção é possível verificar as melhores práticas para a execução de requisições e como seguir diante erros retornados pela API
Last updated
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.
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.
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 srv.mktp.api@americanas.io.
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.
Tenha cuidado para não ultrapassar os limites de requisições 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.
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.
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:
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.
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.
Para que o produto tenha um filtro bem definido por meio de marca, é importante que este atributo seja declarado de forma correta.
Desde Março/2025 é necessário categorizar os itens antes de criá-los no Marketplace.
Para isso, foi disponibilizada uma consulta 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.
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.
Caso envie mais de 20 imagens serão consideradas somente as 20 primeiras.
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.
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.
Para consumir pedidos, todo o processo deve ser feito pelo endpoint /queues/orders, 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.
