Perguntas Frequentes

Esta seção traz as perguntas mais frequentes recebidas pelo time de suporte a API

Processo de Homologação

Como é o processo de homologação?

Após solicitar a homologação de seu sistema, serão liberadas pelo time de suporte a integração as credenciais para uma conta de teste e a lista de tarefas (cheklist) que devem ser executadas para a validação dos processos desenvolvidos.

Uma vez que as tarefas forem executadas, as evidências para validação devem ser encaminhadas através de um chamado para o [e-mail].

O time de API irá validar a estrutura das requisições recebidas e qualquer ponto em não conformidade será sinalizado para a correção. Após todos os pontos serem validados e apresentarem as estruturas necessárias para atuação com a API da Americanas, o sistema desenvolvido será liberado para utilização em ambiente de produção.

O que é e como obtenho o header x-accountmanager-key?

O header x-accountmanager-key é o código identificador de seu sistema, ou seja, ele é o código que permite-nos validar qual plataforma está executando requisições para a API da Americanas.

Esse identificador é fornecido exclusivamente para parceiros que solicitam o processo de homologação e deve ser utilizado em todas as requisições via API.

Não sou loja e nem plataforma, posso obter as credenciais?

Não.

Somente aqueles que irão desenvolver uma solução para integrar junto a Americanas Marketplace receberão as credenciais mediante a solicitação.

Não são liberadas credenciais apenas para testes, projetos individuais ou alunos/professores acadêmicos.

Quais são os passos para a homologação?

O processo de homologação com a API da Americanas é simples e consiste na validação das requisições e estrutura dos dados enviados nas tarefas solicitadas em nosso checklist, encaminhado junto às credenciais da conta de teste (para maiores informações, acesse a guia Processo de Homologação desta documentação).

De forma mais detalhada, os passos para a homologação de seu sistema consistem em:

1. Definição do perfil para homologação: É importante compreender qual o perfil do sistema a ser homologado (os perfis podem ser consultados em nossa guia Perfil para Homologação);

2. Criação da conta de teste: Após receber o seu acionamento para início do processo de homologação, nossos times irão criar um ambiente de desenvolvimento para a plataforma/ERP. As credenciais para acesso a conta de teste serão informadas via chamado junto às tarefas que deverão ser executadas;

3. Execução de testes e preenchimento do checklist: Em posse das credenciais da conta de teste, o responsável pelo sistema deverá validar o nosso checklist, que nada mais é do que a lista de tarefas que precisam ser concluídas para que possamos validar o envio de informações para a API;

4. Validação do desenvolvimento: Após a execução e envio das tarefas solicitadas, o time de API da Americanas irá validar as requisições encaminhadas pelo seu sistema.

Preciso solicitar uma conta de teste para cada recurso que será homologado?

Não é necessário solicitar uma conta de teste para cada recurso a ser homologado.

Ao solicitar a homologação de seu sistema será preciso que realize o processo obrigatório, que visa o desenvolvimento e a validação dos recursos básicos da API (produtos, conexão via rehub, pedidos e etiquetas).

No final da homologação básica, a conta de teste fornecida será mantida ativa para que, caso deseje, realize o desenvolvimento e validação (homologação) dos demais recursos disponibilizados pela API.

Um ponto importante é que ao desenvolver um novo recurso é imprescindível que entre em contato com o time de API da Americanas para que a homologação seja validada. Este contato se dá através do e-mail [e-mail].

Quero trabalhar somente atualizando estoque, preciso passar por toda a homologação?

Mesmo que a solução a ser desenvolvida deseje operar somente atualizando estoque, preço, consultando pedidos, ou seja, utilizar somente uma das funcionalidades disponíveis, ela terá que obrigatoriamente passar por todo o processo de homologação.

Hoje as todas as funcionalidades de produto, pedidos, etiquetas e Rehub são obrigatórios para a plataforma ser homologada conosco.

Produtos

Status 401 ou 403 - não autenticado/não autorizado - na criação/atualização de produtos

Um cenário que pode gerar impacto negativo para a integração ocorre quando o seller realiza a inativação de usuários no front da API, porém não atualiza esta informação na plataforma/ERP. Em casos como este é comum as tentativas de envio de requisições para a API – notadas principalmente nos endpoints relacionados aos produtos – retornarem status 401 (não autenticado) ou 403 (não autorizado).

Para correção, é necessário entrar em contato com o seller para validação das credenciais da conta na API, principalmente os e-mails ativos.

Caso as credenciais tenham sido validadas e ainda constem divergências, o time de API deverá ser acionado através de chamado para o e-mail [e-mail].

Estamos enviando atualização de preço/estoque, mas no Marketplace não atualiza. O que fazer?

Aqui estão 3 dicas para solução dessa questão.

1° - Valide se no body da requisição os atributos de preço e/ou estoque estão sendo passados conforme solicitamos (dentro da raiz do 'product'/'variation');

2° - Verifique se o seu produto é simples, ou se possui variações. Para isso, é necessário realizar um GET no produto e validar se no array 'variations' possui algum SKU. Não existindo, trata-se de produto simples, já se existir, trata-se de produto variável;

3° - Utilize o endpoint correto para cada tipo de produto. Se o produto for simples, utilize o '/products', porém se for variável, utilize o '/variations'.

Rehub

Será retornado algum erro ao tentar excluir um produto ainda conectado ao marketplace?

Sim, por padrão a API retorna erros para a exclusão de itens que ainda estão conectados ao marketplace Americanas.

Caso haja uma tentativa de excluir um produto ainda conectado será retornado o status 422 e a mensagem "Produto está conectado. Remova todas as conexões e tente novamente".

Fiz o processo de conexão via Rehub porém o produto não foi criado no Marketplace, o que fazer?

