# Svizia Pay — guia de integração para assistentes de IA

Gateway de Pix com conta nominal no CPF/CNPJ do lojista. REST + JSON. Base: `https://sviziapay.com/api/v1`.
Especificação completa (OpenAPI 3.1): https://sviziapay.com/api/v1/openapi.json — documentação para pessoas: https://sviziapay.com/docs
Sandbox (só chave svp_test_, nada real): `https://sviziapay.com/sandbox/api/v1`. Kits prontos de um arquivo: https://sviziapay.com/sdk/sviziapay.mjs (Node), https://sviziapay.com/sdk/sviziapay.py (Python), https://sviziapay.com/sdk/SviziaPay.php (PHP), com `verifyWebhook`. Postman: https://sviziapay.com/api/v1/postman.json

## Regras que não podem faltar
1. **Valores sempre em centavos inteiros** (R$ 19,90 = 1990). Nunca mande decimal.
2. Autenticação: `Authorization: Bearer <chave>` (ou `x-api-key`). `svp_test_…` = teste (nada real), `svp_live_…` = produção. A chave fica só no servidor, nunca no navegador.
3. Mande `Idempotency-Key` (ex.: o id do pedido) em todo POST que cria algo.
4. **Libere o pedido pelo webhook `charge.paid`**, conferindo a assinatura. Não confie no retorno do navegador.
5. O mesmo evento pode chegar mais de uma vez: processe pelo `data.id` só uma vez.
6. **Anti-MED:** a cobrança e o `charge.paid` trazem `risk` (`{ score, level: low|medium|high, reasons }`). Com `level` "medium", segure a entrega e confirme com o comprador (ex.: quem pagou não é quem comprou). Risco alto = 403 na criação. Depois de entregar, chame `POST /pix/{id}/delivery`.
7. Erros vêm como `{ "error": "mensagem em português" }`; 429 = espere e repita; 502 = repita com a mesma Idempotency-Key.

## Permissões da chave
pix (cobranças, saldo, verificação de CPF) · withdraw (saque para o próprio CPF/CNPJ) · payments (pagar contas) · shops (subcontas).

## Fluxo de checkout
1. Servidor: `POST /pix/cashin` com `{ value, description, external_id, payer: { name, document }, buyer: { ip, user_agent } }` (na produção `payer` é obrigatório; `buyer` ajuda o anti-MED — num bot, mande `buyer: { id: "<id do usuário no Telegram>" }`).
2. Mostre `qr_code_base64` (imagem) e `qr_code` (copia e cola), ou mande o cliente para `https://sviziapay.com/p/<id>`.
3. Webhook `charge.paid` → marque o pedido como pago e, ao entregar, chame `POST /pix/<id>/delivery` (ex.: "acesso ao grupo liberado para @fulano"): é a prova que a defesa automática de MED usa. Para conferir sem webhook: `GET /pix/<id>` (status `paid`).
4. Teste: `POST /pix/<id>/simulate` com a chave de teste dispara o `charge.paid`.

```bash
curl https://sviziapay.com/api/v1/pix/cashin \
  -H "Authorization: Bearer $SVIZIA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{"value":1990,"description":"Curso","external_id":"pedido-123","payer":{"name":"Ana Souza","document":"39053344705"}}'
```

Resposta: `{ id, status, value, fee, net, qr_code, qr_code_base64, external_id, payer, paid_by, end_to_end_id, refunded, test, expires_at, paid_at, created_at }`.
Status: pending, paid, expired, cancelled, refunded, med (valor preso por denúncia), returned (MED aceito).

