DataFirefly Amazon Connector: ligar o PrestaShop ao Amazon Seller Central

Instalação

Instale o módulo em Módulos > Gestor de módulos > Carregar um módulo, enviando o ficheiro ZIP. É necessária a extensão PHP cURL.

Na instalação, o módulo cria as suas tabelas, um separador Amazon Connector no menu Vender, uma transportadora «Amazon» reservada às encomendas importadas (o cliente nunca a vê) e dois estados de encomenda: «Amazon: a aguardar envio» e «Amazon FBA: enviada».

Preparar a sua conta Amazon

O módulo liga-se à sua conta de vendedor com a sua própria aplicação privada Selling Partner API. Precisa de uma conta profissional no Seller Central.

1. No Seller Central, abra Aplicações e serviços > Desenvolver aplicações e registe-se como programador privado, se ainda não o fez.
2. Crie uma aplicação e peça as funções necessárias às funcionalidades que vai usar: Product Listing e Pricing para o catálogo, Inventory and Order Tracking para as encomendas, Direct-to-Consumer Shipping (Restricted) para receber a morada de entrega e o e-mail do comprador, Amazon Fulfillment para o stock FBA, Finance and Accounting para os reembolsos, Tax Invoicing para o envio de faturas.
3. Autorize a aplicação na sua própria conta para obter um refresh token e anote o ID de cliente LWA e o segredo de cliente.
4. Copie o seu Merchant Token em Definições > Informações da conta.

Ligação e marketplaces

Em Amazon Connector > Definições, escolha a região (Europa, América do Norte ou Extremo Oriente), introduza o cliente LWA, o segredo, o refresh token e o Merchant Token e guarde. Os segredos são cifrados na base de dados; deixe os campos vazios para manter os valores guardados.

No painel, clique em Testar a ligação. Os marketplaces da sua conta aparecem no separador Marketplaces, desativados por predefinição. Para cada um, defina:

• a ativação;
• o idioma dos conteúdos enviados (título, descrição);
• preços com ou sem IVA, conforme o país;
• a sincronização de preços, a desativar se usar um repricer Amazon;
• o acréscimo percentual, o montante fixo e o arredondamento (nenhum, x,99, x,90, inteiro).

Tarefa cron

A sincronização funciona através de uma tarefa cron, idealmente a cada 5 a 15 minutos. O painel mostra o URL protegido por token e o comando de linha de comandos:

php /caminho/para/modules/dfamazonconnector/cron.php --shop=1

Em cada execução, o módulo importa as encomendas, confirma os envios, envia faturas e cancelamentos, lê os reembolsos e o stock FBA e depois envia os anúncios, stocks e preços pendentes em feeds agrupados. Aparece um aviso a vermelho no módulo se a tarefa não correr há mais de uma hora. O botão Novo token invalida o URL anterior.

Correspondência de categorias

A correspondência só é necessária para criar fichas novas na Amazon. Um produto vendido num ASIN existente, ou ligado pelo EAN, só precisa de uma oferta.

No separador Correspondência de categorias, escolha uma categoria PrestaShop e um tipo de produto Amazon (pesquisa por palavras-chave integrada). Um produto usa a correspondência da sua categoria predefinida ou, na falta dela, a da categoria-mãe mais próxima.

• Browse node: o nó de navegação da Amazon, opcional conforme o tipo de produto.
• Tema de variação: por exemplo SIZE_NAME/COLOR_NAME. Se preenchido, as combinações são agrupadas em família; se vazio, cada combinação é publicada como produto independente.
• Atributos das combinações e Características: associam um atributo Amazon a um grupo de atributos ou a uma característica PrestaShop.
• Atributos fixos: valores enviados tal como estão, no formato Listings Items. Variáveis disponíveis: {marketplace_id}, {language_tag}, {currency}, {reference}, {ean13}, {mpn}, {brand}.

O botão Atributos obrigatórios lê o esquema do tipo de produto na Amazon e lista os atributos que o módulo não preenche sozinho. Para cada um, escolha uma origem (valor fixo, característica, atributo de combinação) e depois Aplicar: os campos JSON são preenchidos automaticamente.

Publicar os produtos

A partir da ficha de produto

O separador Módulos da ficha de produto contém um bloco Amazon:

