# Sync Etsy para PrestaShop: documentação > O Sync Etsy liga a sua loja PrestaShop à sua loja Etsy: exporta os seus produtos para listings, sincroniza os stocks e importa automaticamente as encomendas Etsy para o PrestaShop.… - Página: - Idioma: pt - Atualizado em: 2026-09-09 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/sync-etsy-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/sync-etsy-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/sync-etsy-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/sync-etsy-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/sync-etsy-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/sync-etsy-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/sync-etsy-prestashop/index.md) - Índice: O Sync Etsy liga a sua loja PrestaShop à sua loja Etsy: exporta os seus produtos para listings, sincroniza os stocks e importa automaticamente as encomendas Etsy para o PrestaShop. Este guia cobre a instalação, a ligação à Etsy, as definições e o funcionamento no dia a dia. Compatível com PrestaShop 8.0 a 9.x, multiloja. O módulo usa a API oficial Etsy Open v3 e uma ligação OAuth 2.0 (com PKCE): nunca introduz a sua palavra-passe da Etsy no PrestaShop. ## Pré-requisitos - Uma loja PrestaShop 8 ou 9 a funcionar, com acesso ao back-office. - Uma loja Etsy ativa. - Uma aplicação registada no portal de programadores da Etsy (gratuita), ver o passo seguinte. - Um cron no servidor (ou um serviço de cron externo) para automatizar a sincronização dos stocks e a importação das encomendas. ## Instalação 1. No back-office do PrestaShop, vá a **Módulos > Gestor de módulos**. 2. Clique em **Carregar um módulo** e coloque o ficheiro `dfetsy.zip`. 3. Depois de instalado, clique em **Configurar**. Chega à página de administração do módulo, organizada em separadores: Ligação, Produtos, Encomendas, Definições, Cron e Registos. ## Criar a sua aplicação Etsy O módulo liga-se à Etsy através da sua própria aplicação de programador. O procedimento é gratuito e demora poucos minutos. 1. Vá ao portal de programadores da Etsy (etsy.com/developers) e crie uma nova aplicação. 2. A Etsy fornece-lhe uma chave de API, chamada **keystring** (é o seu Client ID). 3. Na configuração da sua aplicação Etsy, declare o **URL de redirecionamento** (Callback URL) exatamente como é apresentado no separador **Ligação** do módulo. O URL de redirecionamento tem de ser copiado tal e qual. Qualquer diferença (http ou https, presença ou ausência de barra final) faz falhar a ligação OAuth. ## Ligação à Etsy No separador **Ligação**: 1. Cole a sua **keystring** no campo previsto e clique em **Gravar**. 2. Clique em **Ligar a minha loja Etsy**. Abre-se um separador da Etsy que lhe pede para autorizar a aplicação. 3. Depois da autorização, é reencaminhado para uma página de confirmação. Volte ao back-office e recarregue a página: a faixa deve mostrar **Ligado**, com o nome e o identificador da sua loja. 4. Use o botão **Testar a ligação** para confirmar que está tudo a funcionar. O token de acesso é renovado automaticamente pelo módulo. O botão **Desligar** elimina os tokens e a associação à loja. ## Definições O separador **Definições** reúne o comportamento de sincronização e os atributos Etsy predefinidos. ### Sincronização - **Enviar os stocks do PS para a Etsy**: cada alteração de quantidade entra numa fila de espera e é enviada na próxima passagem do cron. - **Atualizar o listing a cada gravação do produto**: reexporta automaticamente o listing quando altera um produto associado. - **Importar as encomendas Etsy**: ativa a importação automática das encomendas pagas. - **Enviar as imagens do produto**: junta as imagens do produto ao listing na exportação. - **Sincronizar os preços**: envia o preço do PrestaShop para a Etsy. - **Majoração do preço na Etsy (%)**: aplica uma percentagem ao preço exportado, para absorver as comissões da Etsy, sem mexer no preço do PrestaShop. - **Idioma de exportação**: idioma usado no título e na descrição dos listings. A Etsy é um mercado maioritariamente anglófono. Se vende sobretudo para fora de Portugal, escolha o inglês como idioma de exportação e mantenha o português na sua loja PrestaShop: os dois catálogos podem ter idiomas diferentes sem qualquer problema. ### Atributos Etsy predefinidos - **Quem o fez / Quando**: valores obrigatórios da Etsy (who_made / when_made) aplicados aos novos listings. - **Taxonomy ID**: categoria Etsy predefinida dos listings (consulte a Seller Taxonomy da Etsy). - **Perfil de envio** e **Política de devoluções**: listas carregadas automaticamente a partir da sua loja Etsy, depois de ligada. - **Estado do listing na exportação**: _Rascunho_ (recomendado, para rever antes de publicar) ou _Ativo_ (publicação imediata, com as taxas de colocação da Etsy a aplicarem-se). ### Importação das encomendas - **Estado de encomenda**: estado do PrestaShop atribuído às encomendas importadas. - **Transportadora**: transportadora associada por predefinição. - **Enviar os e-mails do PrestaShop na importação**: desativado por predefinição, porque a Etsy já notifica o comprador. Na maioria dos casos, deve ficar desativado. ## Exportar produtos para a Etsy No separador **Produtos**, procure um artigo por nome, referência ou identificador. - **Exportar para a Etsy** cria um listing com o título, a descrição, as etiquetas, as imagens e o preço do produto. O listing é criado em rascunho (ou ativo, conforme as suas definições) e o inventário (SKU, preço, quantidade) é depois enviado. - **Atualizar** reenvia as informações para um listing já associado. - **Associar (listing ID)** liga manualmente um produto do PrestaShop a um listing Etsy existente, introduzindo o identificador do listing. - **Desassociar** elimina a associação (o listing da Etsy não é eliminado). Na versão 1.0, um produto é exportado com referência única: são usados a quantidade total e o preço de base. Os produtos com combinações são, por isso, geridos em SKU único. As variações nativas da Etsy estão previstas para uma versão posterior. ## Sincronização dos stocks Quando a quantidade de um produto associado muda no PrestaShop, é acrescentado um trabalho de sincronização a uma fila de espera desduplicada. Não é feita qualquer chamada à Etsy durante a navegação: a fila é tratada pelo cron, o que evita atrasos no front-office e no back-office. Também pode acionar o tratamento manualmente, a partir do separador **Cron**. ## Importação das encomendas As encomendas Etsy pagas são importadas como encomendas do PrestaShop: - É criado um cliente convidado (ou reutilizado, se já existir para esse e-mail). - A morada de entrega da Etsy é retomada. Se o país não for reconhecido, a encomenda é ignorada e aparece uma mensagem nos registos. - O preço pago é aplicado ao cêntimo: o total da encomenda no PrestaShop corresponde ao montante pago na Etsy. - A nota deixada pelo comprador é anexada como mensagem no fio de apoio ao cliente da encomenda. - Um mecanismo anti-duplicação por identificador de encomenda Etsy (receipt) evita qualquer importação repetida. Uma encomenda Etsy relativa a um listing não associado a um produto do PrestaShop é ignorada (é escrito um aviso nos registos). Confirme que os produtos vendidos na Etsy estão mesmo associados do lado do PrestaShop. As encomendas importadas são um registo operacional, não um documento fiscal. Numa loja portuguesa, a fatura relativa a uma venda na Etsy tem de ser emitida pelo seu software de faturação certificado pela AT e comunicada nos termos aplicáveis. Confirme com o seu contabilista certificado como tratar estas vendas, incluindo o IVA e o eventual regime de vendas à distância intracomunitárias (OSS), consoante o país do comprador. ## Configurar o cron O separador **Cron** mostra um URL protegido por um token. Chame-o a cada 5 a 15 minutos para tratar a fila de espera (stocks e produtos) e importar as novas encomendas. ``` */10 * * * * curl -s "https://a-sua-loja/index.php?fc=module&module=dfetsy&controller=cron&token=O_SEU_TOKEN" > /dev/null ``` O botão **Executar a fila de espera agora** permite lançar um tratamento manual, para testar. Sem passagens regulares do cron durante várias semanas, o token de renovação da Etsy pode expirar. Basta uma nova ligação a partir do separador Ligação para o regenerar. ## Registos e diagnóstico O separador **Registos** mostra o histórico de eventos (exportação, stock, importação, erros). Em caso de problema numa sincronização, consulte-o em primeiro lugar: cada erro devolvido pela Etsy fica aí registado com a respetiva mensagem. As entradas com mais de 30 dias são eliminadas automaticamente. ## Limitações da versão 1.0 - Um produto corresponde a um listing com referência única (sem variações nativas da Etsy). - Uma só loja Etsy (uma loja ligada de cada vez). - O seguimento de expedição ainda não é devolvido à Etsy. - A repartição detalhada dos custos de envio por linha não é reconstituída (o total pago na Etsy é o que vale). ## Perguntas frequentes ### Os meus listings são publicados automaticamente? Por predefinição, não: são criados em rascunho, para que os reveja antes de publicar na Etsy. Pode escolher o estado «Ativo» nas definições para publicar de imediato. ### Como evitar vender acima do stock entre os dois canais? Ative a sincronização dos stocks e um cron regular: cada venda ou alteração de quantidade no PrestaShop atualiza a quantidade na Etsy na passagem seguinte do cron. ### Onde encontro o código-fonte? O código completo está incluído no ZIP, sem cifragem (PSR-4, autoloader SPL), para auditoria ou personalização.