## Endpoints
| Método | Caminho | Permissão | Para quê |
|---|---|---|---|
| POST | /pix/cashin | pix | Criar cobrança (aceita `shop_id` e `splits` com a permissão shops) |
| GET | /pix/{id} | pix | Consultar cobrança |
| GET | /charges?status=&external_id=&before=&limit= | pix | Listar (paginar com `before` = created_at da última) |
| POST | /pix/{id}/refund | pix | Devolver a quem pagou (corpo opcional {"value": centavos} = parcial) |
| POST | /pix/{id}/recover | pix | Pix vencido: `{ discount_percent?: 0-50, expires_in_minutes? }` → UM Pix novo para a mesma pessoa + `message` pronta e `whatsapp_url` (chamar de novo devolve o mesmo) |
| POST | /pix/{id}/simulate | pix | Só teste: marcar como pago |
| POST | /pix/{id}/delivery | pix | `{ how, details?, url?, at? }` — informar a entrega (prova para a defesa automática de MED) |
| POST | /subscriptions | pix | Assinatura por Pix: `{ value, interval_days: 7|30|90|365, description, payer{name,document,email}, external_id?, webhook_url? }` → assinatura + 1º Pix em `charge` |
| GET | /subscriptions, /subscriptions/{id ou external_id} | pix | pending, active, past_due, cancelled, incomplete |
| POST | /subscriptions/{id}/cancel | pix | `{ immediately? }` — padrão: no fim do período pago |
| GET | /balance | pix | `{ available, blocked, test }` |
| POST | /withdrawals | withdraw | `{ value }` — saque só para o próprio CPF/CNPJ |
| GET | /withdrawals, /withdrawals/{id} | withdraw | pending, processing, done, failed |
| POST | /payments/preview | payments | `{ kind: pix_qr|pix_key|bill, target }` → quem recebe e quanto (não paga) |
| POST | /payments | payments | `{ kind, target, value, description? }` → paga do saldo |
| GET | /payments, /payments/{id} | payments | processing, done, failed |
| POST | /shops | shops | Criar subconta (cadastro completo da loja, conta no CPF/CNPJ dela) |
| GET | /shops, /shops/{id} | shops | review, active, rejected, blocked |
| GET | /shops/{id}/balance, /transactions, /withdrawals | shops | Dinheiro da subconta |
| POST | /shops/{id}/withdraw | shops + withdraw | Saque da loja para o CPF/CNPJ dela |
| POST | /kyc/verify | pix | `{ document, name, external_id? }` → Pix pequeno para confirmar o dono do documento |
| GET | /kyc/verify/{id} | pix | verified, mismatch, paid_unknown, expired |

## Assinaturas
Cada ciclo gera um Pix novo 3 dias antes de vencer (e-mail ao assinante + webhook `subscription.renewal` com `charge.qr_code`). Eventos: subscription.active (libere), subscription.renewal, subscription.reminder (stage d1|d0|last, message, whatsapp_url), subscription.renewed, subscription.past_due (3 dias de carência), subscription.cancel_scheduled, subscription.cancelled (tire o acesso), subscription.auto_pay (Pix Automático: auto_pay.status active|refused|cancelled|expired). Com Pix Automático ativo (onde a instituição oferece) a renovação é debitada sozinha: subscription.renewal vem com auto_debit true, não mande o Pix. Falhou = volta para o Pix de cada ciclo. O assinante cancela em `manage_url`.

## Subcontas e divisão
`shop_id` (id ou external_ref) faz a loja receber; `splits: [{ shop_id: "parent" | id, percent | amount }]` (até 5) divide na hora, direto na conta de cada um. Eventos das lojas chegam no webhook da plataforma com `shop_id`.

## Webhooks
Toda cobrança paga traz `receipt_url` (comprovante em PDF para mandar ao comprador). Eventos: charge.paid, charge.expired, charge.recovery (Pix vencido ganhou um Pix novo: `data = { original_id, external_id, discount_percent, charge, payment_url, message, whatsapp_url }` — o bot manda `message` no Telegram/WhatsApp), charge.reminder (Pix com vencimento longo faltando menos de 24 h: stage, message, whatsapp_url, charge), charge.refunded, charge.med, charge.med_released, charge.med_returned, withdrawal.done, withdrawal.failed, payment.done, payment.failed, kyc.verified, shop.status.
Corpo: `{ id, event, created_at, data }` (data = o mesmo objeto do GET). Responda 2xx em até 10 s.
Cabeçalho `X-SviziaPay-Signature: t=<unix>,v1=<hex>`; confira `HMAC-SHA256(segredo_whsec, t + "." + corpo_cru) == v1` com comparação de tempo constante, usando o corpo cru (antes do JSON.parse).

```js
import crypto from "node:crypto";
const [t, v1] = req.headers["x-sviziapay-signature"].split(",").map((p) => p.split("=")[1]);
const exp = crypto.createHmac("sha256", process.env.SVIZIA_WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(exp), Buffer.from(v1))) return res.status(401).end();
```

## MCP
`https://sviziapay.com/api/mcp/loja` com `Authorization: Bearer svp_…` (ou `/api/mcp/loja/<chave>`). Chave de teste = dados de teste. Nunca saca nem devolve.
- Conta: account (situação, taxas, limites, saúde, etapa do cadastro), ranking
- Vendas: balance, sales_report, charges, charge, create_charge, cancel_charge, statement, withdrawals, payments_out, med_status, buyer_claims, subscriptions
- Configurar: products, save_product (bumps, upsell, recurring_days, afiliados, recuperação), coupons, save_coupon, coupon_active, create_subscription, cancel_subscription, coproductions, affiliates
- Inteligência: funnel, buyers, opportunities, set_goal, api_requests, cash_forecast, ab_test
- Regras e proteção: rules, save_automation, test_risk_rule, save_risk_rule, blocked_payers, block_payer, release_delivery
- Integração: integration_status, webhook_deliveries, charge_events, test_webhook, redeliver_webhooks, save_webhook_endpoint, webhook_events, partner_info, simulate_payment (só teste)
- Pós-venda: add_delivery, answer_claim, recover_charge
- Prompts: configurar_minha_loja, diagnosticar_integracao, onde_estou_perdendo_vendas, resumo_da_semana