• Vender na Amazon ativa o produto.
• Modo de publicação: automático, oferta num produto existente (ASIN ou EAN) ou criação da ficha completa.
• Expedição: por si (FBM) ou pela Amazon (FBA).
• ASIN, tipo de produto, estado e preço Amazon fixo substituem os valores predefinidos para este produto.
• Atributos adicionais: JSON combinado depois dos atributos fixos da categoria; um valor null remove um atributo.
• Marketplaces: desmarque um país para retirar o produto desse marketplace.

A tabela «O que será enviado para a Amazon» mostra, por combinação e país, o preço, o preço promocional e as suas datas, o preço mínimo, o preço Business e a quantidade. Estão disponíveis quatro ações: Verificar com a Amazon (validação sem publicar, erros mostrados atributo a atributo), Enviar agora, Adicionar à próxima sincronização e Atualizar estado.

Em massa

O separador Produtos lista o catálogo com o estado de cada produto por país (ativo, em curso, inativo, erro). Filtre por nome, categoria ou estado, marque os produtos ou a opção «Todos os produtos que correspondem ao filtro» e aplique uma ação: ativar e publicar, publicar novamente, enviar preços, enviar quantidades, desativar (quantidade 0) ou eliminar da Amazon.

Anúncios já presentes na Amazon

O botão Ligar os anúncios Amazon existentes do painel pede à Amazon o relatório dos seus anúncios. Na execução seguinte do cron, cada SKU é ligado ao produto PrestaShop com o mesmo SKU, a mesma referência ou o mesmo EAN. Os SKU não encontrados ficam listados no registo.

SKU Amazon

O SKU é criado na primeira publicação de acordo com a definição escolhida: referência, EAN13 ou padrão (por predefinição PS{id_product}-{id_product_attribute}). Um SKU existente nunca muda, mesmo que a referência mude.

Preços

O preço é calculado na moeda do marketplace com o grupo de preços escolhido e depois são aplicados o acréscimo, o montante fixo e o arredondamento do país. Opções do separador Definições:

• Aplicar os descontos da loja: preços específicos e regras de catálogo incluídos no preço Amazon.
• Enviar os descontos da loja como preços promocionais Amazon: o preço normal continua a ser o de referência e o desconto torna-se um preço promocional com as datas do desconto PrestaShop. Um desconto criado, alterado ou eliminado atualiza a Amazon de imediato; as promoções com datas e as regras de catálogo são verificadas de novo todas as noites.
• Margem mínima sobre o preço de custo: envia um preço mínimo (preço de custo convertido mais a margem, IVA do país incluído) abaixo do qual um repricer não pode vender.
• Preços Amazon Business: o preço do grupo de clientes escolhido torna-se o preço Business e os seus descontos por quantidade tornam-se escalões (5 no máximo). Apenas para vendedores inscritos no Amazon Business.

As atualizações de preço só afetam as ofertas geridas pelo módulo: uma oferta criada à mão no Seller Central para outro público é mantida.

Stock e FBA

Cada movimento de stock no PrestaShop coloca o SKU na fila de envio. Definições disponíveis: stock de segurança (unidades não disponibilizadas na Amazon), quantidade máxima, tempo de preparação, quantidade 0 para produtos desativados e ressincronização completa todas as noites depois das 3 h.

Os produtos FBA não recebem quantidade do PrestaShop. A opção Ler o stock FBA obtém a cada hora a quantidade disponível nos armazéns Amazon, visível na ficha de produto; Copiar o stock FBA para o PrestaShop aplica-a ao stock da loja dos produtos FBA.

Encomendas

As encomendas são lidas com a API Orders v2026-01-01 a partir da data de início configurada. Uma encomenda a aguardar pagamento é memorizada sem ser criada; é importada logo que a Amazon a liberta para envio.

Cada encomenda importada cria ou reutiliza um cliente convidado (um por comprador ou um cliente único, à escolha), uma morada «Amazon + número da encomenda» e uma encomenda PrestaShop com a transportadora Amazon, os preços e portes da Amazon, o número da encomenda Amazon como identificador de transação e, opcionalmente, a data de compra Amazon. O stock é descontado como numa venda da loja.

As encomendas FBA são importadas depois de enviadas, com o estado «Amazon FBA: enviada». A opção «As encomendas FBA não alteram o stock da loja» repõe as quantidades depois da criação.

O separador Encomendas lista todas as encomendas Amazon com os filtros «A enviar», «Pedidos de cancelamento», «Reembolsadas» e «Não importadas». Uma encomenda não importada (SKU desconhecido, moeda ou país não configurados) mostra a causa e um botão Tentar novamente.

