# Stone Vendas — how to use (mcp.ai)

Stone acquirer (card machine) sales via the Conciliação API, read-only. Lists transactions for a period with date and time, gross and net amounts, payment method, card brand, capture type, installments and status, and consolidates totals by payment method, brand or day. Also covers cancellations, chargebacks, the receivables schedule and the settlements deposited into the account. Each StoneCode is one connection, and the same key works for every StoneCode under the same tax id. Auth uses the key the account holder creates in the Stone portal, under authentication keys. Complements Stone Pagamentos, which reads the bank account through Open Finance.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_stone_vendas?ms=1788372720000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `stone_vendas_arquivo`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/stone-vendas`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/stone-vendas/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/stone-vendas/arquivo` — Arquivo de conciliação completo de um único dia, já convertido de XML para JSON, com todos os blocos (vendas, liquidações na conta, agenda prevista, eventos financeiros, pagamentos e posição de cartei
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/cancelamentos` — Cancelamentos, chargebacks e reapresentações de chargeback da conta Stone no período, com o NSU da venda de origem, valor, datas e motivo. A Stone fecha um arquivo por dia e o do dia só fica pronto de
  - body: { data_inicio?: string, data_fim?: string, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/contas` — Lista os StoneCodes (estabelecimentos) Stone conectados neste install, com id e apelido.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/limpar/cache` — Força a Stone a regerar o arquivo de conciliação do período, descartando o extrato que ela mantém em cache. Use quando os números não baterem com o painel da Stone. Não altera nada da conta, não move 
  - body: { data_inicio?: string, data_fim?: string, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/liquidacoes` — Liquidações da Stone no período, o que foi efetivamente depositado, com valor total e a conta bancária favorecida. É a ponta que fecha com o extrato bancário. A Stone fecha um arquivo por dia e o do d
  - body: { data_inicio?: string, data_fim?: string, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/listar` — Lista as vendas do adquirente Stone no período, uma linha por transação capturada, com data e hora, valor bruto e líquido, forma de pagamento (crédito, débito, pré-pago, voucher, boleto), bandeira, ca
  - body: { data_inicio?: string, data_fim?: string, forma_pagamento?: string, bandeira?: string, status?: string, limite?: integer, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/pix` — Vendas por Pix na maquininha Stone no período, com data e hora, valor, taxa, status (paga ou cancelada), terminal, chave Pix, e2e id e dados do pagador. A Stone entrega o Pix num arquivo separado e as
  - body: { data_inicio?: string, data_fim?: string, apenas_maquininha?: boolean, status?: string, limite?: integer, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/recebiveis` — Agenda de recebíveis Stone: as parcelas ainda não pagas com a data prevista de pagamento, detalhadas e totalizadas por data. A Stone fecha um arquivo por dia e o do dia só fica pronto depois das 5h do
  - body: { data_inicio?: string, data_fim?: string, account?: string }
- `POST https://api.mcp.ai/api/stone-vendas/resumo` — Totais consolidados das vendas Stone no período, o equivalente ao Resumo de vendas do painel. Agrupa por forma de pagamento, bandeira, dia, status, tipo de captura ou terminal, e devolve quantidade, v
  - body: { data_inicio?: string, data_fim?: string, agrupar_por?: string, incluir_pix?: boolean, account?: string }

## Example prompts
- "What was the Stone sales summary last month by payment method?"
- "List last week's Stone sales by card brand"
- "How much am I due to receive from Stone in the coming days?"
- "Were there any chargebacks or cancellations on Stone this month?"
- "How much came in through Pix on the Stone card machine last week?"

## More
- Page: https://mcp.ai/stone_vendas
- Agent spec (llms.txt): https://mcp.ai/stone_vendas/llms.txt
- Postman collection: https://mcp.ai/stone_vendas/postman.json