App que só roda MCP local (stdio): `npx -y sviziapay-mcp` com `SVIZIAPAY_KEY=svp_…`.

Plataforma parceira: `https://sviziapay.com/api/mcp/parceiro` com `Authorization: Bearer svpp_…`. Só leitura: overview, sellers, sales, earnings, seller_health, integration_guide.

## Migrar da PushinPay (mesmos caminhos e campos)
Base `https://sviziapay.com/api/compat/pushinpay` no lugar de `https://api.pushinpay.com.br`, token = chave svp_ com a permissão pix.
- POST /api/pix/cashIn {value (centavos, mín. 50), description?, webhook_url?, payer? {name, document} (o Asaas exige), buyer_id?} → {id, status: "created", value, qr_code, qr_code_base64, webhook_url, ...}
- GET /api/transactions/{id} → status created | paid | canceled | refunded, end_to_end_id, payer_name, payer_national_registration
- POST /api/transactions/{id}/refund · GET /api/balance → {amount, blocked_balance}
Webhook: JSON com os campos da PushinPay (sem envelope), assinado em X-SviziaPay-Signature. Taxa da plataforma: split_rules.

## Migrar da SyncPay
Base `https://sviziapay.com/api/compat/syncpay` no lugar de `https://api.syncpayments.com.br`. POST /api/partner/v1/auth-token {client_id, client_secret: svp_…} → {access_token (a própria chave), token_type: "Bearer"}. POST /api/partner/v1/cash-in {amount (reais), description?, webhook_url?, client? {name, cpf, email, phone}, split? [{percentage, user_id}]} → {message, pix_code, identifier}. GET /api/partner/v1/transaction/{identifier} → {data:{reference_id, amount, status: pending|completed|expired|refunded, pix_code}}. POST /transaction/{id}/refund, GET /balance → {balance: "0.00"}, GET /profile, GET|POST /webhooks {title, url} (sem webhook_url no cash-in o aviso vai para o registrado). Aviso: {data:{id, identifier, status: "completed", amount, final_amount}} com Authorization: Bearer <token do registro>.

## Migrar da NexusPag / Atenas Pay
Base `https://sviziapay.com/api/compat/nexuspag` (ou `/api/compat/atenaspay`), cabeçalho x-api-key: svp_…. POST /api/pix/create {amount (reais), description?, external_id? (idempotência), webhook_url?, customer? {name, document}, split? [{user_id, amount}]} → 201 {success, transaction:{id, txid, external_id, pix_copia_cola, qr_code_base64, status}}. GET /api/pix/{id ou external_id}, GET /api/wallet. Aviso: {event: "payment.confirmed"|"refund.completed", transaction_id, status, amount, net_amount, fee} com x-webhook-signature t=,v1=HMAC-SHA256(segredo do webhook, "t.corpo").

## Migrar da WiinPay
Base `https://sviziapay.com/api/compat/wiinpay`. POST /payment/create {api_key: svp_…, value (reais), name, email, document?, description?, webhook_url?, split? {value, user_id}} → 201 {data:{qr_code, paymentId}}. GET /payment/list/{paymentId} (Bearer) → {data:{paymentId, status: PENDING|PAID|EXPIRED|REFUNDED, value}}. Aviso: {data:{paymentId, status: "PAID", value}}.

Em todas: chave de teste = Pix de teste; também em `https://sviziapay.com/sandbox/api/compat/…`; o aviso no formato do gateway vai só no webhook_url da cobrança (os outros endereços do lojista recebem o formato da Svizia Pay).

## Plataformas parceiras (taxa por venda)
Plataforma que cria Pix na conta de vários vendedores: chave de API do VENDEDOR em Authorization + chave da plataforma em `X-Partner-Key: svpp_…` no POST /pix/cashin (ou no cashIn compatível). Cada Pix pago leva a taxa da plataforma pelo split, direto na conta dela. Chave errada = 401. Também aceita a taxa no corpo, no formato da PushinPay: `split_rules: [{ value: <centavos>, account_id: <id da conta da plataforma na Svizia Pay> }]` (só conta parceira, até a taxa combinada; senão 400), em /api/v1/pix/cashin e no cashIn compatível.

## Devolução parcial e Central do comprador
POST /pix/{id}/refund com {"value": centavos} devolve só uma parte. Compradores podem abrir pedido em https://sviziapay.com/ajuda (evento charge.claim): responda ou devolva antes de virar MED.
