Pular para o conteúdo
Para desenvolvedores

Integre sua loja com IA e API.

Conecte um assistente de IA ou integre seu sistema pela API. Endereços, permissões e formatos para começar.

Conector MCP

Conecte um assistente de IA para consultar e operar a loja por conversa. Use este endereço:

https://lojas.avilaops.com/api/mcp

Adicione 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_loja Ver dados da lojaconsulta
  • atualizar_marca Alterar marca e layoutaltera

Catálogo

  • listar_produtos Listar produtosconsulta
  • obter_produto Ver produtoconsulta
  • listar_categorias Listar categoriasconsulta
  • listar_estoque_baixo Ver estoque baixoconsulta
  • listar_avaliacoes Listar avaliaçõesconsulta
  • criar_produto Criar produtoacrescenta
  • atualizar_produto Alterar produtoaltera
  • atualizar_categoria Alterar categoriaaltera
  • gerar_seo_categoria Gerar e publicar SEO da categoriaaltera
  • gerenciar_fotos_produto Alterar fotos do produtoaltera
  • ajustar_estoque Ajustar estoquealtera
  • moderar_avaliacao Moderar avaliaçãoaltera

Pedidos

  • listar_pedidos Listar pedidosconsulta
  • obter_pedido Ver pedidoconsulta
  • atualizar_status_pedido Alterar status do pedidoaltera
  • emitir_etiqueta_envio Emitir etiqueta de envioaltera

Clientes

  • listar_clientes Listar clientesconsulta
  • obter_cliente Ver clienteconsulta

Promoções

  • listar_cupons Listar cuponsconsulta
  • criar_cupom Criar cupomaltera
  • atualizar_cupom Alterar cupomaltera

Análises

  • resumo_vendas Resumo de vendasconsulta
  • resumo_atribuicao Resumo de origem das vendasconsulta
  • resumo_marketing Resumo 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 o codigo; 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:ler

    A loja dona da chave e os escopos da chave.

  • GET/api/v1/produtoscatalogo:ler

    Catálogo completo, inclusive inativos. Filtros: ativo, categoria, sku, busca, atualizadoDesde.

  • GET/api/v1/produtos/{id}catalogo:ler

    Um produto (id ou slug) com as variações.

  • POST/api/v1/produtosprodutos:escrever

    Cria 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:escrever

    Edita o cadastro (nome, slug, marca, descrições, categoria, ativo, destaque). Preço e estoque são de /ofertas.

  • PATCH/api/v1/ofertascatalogo:escrever

    Preç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:ler

    Saldos físicos e reservados por local. Filtros: varianteId, local. Paginação pagina/porPagina.

  • GET/api/v1/estoque/razaocatalogo:ler

    Razão imutável de alterações de saldo. Filtros: varianteId, local, comandoId. Sequência retornada como string decimal.

  • POST/api/v1/estoque/movimentosestoque:escrever

    Entrada, saída ou transferência imediata entre locais. Exige Idempotency-Key; nunca consome unidades reservadas.

  • GET/api/v1/pedidospedidos:ler

    Pedidos. Filtros: status, canal, criadoDesde, atualizadoDesde.

  • GET/api/v1/pedidos/{id}pedidos:ler

    Um pedido (id ou referência) com os itens.

  • PATCH/api/v1/pedidos/{id}pedidos:escrever

    Avanç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:ler

    Dados públicos da loja, para um front próprio. Aceita chamada do navegador.

  • GET/api/v1/vitrine/produtosvitrine:ler

    Produtos ativos, como a vitrine mostra. Filtros: busca, categoria, destaque, ordem.

  • GET/api/v1/vitrine/produtos/{id}vitrine:ler

    Um 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:ler

    Opçõ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:comprar

    Confere 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:comprar

    Fecha 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:comprar

    Andamento 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.criado Pedido registrado, ainda aguardando pagamento ou já aprovado no cartão
  • pedido.pago Pagamento confirmado e estoque baixado
  • pedido.recusado Pagamento recusado; a reserva de estoque foi liberada
  • pedido.em-separacao A loja começou a separar
  • pedido.enviado Pedido despachado, com transportadora e rastreio quando houver
  • pedido.entregue Pedido marcado como entregue
  • pedido.cancelado Pedido 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:ler Dados da loja (nome, plano, endereço da vitrine)
  • catalogo:ler Produtos e variações, inclusive inativos, com estoque
  • catalogo:escrever Preço e estoque por SKU (o que o ERP sincroniza)
  • estoque:escrever Registrar entradas, saídas e transferências imediatas entre locais
  • pedidos:ler Pedidos com cliente, itens, valores e rastreio
  • vitrine:ler O que a vitrine pública mostra: produtos ativos e dados da loja
  • vitrine:comprar Fechar compra pelo site ou app próprio: criar o pedido e a cobrança e consultar o status
  • produtos:escrever Criar produto e editar o cadastro (nome, descrição, categoria, ativo)
  • pedidos:escrever Avançar o pedido: separar, enviar com rastreio, entregar, cancelar
  • loja:escrever Marca, cores e layout da loja (conector MCP)
  • clientes:ler Clientes da loja, com contato e histórico de compras (conector MCP)
  • promocoes:ler Cupons de desconto (conector MCP)
  • promocoes:escrever Criar e alterar cupons (conector MCP)
  • analises:ler Resumo de vendas, origem das vendas e marketing (conector MCP)
  • mcp:usar Usar 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.

  • 401chave_ausenteA requisição veio sem chave.
  • 401chave_invalidaChave em formato desconhecido ou que não existe.
  • 401chave_revogadaA chave foi revogada no painel.
  • 403escopo_insuficienteA chave não tem o escopo que a rota exige.
  • 403plano_sem_apiChave secreta é do plano Loja Pro.
  • 403loja_fora_do_arA loja não está no ar.
  • 400parametro_invalidoCampo errado, faltando ou desconhecido. A mensagem diz qual.
  • 404nao_encontradoNão existe nesta loja.
  • 409conflitoO pedido é válido, mas o estado atual não permite: slug ou SKU já em uso, pedido ainda não pago.
  • 403origem_nao_permitida
  • 403loja_nao_vende
  • 422pedido_invalido
  • 429limite_excedidoRequisições demais por minuto. O cabeçalho Retry-After diz quanto esperar.
  • 500erro_internoErro do nosso lado. Informe o id da requisição ao suporte.
  • 502gateway_recusou
  • 503pagamento_a_confirmar