Alpha Commerce

O que ele faz

• As mesmas ferramentas para as duas plataformas: situações como active, paused e paid têm o mesmo nome; o valor original vem em status_detail.
• Toda alteração mostra o plano antes e devolve o valor de antes e como desfazer.
• Conhece as armadilhas do Mercado Livre: descrição que nasce vazia, moderação que aparece minutos depois, categoria sem Mercado Envios, faixas de preço que somem ao mudar o preço.
• Várias contas na mesma conversa, de uma ou das duas plataformas.
• Trabalha junto com o Alpha ERP, pelo SKU: veja a página os dois juntos.

Credenciais do Mercado Livre

O Alpha Commerce não pede a sua senha do Mercado Livre. Ele usa uma aplicação que você mesmo cria no portal de desenvolvedores do Mercado Livre, e ela define o que o assistente pode fazer na sua conta. É feito uma vez.

O que você precisa

• A conta principal do vendedor. Contas de colaborador têm permissões limitadas e podem não servir.
• Um endereço de site que comece com https://, porque o Mercado Livre exige isso no endereço de retorno. Pode ser o site da sua loja. Depois de autorizar, o navegador vai para esse endereço (mesmo que a página dê erro ou fique em branco) e você copia o endereço da barra e cola na conversa com o assistente.
• O instalador aberto ao lado, com os campos para colar o que o Mercado Livre mostrar.

Passo a passo

1. Entre em developers.mercadolivre.com.br com a conta principal do vendedor e abra Minhas aplicações.
2. Crie uma nova aplicação. Dê um nome que você reconheça, como "Alpha Commerce", e uma descrição curta.
3. Em URI de redirecionamento, cadastre o endereço https:// do seu site (a raiz do domínio serve). Anote exatamente como ficou: você vai colar o mesmo no instalador.
4. Marque os fluxos Authorization Code e Refresh Token. Sem o segundo, o acesso cai depois de cerca de 6 horas. Se houver a opção PKCE, ative.
5. Nas permissões (escopos), deixe leitura e, se o assistente for alterar anúncios ou responder perguntas, escrita, além do acesso offline.
6. Salve. O Mercado Livre mostra o App ID (o Client ID) e a chave secreta (o Client Secret).
7. Copie os dois e cole no instalador, junto com o endereço de retorno.

O que copiar e onde colar

Conferir se deu certo

Os três campos do Mercado Livre no instalador vão juntos: ou os três preenchidos, ou os três em branco (quem usa só o WooCommerce deixa em branco). Feche e abra o assistente e peça "Conecte minha conta do Mercado Livre". O assistente mostra um endereço de login: abra, entre com a conta principal e autorize. Depois o navegador vai para o endereço do seu site: copie o endereço inteiro da barra (ele tem code= no meio) e cole na conversa. Para outro país (Argentina, México e outros), use o endereço de login do país nas opções avançadas do instalador.

Se algo der errado

Revogar o acesso

Para encerrar o acesso de vez, remova a aplicação em Minhas aplicações.

Credenciais do WooCommerce

A loja WooCommerce não usa login: você gera uma chave de API no painel da própria loja, com a permissão que quiser dar. São duas partes, a chave (começa com ck_) e o segredo (começa com cs_). Você revoga quando quiser, no mesmo lugar.

O que você precisa

• Acesso de administrador ao painel da loja (WordPress).
• A loja de produção, a que vende de verdade, respondendo por https://. O programa recusa endereços http://, endereços com usuário e senha e endereços da rede interna.
• Os links permanentes do WordPress em qualquer opção que não seja Simples (em Configurações > Links permanentes). O WooCommerce exige isso para a API funcionar.

Passo a passo

1. No painel da loja, abra WooCommerce > Configurações > Avançado > API REST.
2. Clique em Adicionar chave.
3. Em Descrição, escreva "Alpha Commerce". Em Usuário, escolha o seu usuário administrador.
4. Em Permissões, escolha Leitura para começar (o assistente só consulta). Escolha Leitura/Gravação só se quiser que ele altere preço, estoque e pedidos, sempre com a sua confirmação.
5. Clique em Gerar chave de API.
6. A tela mostra a Consumer key (ck_...) e o Consumer secret (cs_...). O segredo só aparece essa vez: copie os dois antes de sair da página. O painel em português pode traduzir os nomes.
7. Abra o instalador, escolha Conectar loja WooCommerce e cole o endereço da loja, a chave e o segredo.

O que copiar e onde colar

Qual permissão escolher

Na dúvida, comece com Leitura: dá para gerar outra chave com gravação depois.

Conferir se deu certo

Depois de conectar, a loja aparece na tela Seus programas do instalador como "conectada · só consulta" (ou "pode alterar"). No assistente, peça: "Quais lojas estão conectadas?" e depois "Liste os 5 produtos mais recentes da minha loja".

Se algo der errado

Revogar o acesso

No painel da loja, em WooCommerce > Configurações > Avançado > API REST, abra a chave e clique em Revogar chave. O assistente perde o acesso na hora.

Ferramentas

As respostas trazem um resumo com os mesmos campos para as duas plataformas. Com raw: true, a resposta inclui o registro original. Listas paginam com cursor. Uma ferramenta de uma plataforma chamada numa conta da outra responde com o que aquela plataforma suporta e indica a ecommerce_api.

Exemplos de pedidos