Envios

Escolha nas definições os estados que confirmam o envio (por exemplo Enviado). Quando uma encomenda Amazon passa a um desses estados, o módulo envia à Amazon o código da transportadora, o número de seguimento e a data de envio. Se o número de seguimento ainda não estiver introduzido, aguarda até uma hora antes de confirmar sem seguimento.

A tabela de correspondência de transportadoras associa cada transportadora PrestaShop a um código de transportadora Amazon. As encomendas importadas usam a transportadora Amazon: altere a transportadora da encomenda antes do envio para que seja enviado o código certo. O bloco Amazon da ficha da encomenda tem também um botão Confirmar o envio agora.

Faturas

Se estiver inscrito no serviço de cálculo de IVA da Amazon com a opção de carregar as suas próprias faturas, ative Carregar as faturas PrestaShop na Amazon. Depois da confirmação do envio, a fatura PDF da encomenda é enviada com o seu número, o total e o montante de IVA. O estado (enviada, pendente, rejeitada) aparece na lista e na ficha da encomenda.

Cancelamentos

Quando um comprador pede o cancelamento de uma encomenda não enviada, a encomenda fica assinalada a vermelho na lista e na sua ficha, com o motivo indicado pelo comprador. Não envie: cancele a encomenda a partir do bloco Amazon escolhendo o motivo, ou ative Cancelar na Amazon quando a encomenda é cancelada no PrestaShop. Um cancelamento pedido pelo comprador é enviado com o motivo BuyerCanceled e não penaliza a sua taxa de cancelamento.

No sentido inverso, uma encomenda cancelada na Amazon passa no PrestaShop ao estado de cancelamento escolhido, sem e-mail ao cliente.

Reembolsos

Com a opção Ler os reembolsos Amazon, os reembolsos feitos no Seller Central são lidos através da API Finances. Cada um é anotado na nota privada da encomenda com a data, os artigos e o montante líquido. Quando todas as unidades estão reembolsadas, a encomenda passa ao estado escolhido (Reembolsado por predefinição). O montante mostrado é o montante líquido lançado na sua conta Amazon, após as taxas reembolsadas.

Painel, alertas e registo

O painel mostra os anúncios ativos e com erro, as encomendas das últimas 24 horas e dos últimos 30 dias, as tarefas pendentes, a última sincronização, os erros Amazon mais frequentes agrupados por código e os últimos feeds enviados.

O e-mail de alerta diário é enviado depois das 8 h aos destinatários escolhidos, apenas quando é preciso agir: pedidos de cancelamento, encomendas não confirmadas mais de 2 dias após a compra, encomendas não importadas, faturas rejeitadas, anúncios com erro, feeds rejeitados, cron parado. O botão Enviar um e-mail de teste verifica a configuração.

O separador Registos guarda cada operação (feeds, encomendas, envios, reembolsos, FBA, erros) com o detalhe técnico, filtrável por nível e por canal. O período de conservação define-se nas definições.

Resolução de problemas

O teste de ligação falha

Verifique a região escolhida, o cliente LWA, o segredo e o refresh token. Um refresh token pertence a uma aplicação e a uma conta: gere-o novamente depois de alterar as funções da aplicação.

Um anúncio tem um erro

Abra a ficha de produto: os erros Amazon aparecem por baixo de cada anúncio. O código 90220 indica um atributo obrigatório em falta, a completar na correspondência de categoria ou nos atributos adicionais do produto. Use Verificar com a Amazon para validar a correção antes do envio.

Uma encomenda não é importada

O motivo aparece no separador Encomendas. O caso mais frequente é um SKU Amazon que não corresponde a nenhum produto: ligue os anúncios existentes ou corrija a referência e clique em Tentar novamente. Verifique também se a moeda e o país de entrega estão ativos no PrestaShop.

O stock ou os preços não são atualizados

Verifique a última sincronização no painel e no registo. As atualizações saem na execução seguinte do cron e a Amazon processa-as em poucos minutos. Para forçar um envio completo, use Reenviar todas as quantidades.

Compatibilidade

• PrestaShop 8.0 a 9.x, o mesmo ZIP cobre os dois ramos.
• Multiloja e multilíngue.
• Regiões Amazon Europa, América do Norte e Extremo Oriente.
• Arquitetura ModuleAdminController, sem dependências Composer.
• Interface disponível em francês, inglês, espanhol, alemão, italiano, neerlandês, polaco e português.