Seu sistema.
O Pix da sua loja.

Da sua loja à primeira chamada.

A API key permite criar e consultar vendas da própria loja. Use-a somente no backend ou no processo local do MCP. O portal permite substituir ou desativar a chave; a anterior deixa de funcionar imediatamente.

Escolha sua linguagem.

O mesmo fluxo de criação e consulta em oito linguagens. Baixe o arquivo, configure as variáveis de ambiente e execute no seu servidor.

Seleção: oito linguagens mais usadas por contribuidores mensais no GitHub Octoverse 2025 ↗. Shell está representado por Bash. Esse recorte não é um ranking universal de uso.

// Node.js 22.18+ (TypeScript nativo). Execute somente no servidor.
const key: string | undefined = process.env.PIX_API_KEY;
const id: string | undefined = process.env.PIX_SALE_ID;
const operation: string | undefined = process.argv[2];
if (!key || !id || !/^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{21}$/.test(id))
  throw new Error("Configure PIX_API_KEY e PIX_SALE_ID (21 caracteres Crockford).");
if (operation !== "create" && operation !== "get") throw new Error("Use: node sale.ts create|get");

// Persista ID e corpo antes do POST; preserve ambos em toda retentativa.
const body = { sale_id: id, amount_cents: 8990, reference: "Pedido 1042" };
const url = "https://pixlojista.com.br/v1/integration/sales";
const response = await fetch(operation === "create" ? url : `${url}/${id}`, {
  method: operation === "create" ? "POST" : "GET",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: operation === "create" ? JSON.stringify(body) : undefined,
  redirect: "error",
  signal: AbortSignal.timeout(15000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data: unknown = await response.json();
process.stdout.write(JSON.stringify(data, null, 2) + "\n");
export {};

node sale.ts create

node sale.ts get

Duas operações. A mesma venda.

Base de produção: https://pixlojista.com.br/v1. Todas as chamadas usam HTTPS e Authorization: Bearer SUA_API_KEY.

Idempotência: nova venda retorna HTTP 201; repetição idêntica retorna 200; mesmo ID com dados diferentes retorna 409. Preserve também os campos opcionais nas retentativas.

{
  "sale": {
    "sale_id": "0123456789ABCDEFGHJKM",
    "status": "ABERTA",
    "current_version": 1
  },
  "brcode": "<Pix Copia e Cola retornado pela API>",
  "qr_png_base64": "<PNG codificado em base64>"
}

O exemplo acima é abreviado; não é um QR válido. Leia sale.status para acompanhar a venda, brcode para copiar e qr_png_base64 para mostrar a imagem usando o prefixo data:image/png;base64,.

Estados possíveis: ABERTA, PAGA, CONFIRMADA_MANUAL, NAO_CONCILIADA, EXPIRADA, CANCELADA e ESTORNADA.

Seu sistema pode receber as mudanças.

Webhooks são opcionais. No portal, salve uma URL HTTPS pública e gere o segredo de assinatura. O receptor recebe sale.created e sale.updated das vendas da loja, inclusive as criadas no terminal.

1. Leia X-Pix-Timestamp (Unix, segundos) e rejeite diferença de mais de cinco minutos.
2. Calcule HMAC-SHA256 hexadecimal de timestamp + "." + corpo HTTP original com seu segredo. Compare com X-Pix-Signature em tempo constante, antes de confiar no conteúdo.
3. Persista o evento, deduplicando por event_id, e responda 2xx. Não serialize o JSON novamente para validar a assinatura.
4. Eventos podem chegar fora de ordem. Consulte a venda para obter o estado atual. São até seis tentativas de entrega, com espera crescente.

O corpo inclui event_id, type, merchant_id, sale_id, status, current_version, amount_cents, evidence, occurred_at e brcode. O segredo de webhook é diferente da API key.

Conecte seu cliente MCP.

O conector local usa a mesma API key e as mesmas vendas. Funciona por stdio, com Node.js 20 ou superior e sem dependências npm. O cliente MCP precisa permitir executar um processo local.

1. Extraia o ZIP. Ele contém server.mjs e README.md.
2. Configure PIX_API_KEY no ambiente privado herdado pelo processo Node, ou no gerenciador de segredos do seu cliente.
3. Adicione a configuração abaixo, trocando o caminho pelo local onde você extraiu o arquivo. O formato pode variar entre clientes.

{
  "mcpServers": {
    "pixlojista": {
      "command": "node",
      "args": [
        "/CAMINHO/ABSOLUTO/server.mjs"
      ]
    }
  }
}

Exemplo de pedido ao assistente: “Crie uma venda de R$ 89,90 para o pedido 1042. Gere e guarde um sale_id único antes de chamar a ferramenta. Depois consulte o estado desse mesmo ID.”

Esta versão não oferece uma URL MCP remota. Uma conexão que aceita somente servidores HTTP não executa este conector. Criar a venda ou exibir o QR não confirma o recebimento.

Trate respostas e retentativas.

Erros retornam error, message e request_id. Guarde o identificador da requisição para diagnóstico, sem registrar sua chave.