Conector MCP
Conecte um assistente de IA para consultar e operar a loja por conversa. Use este endereço:
https://lojas.avilaops.com/api/mcpAdicione este endereço como conector no Claude, no ChatGPT ou no Codex e autorize a loja pelo login do painel. O assistente descobre o fluxo sozinho (OAuth 2.1 com PKCE e registro dinâmico de cliente). Na autorização você escolhe o que ele pode: consultar e alterar, só consultar, ou área por área. Exclusivo do plano Loja Pro.
Para automações sem tela, como n8n e scripts, crie no painel uma chave secreta com o escopo mcp:usar e envie no cabeçalho Authorization: Bearer lojas_sk_….
Antes de conectar, consulte que dados o conector lê e guarda.
Ferramentas do conector
26 ferramentas, agrupadas por área da loja.
O assistente só vê as ferramentas que a conexão pode usar. As que alteram a loja vêm marcadas como destrutivas (sobrescrevem, mudam status ou excluem), para ele pedir confirmação antes de agir.
Loja
obter_lojaVer dados da lojaconsultaatualizar_marcaAlterar marca e layoutaltera
Catálogo
listar_produtosListar produtosconsultaobter_produtoVer produtoconsultalistar_categoriasListar categoriasconsultalistar_estoque_baixoVer estoque baixoconsultalistar_avaliacoesListar avaliaçõesconsultacriar_produtoCriar produtoacrescentaatualizar_produtoAlterar produtoalteraatualizar_categoriaAlterar categoriaalteragerar_seo_categoriaGerar e publicar SEO da categoriaalteragerenciar_fotos_produtoAlterar fotos do produtoalteraajustar_estoqueAjustar estoquealteramoderar_avaliacaoModerar avaliaçãoaltera
Pedidos
listar_pedidosListar pedidosconsultaobter_pedidoVer pedidoconsultaatualizar_status_pedidoAlterar status do pedidoalteraemitir_etiqueta_envioEmitir etiqueta de envioaltera
Clientes
listar_clientesListar clientesconsultaobter_clienteVer clienteconsulta
Promoções
listar_cuponsListar cuponsconsultacriar_cupomCriar cupomalteraatualizar_cupomAlterar cupomaltera
Análises
resumo_vendasResumo de vendasconsultaresumo_atribuicaoResumo de origem das vendasconsultaresumo_marketingResumo de marketingconsulta
Autenticação e respostas
Use a API para integrar um ERP, um PDV ou um site próprio. Confira o formato das chaves, dos valores e das respostas antes da primeira requisição.
Versão v1
- Autenticação
- Authorization: Bearer <chave> (ou x-api-key). Chaves secretas começam com lojas_sk_, publicáveis com lojas_pk_. As chaves são criadas em Painel, IA e API.
- Dinheiro
- Valores em centavos inteiros (campos *Centavos), moeda BRL.
- Paginação
- Parâmetros pagina e porPagina; 50 itens por página, no máximo 100.
- Resposta
- Sucesso:
{ "dados": … }. Erro:{ "erro": { "codigo", "mensagem" }, "requisicao" }. Compare ocodigo; a mensagem é para gente e pode mudar.
Rotas da API
Cada rota indica o método HTTP, o caminho e o escopo exigido pela chave.
GET
/api/v1/lojaloja:lerA loja dona da chave e os escopos da chave.
GET
/api/v1/produtoscatalogo:lerCatálogo completo, inclusive inativos. Filtros: ativo, categoria, sku, busca, atualizadoDesde.
GET
/api/v1/produtos/{id}catalogo:lerUm produto (id ou slug) com as variações.
POST
/api/v1/produtosprodutos:escreverCria um produto simples. Nasce inativo, a menos que venha ativo: true. Slug ou SKU já em uso responde conflito (409).
PATCH
/api/v1/produtos/{id}produtos:escreverEdita o cadastro (nome, slug, marca, descrições, categoria, ativo, destaque). Preço e estoque são de /ofertas.
PATCH
/api/v1/ofertascatalogo:escreverPreço e estoque por SKU, em lote de até 100. Valores absolutos em centavos; reenviar o mesmo lote não muda nada.
GET
/api/v1/estoque/saldoscatalogo:lerSaldos físicos e reservados por local. Filtros: varianteId, local. Paginação pagina/porPagina.
GET
/api/v1/estoque/razaocatalogo:lerRazão imutável de alterações de saldo. Filtros: varianteId, local, comandoId. Sequência retornada como string decimal.
POST
/api/v1/estoque/movimentosestoque:escreverEntrada, saída ou transferência imediata entre locais. Exige Idempotency-Key; nunca consome unidades reservadas.
GET
/api/v1/pedidospedidos:lerPedidos. Filtros: status, canal, criadoDesde, atualizadoDesde.
GET
/api/v1/pedidos/{id}pedidos:lerUm pedido (id ou referência) com os itens.
PATCH
/api/v1/pedidos/{id}pedidos:escreverAvança o pedido e registra progresso parcial por item. Exige Idempotency-Key para alterar quantidades; pagamento não muda por aqui.
GET
/api/v1/vitrine/lojavitrine:lerDados públicos da loja, para um front próprio. Aceita chamada do navegador.
GET
/api/v1/vitrine/produtosvitrine:lerProdutos ativos, como a vitrine mostra. Filtros: busca, categoria, destaque, ordem.
GET
/api/v1/vitrine/produtos/{id}vitrine:lerUm produto ativo (id ou slug) com a descrição e as variações. O id de cada variação é o que vai no carrinho.
POST
/api/v1/vitrine/fretevitrine:lerOpções de entrega para um CEP e um carrinho, com a retirada na loja quando há. O id da opção vai em freteId na compra.
POST
/api/v1/vitrine/cupomvitrine:comprarConfere um cupom para um carrinho e devolve o desconto. Uma recusa só (cupom_invalido), e erro conta num limite próprio. Com cep, cupom de frete grátis devolve as entregas já com ele.
POST
/api/v1/vitrine/checkoutvitrine:comprarFecha a compra: cria o pedido e a cobrança e devolve o Pix, o boleto ou o resultado do cartão. O preço sai do servidor. Aceita Idempotency-Key.
GET
/api/v1/vitrine/pedidos/{referencia}vitrine:comprarAndamento do pedido pela referência devolvida na compra, para a tela do Pix saber que foi pago. Sem dado pessoal.
Compra pelo site ou app próprio
Chave publicável com o escopo vitrine:comprar, marcado pelo lojista no painel, e os sites autorizados.
- Corpo de POST /api/v1/vitrine/checkout
{ "itens": [{ "id", "quantidade" }], "cliente": { "nome", "sobrenome", "email", "telefone", "documento" }, "entrega": { "cep", "logradouro", "numero", "complemento"?, "bairro", "cidade", "uf" } | null, "freteId", "meioPagamento": "pix" | "cartao" | "boleto", "cartao"?: { "token", "parcelas"?, "bandeira"? }, "cupom"?, "totalCentavos"? }- Regras
- O preço e o frete saem do servidor. Campo desconhecido é erro. Cupom que não vale recusa a compra (cupom_invalido), não cobra sem desconto. A referência do pedido vem na resposta. Envie Idempotency-Key para repetir sem cobrar de novo. O token do cartão é gerado no navegador com a chave pública do Mercado Pago que vem em /vitrine/loja.
Webhooks
Receba eventos da loja no seu sistema e trate as tentativas repetidas pelo identificador do evento.
Em vez de consultar os pedidos de tempos em tempos, seu sistema é avisado. Painel da loja, em IA e API. Só https, em domínio público.
pedido.criadoPedido registrado, ainda aguardando pagamento ou já aprovado no cartãopedido.pagoPagamento confirmado e estoque baixadopedido.recusadoPagamento recusado; a reserva de estoque foi liberadapedido.em-separacaoA loja começou a separarpedido.enviadoPedido despachado, com transportadora e rastreio quando houverpedido.entreguePedido marcado como entreguepedido.canceladoPedido cancelado pela loja
- Corpo
{ "id", "tipo", "criadoEm", "dados": { "pedido": <o mesmo de GET /api/v1/pedidos/{id}> } }- Assinatura
- x-lojas-assinatura: t=<segundos>,v1=<hmac>. O hmac é HMAC-SHA256, em hexadecimal, de `<t>.<corpo exato>` com o segredo do webhook. Recuse se t tiver mais de 5 minutos.
- Entrega
- Pelo menos uma vez: o mesmo `id` pode chegar de novo, e é por ele que se reconhece a repetição. Responda 2xx em até 8 segundos. Sem 2xx, 7 tentativas ao todo, com esperas de 1, 5, 30, 120, 480, 960 minutos. Redirecionamento não é seguido.
Escopos
Escolha os acessos necessários para a integração. As permissões da chave determinam quais operações ela pode executar.
loja:lerDados da loja (nome, plano, endereço da vitrine)catalogo:lerProdutos e variações, inclusive inativos, com estoquecatalogo:escreverPreço e estoque por SKU (o que o ERP sincroniza)estoque:escreverRegistrar entradas, saídas e transferências imediatas entre locaispedidos:lerPedidos com cliente, itens, valores e rastreiovitrine:lerO que a vitrine pública mostra: produtos ativos e dados da lojavitrine:comprarFechar compra pelo site ou app próprio: criar o pedido e a cobrança e consultar o statusprodutos:escreverCriar produto e editar o cadastro (nome, descrição, categoria, ativo)pedidos:escreverAvançar o pedido: separar, enviar com rastreio, entregar, cancelarloja:escreverMarca, cores e layout da loja (conector MCP)clientes:lerClientes da loja, com contato e histórico de compras (conector MCP)promocoes:lerCupons de desconto (conector MCP)promocoes:escreverCriar e alterar cupons (conector MCP)analises:lerResumo de vendas, origem das vendas e marketing (conector MCP)mcp:usarUsar esta chave no conector MCP (/api/mcp), dentro dos outros escopos marcados
Códigos de erro
Use o código do erro para decidir como a integração deve responder. Guarde o identificador da requisição ao acionar o suporte.
- 401
chave_ausenteA requisição veio sem chave. - 401
chave_invalidaChave em formato desconhecido ou que não existe. - 401
chave_revogadaA chave foi revogada no painel. - 403
escopo_insuficienteA chave não tem o escopo que a rota exige. - 403
plano_sem_apiChave secreta é do plano Loja Pro. - 403
loja_fora_do_arA loja não está no ar. - 400
parametro_invalidoCampo errado, faltando ou desconhecido. A mensagem diz qual. - 404
nao_encontradoNão existe nesta loja. - 409
conflitoO pedido é válido, mas o estado atual não permite: slug ou SKU já em uso, pedido ainda não pago. - 403
origem_nao_permitida - 403
loja_nao_vende - 422
pedido_invalido - 429
limite_excedidoRequisições demais por minuto. O cabeçalho Retry-After diz quanto esperar. - 500
erro_internoErro do nosso lado. Informe o id da requisição ao suporte. - 502
gateway_recusou - 503
pagamento_a_confirmar