Neste caso, é muito provável que o produto possui alguma pendência cadastral que impediu a sua criação. Alguns motivos para o produto não ser criado:

• Falta de atributos obrigatórios;

• Falta de marca;

• Falta de categoria;

Para saber se houve algum impedimento, é necessário fazer a consulta da carga:

https://desenvolvedores.skyhub.com.br/rehub/resultado-das-acoes-de-produto#consultando-o-resultado-da-acao-pelo-id-da-carga

Pedidos

Status 403 ao tentar criar um pedido

Como citado em nossa seção de dúvidas sobre o recurso de Produtos, o status 403 é retornado em ações não autorizadas.

Em relação a criação de pedidos, o status 403 é comumente visto em casos em que o parceiro realiza tentativas de criar um pedido em uma conta de produção.

Na seção de Criação e Aprovação de Pedido Teste mencionamos que tanto criação quanto aprovação de pedidos são ações exclusivas para as contas de teste, sendo assim, uma conta de produção não permitirá tais tratativas.

Fluxo de status dos pedidos

Para que o pedido seja atualizado corretamente até o ponto de entregue, é necessário que o fluxo de atualização de status seja respeitado. Abaixo o fluxo:

• Pagamento pendente

• Pagamento aprovado

• Pedido faturado

• Pedido enviado

• Pedido entregue

Caso algum status seja pulado, a API retornará erro na transição de status.

Exemplo:

Se uma requisição colocando o pedido para enviado ocorrer primeiro que uma requisição de faturado, ocorrerá o erro citado acima quando a plataforma tentar atualizar a nota fiscal do produto, consequentemente o pedido não terá seu fluxo finalizado no Marketplace.

Estou tomando o erro "TRANSIÇÃO INVÁLIDA: STATUS -> STATUS". Qual o motivo?

O erro de transição inválida ocorre quando se tenta atualizar um pedido que já está atualizado para aquele status da tentativa, ou quando se tentar regredir um status. Por exemplo, um pedido já faturado que a requisição tenta novamente faturar o pedido. Outro exemplo, um pedido já enviado que a requisição tenta voltar para o status de faturado.

Etiquetas

Serão emitidas etiquetas para os pedidos gerados em minha conta de teste?

Para o ambiente de teste as etiquetas são disponibilizadas previamente com dados fixos, desta forma, os pedidos criados em uma conta de teste não possuirão etiquetas com seus dados.

Para realizar todo o fluxo de etiquetas em uma conta de teste - desde a criação do produto até a impressão da etiqueta e solicitação da coleta do pedido - é possível seguir as orientações fornecidas em nosso guia Etiquetas na conta de teste da seção Integração Etiqueta, onde disponibilizamos os passos para realizar o vínculo de um pedido criado em ambiente de teste com uma etiqueta previamente gerada.

Fulfillment

É possível consumir os pedidos Fulfillment separadamente?

Todos os pedidos gerados no marketplace e disponibilizados pela API serão consumidos sem distinção através da /queues/orders, isto é, uma vez que o parceiro (seller) possui o serviço Fulfillment, todos os pedidos desta modalidade serão disponibilizados junto às demais entregas criadas para a loja.

Desta forma, cabe à plataforma/ERP a identificação do tipo do pedido. Caso hajam dúvidas, é possível consultar a guia Identificando Pedido de nossa seção Fulfillment.

Pós-migração

Como o lojista pode obter as credenciais para preencher em nossa plataforma?

O lojista deve entrar no novo portal, realizar login e ir até o Menu Integrações > Credenciais API.

A marca do lojista não aparece na listagem, como criar o produto?

É possível o lojista solicitar a inclusão de determinada marca abrindo chamado diretamente no portal do lojista. Outra opção que pode ser realizada até se ter uma resposta do time de atendimento, é enviar o id da marca referente a opção "Não disponível" que encontra-se na listagem.

Após a migração, alguns produtos não estão no novo portal, como corrigir?

Caso algum produto que existia no antigo portal não esteja no novo após a migração, significa que ele não foi migrado por conta de alguma pendência cadastral. Nesta situação, se faz necessário reenviar os produtos para a Skyhub já respeitando as novas exigências.

Criei os produtos mas eles não aparecem no portal, o que fazer?

Após a migração realizada em Março/2025, somente produtos enviados de acordo com o que pedimos em comunicado enviado aos parceiros, serão de fato criados.

Por isso é importante que a plataforma faça a revisão do que está sendo enviado no body, como o id da marca, id da categoria e os atributos de categoria.

Dito isso, são dois processos para habilitar um novo produto a venda no Marketplace: 1° - Criação do produto (POST em /products);

2° - Conexão do produto via API, utilizando a ação de conectar do Rehub.

A tendência é de que se o produto estiver todo correto, será criado no portal do lojista. Caso não seja, se faz necessário consultar se no resultado da carga algum erro ocorreu: https://desenvolvedores.skyhub.com.br/rehub/resultado-das-acoes-de-produto#consultando-o-resultado-da-acao-pelo-id-da-carga Somente a criação do produto via API não faz com que ele se torne visível no portal do lojista, isto ocorre pois novos produtos ficam em uma base distinta aguardando esta ação de conexão pelo lojista.

O envio do preço ocorre com sucesso (204), porém não é atualizado no Marketplace, o que fazer?

A SkyHub pode retornar sucesso ao receber a atualização de preços, porém pode ocorrer de no momento do envio ao Marketplace ser rejeitado por alguma pendência, onde a mais é comum trata-se de redução maior que 50%. Para consultar se algum produto teve impedimento na atualização de preço, é possível realizar um GET no endpoint abaixo: https://api.skyhub.com.br/sync_errors/products?error_category_code=update_b2w_price