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 srv.mktp.api@americanas.io.
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 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 desta documentação).
De forma mais detalhada, os passos para a homologação de seu sistema consistem em:
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 );
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;
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;
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 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 srv.mktp.api@americanas.io.
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 srv.mktp.api@americanas.io.
Rehub
Será retornado algum erro ao tentar excluir um produto ainda conectado ao marketplace?
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".
Pedidos
Status 403 ao tentar criar um pedido
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.
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.
Fulfillment
É possível consumir os pedidos Fulfillment separadamente?
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?
Criei os produtos mas eles não aparecem no portal, o que fazer?
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.
Sim, por padrão a API retorna erros para a exclusão de itens que ainda estão ao marketplace Americanas.
Como citado em nossa seção de dúvidas sobre o recurso de , o status 403 é retornado em ações não autorizadas.
Na seção de 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.
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 da seção , onde disponibilizamos os passos para realizar o vínculo de um pedido criado em ambiente de teste com uma etiqueta previamente gerada.
Todos os pedidos gerados no marketplace e disponibilizados pela API serão consumidos sem distinção através da , 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 de nossa seção Fulfillment.
Caso algum produto não tenha sido migrado para o novo portal, significa que ele não foi migrado por conta de alguma pendência cadastral.
Nesta situação, se faz necessário já respeitando as novas exigências.
Após a migração realizada em Março/2025, somente produtos enviados de acordo com o que pedimos em , serão de fato criados.
Dito isso, são dois processos para habilitar um novo produto a venda no Marketplace:
1° - Criação do produto (POST em );
2° - Conexão do produto via API, utilizando a .
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:
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.
