Conectar um marketplace a uma loja é uma tarefa para uma tarde. Executar uma integração do PrestaShop com marketplaces como Etsy e eBay simultaneamente é um problema completamente diferente, porque três sistemas agora acreditam possuir o número de estoque autorizado para um SKU, cada um usa seu próprio modelo de autenticação e cada um impõe seu próprio limite de requisições.
O problema real que você encontra em produção nunca é "a chamada da API não funcionou". É uma unidade vendida em excesso no eBay porque um pedido do Etsy foi processado 400 ms antes. É um anúncio que sobreviveu ao produto que alguém excluiu na terça-feira passada. É um pedido importado duas vezes porque um webhook tentou novamente enquanto seu worker estava dentro de uma transação. Portanto, a questão importante não é se o PrestaShop consegue se comunicar com o eBay e o Etsy, pois obviamente consegue, mas sim como você projeta a sincronização para que ela permaneça correta após a loja entrar em funcionamento.
1.0 API de serviço web do PrestaShop vs. um módulo conector de marketplace: quando devo desenvolver?
A resposta sincera depende menos da sua habilidade em PHP do que de quem arcará com os custos de manutenção quando o eBay descontinuar uma versão da API.
A API de serviços web do PrestaShop é uma camada CRUD genérica sobre as entidades do ObjectModel da loja. Ela reside em /api/ e autentica com uma chave de acesso do back-office enviada como nome de usuário HTTP Basic com senha vazia ( Documentação para desenvolvedores do PrestaShop ). Ela acessa produtos, combinações, disponibilidade em estoque e pedidos, e não possui conhecimento sobre marketplaces. A taxonomia do Etsy, as especificidades dos itens do eBay, a atualização do OAuth, os IDs dos anúncios, a política de repetição e as salvaguardas de idempotência permanecem sob sua responsabilidade.
| Desenvolvimento personalizado na API de serviço web | Módulo conector do Marketplace | |
|---|---|---|
| Tempo até a primeira listagem sincronizada | Semanas, autenticação, mapeamento e enfileiramento vêm primeiro | De horas a dias; telas de mapeamento incluídas. |
| Atualizações da API do Marketplace | Você acompanha as notas de lançamento do Etsy e do eBay. | Responsabilidade do fornecedor, if o fornecedor permanece ativo |
| Controle de mapeamento de dados | É possível ter uma lógica de atributos completa e por marca. | Delimitado pela interface de mapeamento do módulo. |
| Arquitetura síncrona | Você escolhe a fila, os trabalhadores, os bloqueios e o tempo de espera. | Geralmente controlado por cron; o comportamento em tempo real varia. |
| manuseio em condições de corrida | Só é tão bom quanto você o constrói. | Frequentemente, a área mais frágil. |
| orçamento de limite de taxa | Você é o proprietário dos buckets de tokens e pode priorizar. | Opaco; verifique como o módulo regula a velocidade. |
| Depuração | Seus registros, seus IDs de correlação | Formato do registro do fornecedor; o rastreamento por SKU varia. |
| Custo contínuo | Tempo de desenvolvimento, indefinidamente | Licença mais atualização de atrito |
| Mais adequado para | Mais de 2 canais, atributos complexos, preços personalizados | Sincronização padrão do eBay/Etsy, equipes pequenas |
Na prática, a sequência é mais eficaz do que o "ou um ou outro": compre o conector para comprovar que o canal gera receita e, em seguida, desenvolva-o quando o catálogo ultrapassar a capacidade do modelo de mapeamento. Conectores como a Integração do Marketplace do eBay para PrestaShop e a Integração do Marketplace do Etsy para PrestaShop da Knowband existem porque essa primeira camada — perfis, mapeamento de categorias, estado dos anúncios, importação de pedidos e feedback de status — é o mesmo trabalho em todos os projetos. Independentemente do caminho escolhido, os critérios abaixo ainda se aplicam; um módulo só beneficia quem o implementa.
1.1 O que a API de serviço web não fará por você
Ele move registros; não executa lógica de negócios. A requisição POST para /api/orders ignora PaymentModule::validateOrder(), portanto, reduções de estoque, faturas e e-mails de status do pedido nunca são disparados. Também não há cota de requisições documentada, o que não significa que não haja limite máximo, pois cada chamada para /api/ inicializa o framework, então seu limite real são os workers do PHP-FPM, e um loop de resincronização os esgota muito antes que os limites do eBay entrem em vigor. Uma alternativa pode ajudar: um módulo pode registrar seus próprios recursos de webservice ( conceitos de webservice de módulo ) e expor um único endpoint marketplace_sync em vez de oito chamadas genéricas por produto.
2.0 Mapeamento de dados: combinações do PrestaShop versus taxonomia do Etsy e especificações de itens do eBay
É aqui que os projetos de marketplace perdem semanas silenciosamente. Os três modelos de catálogo não apenas usam nomes de campos diferentes; eles discordam sobre o que é um produto.
O PrestaShop modela um produto como uma árvore de categorias aninhadas, um id_category_default e combinações geradas a partir de grupos de atributos. O eBay exige um categoryId de uma única folha, além das especificações do item, cujos nomes, cardinalidade e valores permitidos são definidos por categoria e obtidos por meio do método getItemAspectsForCategory da API de Taxonomia ( API de Taxonomia do eBay ). O Etsy exige um taxonomy_id de sua própria taxonomia de vendedor, além das propriedades desse nó, e limita as variações a duas propriedades por anúncio.
Três consequências se fazem sentir durante o primeiro lançamento do catálogo:
- Um produto com três grupos de atributos: tamanho, cor e acabamento. não podes Pode ser um único anúncio do Etsy. Ou você incorpora uma dimensão ao título ou divide o produto, de forma que um produto do PrestaShop passe a corresponder a vários IDs de anúncios do Etsy.
- O eBay rejeita uma publicação quando falta um aspecto obrigatório, portanto, valide o mapeamento por categoria. antes o impulso em vez de descobri-lo a partir de um 400.
- Ambas as plataformas estão revisando suas taxonomias, o que torna um ID de categoria fixo uma futura indisponibilidade.
2.1 Defina o SKU como a chave de entrada em todos os canais.
Antes de qualquer mapeamento, defina a identidade. A referência do PrestaShop deve ser o identificador principal de sincronização, e cada combinação precisa do seu próprio identificador, por exemplo: TSHIRT-BLK-M, TSHIRT-BLK-L, TSHIRT-WHT-M. A API de Inventário do eBay é endereçada por SKU por padrão ( API de Inventário do eBay ), portanto, uma combinação com uma referência vazia não poderá ser sincronizada. Valide isso durante o processo de integração, não a cada atualização.
2.2 Armazene o mapeamento como dados e versione-o.
Resista à tentação de escrever `mapCategory()` em PHP. Os mapeamentos são dados comerciais que um comerciante edita, não código que você reimplantará.
-- Esquema ilustrativo para a camada de mapeamento
CRIAR TABELA ps_mp_category_map (
id_map INT UNSIGNED NOT NULL AUTO_INCREMENT,
canal ENUM('etsy','ebay') NÃO NULO,
id_category INT UNSIGNED NOT NULL, -- Categoria do PrestaShop
remote_node VARCHAR(64) NOT NULL, -- etsy taxonomy_id | ebay categoryId
aspects_json TEXT NULL, -- valores padrão de aspectos estáticos
taxonomy_rev VARCHAR(32) NULL, -- versão da árvore de categorias do eBay
CHAVE PRIMÁRIA (id_map),
CHAVE ÚNICA channel_cat (canal, id_categoria)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CRIAR TABELA ps_mp_listing_link (
id_product INT UNSIGNED NOT NULL,
id_attribute INT UNSIGNED NOT NULL DEFAULT 0, -- 0 = produto simples
canal ENUM('etsy','ebay') NÃO NULO,
remote_id VARCHAR(64) NOT NULL, -- listing_id | offerId
remote_sku VARCHAR(64) NOT NULL,
última_enviada_em DATETIME NULL,
CHAVE PRIMÁRIA (id_produto, id_atributo, canal),
CHAVE ÚNICA chan_remote (canal, id_remoto)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
Armazene a versão da árvore de categorias do eBay junto com o mapeamento. Quando getDefaultCategoryTreeId retorna uma nova versão, cada linha com um taxonomy_rev desatualizado precisa ser revalidada, o que faz a diferença entre um remapeamento agendado e uma segunda-feira de falhas de publicação.
3.0 Arquitetura de sincronização de inventário: webhooks, consulta agendada ou ambos
Compare o que cada lado realmente emite, e a resposta deixa de ser uma questão de gosto.
| Canal | Capacidade de empurrar | lacuna de cobertura |
|---|---|---|
| PrestaShop | Não há webhooks de saída nativos; um módulo engata as ações actionUpdateQuantity, actionValidateOrder e actionProductUpdate. | Nada é acionado para edições diretas de SQL ou alguns caminhos de importação. |
| Etsy | Os webhooks abrangem apenas quatro eventos de pedido: order.paid, order.canceled, order.shipped, order.delivered (Webhooks do Etsy) | Nenhum evento criado por recibo, e nenhum evento de alteração de estoque |
| eBay | API de notificação com assinaturas de tópicos e destinos HTTPS (API de Notificação do eBay) | A disponibilidade dos tópicos varia; utilize o comando `getTopics` para enumerá-los em vez de presumir. |
O Etsy não emite nenhuma informação quando a finalização da compra de um comprador altera a quantidade de itens, nem quando um recibo é criado. Essa lacuna força a implementação de polling no projeto, independentemente da qualidade do tratamento de webhooks. Portanto, a regra prática é: webhooks para latência, polling para informações precisas : os webhooks garantem a velocidade de processamento, enquanto uma verificação de reconciliação a cada 5 a 15 minutos relê as quantidades e os recibos recentes, corrigindo o que a velocidade de processamento deixou passar. A reconciliação não é um recurso de contingência que você espera que nunca seja executado; ela é o que garante a correção do sistema.
Se você usar um conector, a mesma arquitetura aparecerá como tarefas cron. Um módulo que está instalado, licenciado e mapeado perfeitamente ainda parecerá quebrado quando sua tarefa agendada nunca for executada; portanto, a verificação do cron deve estar na lista de verificação de entrada em produção, e não nas anotações de solução de problemas.
3.1 Nunca utilize a API de um marketplace durante o processo de finalização da compra.
// Exemplo ilustrativo: gancho de módulo. Apenas enfileirar — nunca chamar uma API do marketplace aqui.
função pública hookActionUpdateQuantity($params)
{
$sku = $this->resolveSku((int) $params['id_product'], (int) $params['id_product_attribute']);
se (!$sku) {
voltar;
}
Db::getInstance()->insert('mp_sync_queue', [
'sku' => pSQL($sku),
'op' => 'stock.push',
'payload' => pSQL(json_encode(['quantity' => (int) $params['quantity']])),
'dedupe_key' => pSQL('stock:' . $sku), // colapsa rajadas
'created_at' => date('Ymd H:i:s'),
], false, true, Db::REPLACE); // REPLACE = a intenção mais recente prevalece
}
Uma chamada HTTP dentro do gancho adiciona latência ao checkout e causa falha no pedido quando o Etsy está lento, então o gancho apenas enfileira os pedidos. O comando REPLACE em uma chave de deduplicação por SKU transforma vinte movimentações de estoque em um minuto em uma única chamada de saída contendo a quantidade atual.
4.0 Condições de corrida quando um SKU é vendido em três canais simultaneamente
Pegue quatro unidades de CAMISETA-PRETA-M. Um comprador do eBay leva duas, um comprador do Etsy leva uma, e a loja virtual leva uma, tudo em dois segundos. Três trabalhadores são ativados, cada um lê o estoque, calcula a quantidade e envia o pedido. Dois bugs independentes estão agora à espreita.
A aritmética relativa perde atualizações. Um trabalhador que envia "decrementar em 2" enquanto outro envia "decrementar em 1" para um valor que ambos leem como 4, resulta em 2 ou 3, dependendo da ordem. Sempre envie as quantidades absolutas lidas no momento do envio. `StockAvailable::getQuantityAvailableByProduct()` é a única fonte de verdade, e as quantidades no marketplace são projeções dela, nunca entradas para aritmética.
As operações de envio intercaladas deixam um estado final obsoleto. O trabalhador A lê 2, o trabalhador B lê 1 um instante depois, B envia 1, e então a solicitação mais lenta de A chega e grava 2. O eBay agora anuncia uma unidade que não existe. Um bloqueio por SKU, juntamente com uma verificação de versão monotônica, é a maneira mais barata de impor a ordem correta.
// Exemplo ilustrativo: serializar todas as notificações push para um SKU em todos os canais.
$lockName = 'mp_sku_' . md5($sku);
$db = Db::getInstance();
// Bloqueio consultivo do MySQL: aguarda até 3 segundos, retorna 1 na aquisição e 0 no tempo limite.
if (!(int) $db->getValue("SELECT GET_LOCK('" . pSQL($lockName) . "', 3)")) {
$this->requeue($job, 5); // outro worker possui este SKU; tente novamente em breve
voltar;
}
experimentar {
$qty = (int) StockAvailable::getQuantityAvailableByProduct($idProduct, $idAttribute);
$ver = (int) $db->getValue(
'SELECT stock_version FROM ' . _DB_PREFIX_ . 'mp_sku_state WHERE sku = "' . pSQL($sku) . '"'
);
se ($job['version'] < $ver) {
retornar; // uma nova notificação push já foi enviada; descarte esta
}
$this->etsy->setQuantity($sku, $qty); // valor absoluto
$this->ebay->setQuantity($sku, $qty); // valor absoluto
$db->execute(
'ATUALIZAR ' . _DB_PREFIX_ . 'mp_sku_state
DEFINIR stock_version = stock_version + 1, synced_qty = ' . $qty . ', synced_at = NOW()
ONDE sku = "' . pSQL($sku) . '"'
);
} finalmente {
$db->execute("SELECT RELEASE_LOCK('" . pSQL($lockName) . "')");
}
O GET_LOCK tem escopo de sessão, portanto, abrange processos do PHP-FPM e do cron no mesmo banco de dados e libera o bloqueio quando a conexão é encerrada, o que um bloqueio em linha não faz. Em vários servidores de banco de dados, mova o bloqueio para o Redis e mantenha a coluna de versão como medida de segurança.
A ausência de bloqueio elimina o risco residual. Entre o checkout do Etsy e sua publicação, o eBay pode vender a mesma unidade de forma legítima. Portanto, mitigando isso comercialmente: publique "disponível - 1" para os itens de venda rápida e publique "0" na última unidade imediatamente, em vez de esperar até a próxima conciliação.
5.0 Como os limites de taxa da API do Etsy, os limites de taxa da API do eBay e o teto do PrestaShop se acumulam
Cada orçamento parece generoso individualmente. No entanto, em uma sincronização tripla, eles se multiplicam em relação à sua quantidade de SKUs.
| Canal | Limites documentados | Sinais para ler |
|---|---|---|
| Etsy | Cotas de QPS e QPD por aplicativo em uma janela deslizante; o padrão documentado para um novo aplicativo é de 10 solicitações/segundo e 10,000 por 24 horas, podendo ser aumentado mediante solicitação (limites de taxa do Etsy) | x-limite-por-segundo, x-restante-neste-segundo, x-limite-por-dia, x-restante-hoje; tentar-novamente-após em 429 |
| eBay | Limites diários de chamadas por aplicação, por API e recurso, definidos através da Verificação de Crescimento da Aplicação (limites de chamadas da API do eBay) | API de análise de desenvolvedores getRateLimits — cota, usada, restante, janela de redefinição |
| PrestaShop | Sem cota publicada; limitado pelos workers do PHP-FPM e pelo custo de inicialização do framework por chamada /api/ | Sua própria taxa 5xx e profundidade de fila FPM |
Uma resincronização completa de 3,000 SKUs exige uma gravação de inventário no Etsy por anúncio, uma atualização de oferta no eBay por SKU e uma leitura no PrestaShop por SKU. Com a taxa padrão de 10 QPS do Etsy, isso representa uma sobrecarga contínua de cinco minutos, sem margem para o coletor de pedidos, a única tarefa que nunca pode ser interrompida. Três regras mantêm o orçamento sob controle:
- Execute um bucket de tokens por canal, compartilhado por todos os trabalhadores. Aplique essa restrição no Redis, pois um limitador por processo multiplica sua taxa real pelo número de trabalhadores.
- Priorizar filas. A remoção de pedidos e a redução do estoque a zero têm prioridade sobre as atualizações de preço e os uploads de imagens. O uso de cota para miniaturas enquanto ocorre uma sobrevenda é um erro de projeto.
- Lote e diferença. A API de Inventário do eBay oferece atualizações em lote de preço e quantidade, então processe em lotes até o limite atual por chamada, compare com a quantidade sincronizada (synced_qty) e pare de gastar a cota para confirmar que 7 ainda é igual a 7.
6.0 Autenticação: Chaves da API OAuth do Etsy, OAuth 2.0 do eBay e da API do PrestaShop
Três modelos, e apenas dois deles expiram.
O PrestaShop envia a chave de acesso como nome de usuário HTTP Basic com senha vazia. Sem expiração, sem atualização, sem modo de falha de atualização de token; o risco é o oposto, já que uma chave nunca é rotacionada a menos que você a rotacione.
O Etsy usa o protocolo OAuth 2.0 com concessão de código de autorização e PKCE obrigatório: um `code_verifier` de 43 a 128 caracteres e um `code_challenge` S256. Os tokens de acesso têm um tempo de expiração de 3600 dias e os tokens de atualização têm validade de 90 dias ( autenticação do Etsy ). Cada requisição precisa do cabeçalho `x-api-key` e do token de portador (bearer token), cujo formato é `{user_id}.{token}`, sendo que o prefixo numérico pertence à credencial. A remoção desse prefixo é um bug clássico encontrado no primeiro dia de uso.
O eBay emite tokens de acesso de usuário válidos por 7,200 segundos e tokens de atualização válidos por 47,304,000 segundos, aproximadamente dezoito meses ( tokens OAuth do eBay ). Os tokens de aplicativo abrangem dados públicos, mas qualquer transação relacionada ao inventário de um vendedor requer o token de usuário.
A falha que realmente interrompe as tarefas de sincronização não é o vencimento do token. É o fato de dez processos detectarem o vencimento simultaneamente. Portanto, proteja a atualização com um bloqueio de voo único, verifique novamente o token armazenado sob esse bloqueio e atualize em um intervalo de dois minutos, em vez de reagir a um erro 401. Persista o token de atualização rotacionado na mesma gravação do token de acesso, pois uma falha entre duas gravações resulta na perda da permissão. Em seguida, gere alertas sobre a idade de sucesso da atualização , bem como sobre a falha, porque uma permissão que não foi atualizada em 24 horas é um problema mesmo quando nenhuma exceção foi lançada ( melhores práticas do eBay OAuth ).
7.0 Sincronização de pedidos do Marketplace: impostos, frete, moeda e idempotência
A importação de pedidos é onde os contadores encontram seus erros. Um pedido de marketplace não é um pedido do PrestaShop com nomes de campos diferentes; é um documento financeiro liquidado. Quatro inconsistências precisam ser resolvidas antes de você escrever o código do importador.
Imposto sobre facilitadores de mercado. O Etsy e o eBay coletam e repassam o imposto sobre vendas ou o IVA para o vendedor em muitas jurisdições. Esse imposto está incluído no payload, mas não é responsabilidade do comerciante nem sua receita, portanto, importá-lo para uma regra de imposto normal infla a declaração de IVA. Mapeie-o para uma regra de alíquota zero mais um campo contábil separado e, em seguida, confirme o tratamento com o contador do comerciante.
Envio. Os marketplaces enviam um valor já calculado com base em seus próprios perfis de frete. Não execute novamente as regras de frete do PrestaShop, pois os totais divergem e o pedido nunca é conciliado com o pagamento. Em vez disso, crie uma transportadora por canal e defina o custo a partir do payload.
Moeda. A carga útil carrega sua própria moeda e o pagamento pode chegar em uma terceira. Mantenha o valor do mercado, o valor na moeda da loja e a taxa de conversão usada na importação, pois reutilizar a taxa de hoje para reimprimir uma fatura de três meses atrás produz um documento que não corresponde a nada.
Caminho de criação. Construa o carrinho e, em seguida, chame PaymentModule::validateOrder() — o único caminho que decrementa o estoque, gera a fatura, define o estado do pedido e dispara os hooks dos quais outros módulos dependem.
// Exemplo ilustrativo: importação de pedidos em marketplace idempotente.
$externalId = $channel . ':' . $remoteOrderId;
se (Db::getInstance()->getValue(
'SELECT id_order FROM ' . _DB_PREFIX_ . 'mp_order_link
ONDE external_id = "' . pSQL($externalId) . '"'
)) {
retornar; // já importado — tentativa de webhook ou sondagem sobreposta
}
$carrinho = novo Carrinho();
$cart->id_customer = $idCustomer;
$cart->id_currency = (int) Currency::getIdByIsoCode($payload['currency']);
$cart->id_carrier = (int) Configuration::get('MP_CARRIER_' . strtoupper($channel));
$cart->id_address_delivery = $idAddress;
$cart->id_address_invoice = $idAddress;
$cart->add();
foreach ($payload['lines'] as $line) {
$cart->updateQty((int) $line['qty'], (int) $line['id_product'], (int) $line['id_attribute']);
}
$module = Module::getInstanceByName('mpsync');
$module->validateOrder(
(int) $cart->id,
(int) Configuração::obter('PS_OS_PAYMENT'),
(float) $payload['total_paid'],
$channel . ' Marketplace',
nulo
['transaction_id' => $remoteOrderId],
(int) $cart->id_currency,
falso,
$cart->chave_segura
);
Db::getInstance()->insert('mp_order_link', [
'external_id' => pSQL($externalId),
'id_order' => (int) $module->currentOrder,
'importado_em' => date('Ymd H:i:s'),
]);
Coloque um índice UNIQUE em external_id. O SELECT acima é apenas um caminho rápido; o índice é a garantia, porque dois processos podem passar nessa verificação no mesmo milissegundo. Em seguida, paginar os resultados de getOrders do eBay e os recibos de lojas do Etsy usando um cursor persistente com valor atualizado desde, em vez de um deslocamento fixo que se altera sem que você perceba.
A idempotência se estende além dos pedidos. Um push de produto envolve quatro chamadas: criar item de estoque, criar oferta, fazer upload de imagens e publicar. Portanto, registre o estado de cada etapa com base em (SKU, canal, etapa) e permita que uma nova tentativa seja retomada em vez de reiniciar. O Etsy também assina webhooks com webhook-id, webhook-timestamp e webhook-signature, portanto, remova duplicatas com base no webhook-id e rejeite timestamps com mais de 300 segundos de diferença. Somente esse cabeçalho já elimina a classe de nova tentativa para duplicatas.
8.0 Monitoramento da sincronização de um mercado de produção
Uma sincronização que falha de forma evidente é uma tarefa de manutenção. Uma que falha silenciosamente é uma fila de reembolsos.
| Registre todas as operações com | Alerta em |
|---|---|
| Correlação de ID abrangendo webhook → fila → chamada de API | Divergência de ações, local ≠ remoto por mais de N minutos |
| SKU, canal, operação, quantidade absoluta enviada | Falha na autenticaçãoQualquer erro de atualização do OAuth será imediatamente notificado. |
| Solicitação e resposta completas para não-2xx, segredos omitidos. | queima com taxa limitada, quota diária restante inferior a 20% antes das 18:00 |
| Orçamento restante de limite de taxa por canal | Idade da fila, trabalho não processado mais antigo com mais de 5 minutos |
| Data e hora de expiração do token e da última atualização bem-sucedida. | Lacuna de ordem, zero pedidos de um canal em uma janela normalmente movimentada |
| Resultados da reconciliação: verificado, reparado, não resolvido | Silêncio de Cron, uma tarefa de sincronização agendada que não foi executada no prazo |
Duas métricas merecem destaque. A idade da fila é o principal indicador, pois aumenta antes que os clientes percebam qualquer problema. A contagem de correções de reconciliação é a métrica de honestidade; quando o processo de 15 minutos continua corrigindo os mesmos SKUs, seu caminho rápido está com problemas e a verificação automática está silenciosamente mascarando a falha.
Por fim, registre a quantidade absoluta enviada, e não a diferença. Quando um lojista perguntar por que o eBay mostrou 3 enquanto o PrestaShop mostrou 1, a resposta deve poder ser obtida apenas com base no registro de dados.
9.0 Solução de problemas para quatro falhas de sincronização do marketplace do PrestaShop que você realmente encontrará
9.1 Os anúncios mostram quantidades desatualizadas, enquanto os registros mostram HTTP 200.
Verifique a carga útil, não o código de status. No Etsy, uma atualização de estoque de um anúncio substitui toda a estrutura de estoque, portanto, uma estrutura parcial pode redefinir ofertas que você nunca pretendeu alterar. No eBay, atualizar um item de estoque não é o mesmo que atualizar a oferta publicada, e a oferta contém a quantidade disponível para venda. Leia um SKU imediatamente após um push e compare campo por campo. Em uma configuração baseada em conectores, percorra a mesma cadeia primeiro: o produto está mapeado? Ele possui uma referência válida? A tarefa de sincronização está habilitada? O cron foi executado?
Os erros 9.2 429 aparecem apenas durante a resincronização completa noturna.
Seu limite de tokens é por processo, então oito processos cron são executados a uma taxa oito vezes maior que a pretendida. Mova o limitador para um armazenamento compartilhado. Em seguida, questione a própria resincronização completa, compare com o `synced_qty` e envie apenas as alterações. O consumo noturno geralmente diminui em uma ordem de magnitude. Respeite o `retry-after` nos erros 429 do Etsy e verifique o `getRateLimits` do eBay antes de um grande lote de requisições, em vez de se deparar com um limite no meio da execução.
9.3 O mesmo pedido é importado duas vezes, com algumas horas de intervalo.
Janelas de consulta sobrepostas e uma restrição ausente. Confirme se o índice UNIQUE em external_id existe, pois uma consulta SELECT para verificação de duplicatas sem ele resulta em uma condição de corrida em vez de uma verificação. Em seguida, verifique o cursor: um mecanismo de consulta que solicita a cada 15 minutos "pedidos atualizados nos últimos 30 minutos" oferece cada pedido duas vezes, por design. Mantenha um limite máximo de consultas, sobreponha-o deliberadamente e deixe o banco de dados garantir a unicidade.
9.4 A sincronização para em um canal às 3h da manhã sem erros.
Geralmente ocorre a perda do token de atualização. Um token de atualização do Etsy expirou silenciosamente seu período de 90 dias, ou uma atualização simultânea rotacionou o token duas vezes e seu worker persistiu o token inválido. Verifique primeiro o `expires_at` e o timestamp da última atualização bem-sucedida do armazenamento de tokens. Em seguida, confirme se o serviço cron do servidor ou o agendador externo ainda está executando as tarefas de sincronização, pois um agendador parado produz exatamente esse sintoma e exatamente esses logs vazios.
10.0 Lista de verificação de prontidão para produção para vendas multicanal no PrestaShop
Antes de considerar a integração com o Etsy ou o eBay concluída, verifique esta lista:
- ProdutosCada produto e combinação sincronizados possui uma referência única, as categorias são mapeadas para nós válidos do marketplace, os aspectos obrigatórios são preenchidos e as imagens atendem aos requisitos do marketplace.
- EstoqueO PrestaShop é a fonte da verdade, os envios (push) mantêm as quantidades absolutas protegidas por um bloqueio por SKU, os envios com estoque zero são feitos imediatamente e a reconciliação é executada de acordo com um cronograma.
- Pedidos, o ID do pedido do marketplace é armazenado sob uma restrição única, o imposto e o frete do facilitador são mapeados deliberadamente e as importações são executadas por meio de validateOrder().
- API e autenticaçãoAs credenciais são armazenadas com segurança, a atualização é executada em uma margem protegida por um bloqueio de voo único e os limites de taxa são compartilhados entre os trabalhadores.
- Cron e monitoramento, todas as tarefas necessárias estão sendo executadas de forma verificável, o tempo de espera na fila e os reparos de reconciliação estão visíveis, e as falhas de autenticação geram um alerta em vez de uma linha de log.
11.0 Por onde começar
Ao construir uma integração de marketplace para PrestaShop do zero, a ordem que evita retrabalho é a seguinte: integridade de SKU, mapeamento de tabelas, envio de quantidades absolutas protegido por um bloqueio por SKU, importação de pedidos com um ID externo único, reconciliação e, por último, webhooks. Os webhooks são a otimização. Um loop de polling correto com bloqueios e idempotência já é um sistema confiável.
Se preferir partir de um conector funcional e dedicar tempo de desenvolvimento ao que é realmente específico para o seu catálogo, avalie o módulo com base nessa mesma lista de verificação, mapeamento, agendamento, visibilidade de erros, proteção contra duplicados, reconciliação e confirme suas tarefas cron antes de implementá-lo. De qualquer forma, o objetivo não é sincronizar apenas uma vez, mas sim manter a sincronização em seis meses.
Se você tiver dúvidas ou precisar de ajuda com o desempenho ou a migração do seu site, nossos especialistas estão à disposição. Entre em contato com a equipe da Knowband pelo e-mail [email protected] hoje mesmo para obter plugins de e-commerce confiáveis e personalizados para as suas necessidades.