Peça em português, e o assistente escolhe a ferramenta.

• "Quais anúncios estão pausados e por quê?"
• "Tem pergunta sem resposta? Me mostre as três mais antigas."
• "Quanto sobra no meu bolso se eu vender o SKU CAM-001-M a R$ 120 no anúncio Premium?"
• "Algum anúncio está sem Mercado Envios ou sem descrição?"
• "Esse anúncio está em revisão? Qual o motivo e como corrijo?"
• "Confira se o estoque da loja WooCommerce bate com o do ERP." (com os dois programas ligados)
• "Muda o preço desse anúncio para R$ 119,90." (o assistente mostra o plano, inclusive se as faixas de preço por quantidade serão apagadas, e só altera depois do seu sim)

Mais de uma conta

• Com mais de uma conta, account é obrigatório em toda chamada (mercadolivre:123, woocommerce:loja.exemplo). Sem ele, o erro lista as contas.
• Cada conta enxerga só os seus dados. Escrever numa não mexe na outra, e a liberação de escrita vale por conta.
• Perder o acesso de uma conta pede a reconexão dela e não derruba as outras.
• Acrescentar uma conta ou loja depois não refaz nada. Uma loja WooCommerce nova entra pela tela Conectar loja WooCommerce do instalador; outra conta do Mercado Livre, pelo pedido "conecte outra conta do Mercado Livre". Só a nova é conectada, e as que já estavam continuam como estão (o aplicativo do Mercado Livre é o mesmo para todas as contas). Se for a primeira conta de uma plataforma ainda sem conta, feche e abra o assistente para as ferramentas dela aparecerem.

Confirmação e somente leitura

• Toda escrita pede confirmação. As ferramentas de escrita e a ecommerce_api fora do GET só alteram com confirm: true. Sem ele, a resposta é o plano (applied: false): o que mudaria, de/para, com os avisos.
• Valor anterior e desfazer. A escrita devolve o valor de antes (preço, faixas, descrição) e o undo, a chamada que restaura (que também pede confirm: true). O desfazer vive na resposta; não é guardado entre conversas.
• Catálogo de erros conhecidos. Cada recusa do Mercado Livre chega com o que fazer, por exemplo "categoria sem Mercado Envios: escolha outra com ecommerce_category_shipping".
• Somente leitura: as ferramentas de escrita nem aparecem. Validar, auditar, cotar, ver faixas, elegibilidade e acompanhar moderação continuam.

O que ele não faz

O Alpha Commerce só trata das contas e lojas que você conectou: anúncios e produtos, preço e estoque, pedidos, envios e, nas plataformas que têm, perguntas, tarifas e moderação. Um pedido fora disso (previsão do tempo, um texto livre, contas bancárias, uma loja ou plataforma que você não conectou) não usa nenhuma ferramenta do programa: o assistente responde com o conhecimento dele ou diz que aquilo não é com o programa.

Não há como o programa chegar ao que você não ligou a ele: as ferramentas só falam com as contas conectadas. E uma plataforma que ainda não existe no programa só passa a existir quando a Alcateia publicar o conector.

O que o programa sabe do Mercado Livre

Estes comportamentos custaram tempo numa operação real e não aparecem com clareza na documentação do Mercado Livre. As ferramentas já os tratam.

• Descrição: num anúncio criado no modelo de produto de usuário, o campo description da criação é ignorado e o anúncio nasce sem descrição. A ecommerce_description_set cria ou atualiza (consulta antes, escolhe o verbo, trata o erro de catálogo) e a ecommerce_account_audit lista os anúncios sem descrição.
• Moderação: a infração "categoria incorreta" pode aparecer cerca de 5 minutos depois da criação, com o anúncio já ativo. A ecommerce_moderation_watch acompanha por alguns minutos e devolve o resumo.
• Envio: uma categoria sem Mercado Envios deixa o envio "a combinar" sozinha, sem erro. A ecommerce_category_shipping responde se a categoria tem Mercado Envios e a ecommerce_listing_validate diz se ele foi mantido.
• Frete grátis vale pelo total do pedido a partir de R$ 79, não só pelo preço da unidade: margem e preço mínimo devem ser calculados para o pedido com várias unidades. A ecommerce_shipping_quote faz a cotação, com kit empilhado.
• Preço por quantidade: qualquer alteração de preço do anúncio apaga as faixas. A ecommerce_quantity_price_set e a ecommerce_listing_update avisam e mostram o preço efetivo de antes e de depois.
• Anúncio novo nasce pausado até a foto processar (2 a 3 minutos), e o segundo anúncio do mesmo produto só depois disso. A foto precisa de pelo menos 500 px em um dos lados.
• Estoque zero pausa o anúncio; voltar a ter estoque o reativa.

Limites

• A busca por situação pagina até 1.000 anúncios; acima disso, o Mercado Livre exige outro modo de busca, ainda não implementado.
• Publicar anúncio novo ainda não tem ferramenta própria: valide com a ecommerce_listing_validate e crie pela ecommerce_api.
• A ecommerce_moderation_watch pode levar até 15 minutos; se o assistente cortar chamadas longas, peça com um tempo menor.
• A auditoria de descrição e de faixa de preço faz uma chamada por anúncio, espaçadas em 100 ms: contas grandes levam alguns minutos.

O que já foi validado

Estado em 03/10/2026. Prefira saber o que foi e o que não foi testado: