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

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.

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 [e-mail].

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

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 '{"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.

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.

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.

Ao utilizar o endpoint /attributes é possível consultar quais atributos estão criados na conta.

Atributo Garantia

Para o atributo Garantia é 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.

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.

Caso envie mais de 20 imagens serão consideradas somente as 20 primeiras.

Limite de Categorias

Para a API da Americanas existe um limite de até 10 categorias por produto.

As categorias são informadas na estrutura do produto e não designadas por SKU, ou seja, podemos ter somente 10 categorias por produto cadastrado na SkyHub independente da estrutura ser com ou sem variação.

O endpoint responsável pelas categorias (/categories) foi descontinuado.

Com a sua inativação, as categorias indexadas a um SKU deixam de ser visualizadas na API.

Para maiores informações, consulte a nossa seção de comunicados - Inativação do endpoint /categories.

pageEndpoint Categorias

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