{"openapi":"3.0.3","info":{"title":"VPN Pay API","version":"1.0.0","description":"API pública da VPN Pay. Autenticação por chave de API (Bearer). Valores sempre em centavos. Operações financeiras exigem o cabeçalho Idempotency-Key. Todas as respostas usam o mesmo envelope, exceto /openapi.json, que devolve o documento OpenAPI puro. Quando provider_connection_id não é enviado em cobranças e repasses, o Smart Routing escolhe a conexão elegível. As listas devolvem os registros mais recentes e não aceitam paginação nem filtros nesta versão.","contact":{"name":"Suporte VPN Pay"}},"servers":[{"url":"https://vpnpay.com.br/api/public/v1","description":"Endereço oficial"}],"tags":[{"name":"Connect","description":"Envio e status WhatsApp com credencial protegida"},{"name":"Payments","description":"Cobranças Pix (Pix In)"},{"name":"Payouts","description":"Repasses Pix (Pix Out)"},{"name":"Refunds","description":"Devoluções totais e parciais"},{"name":"Merchants","description":"Unidades (lojas) e mapeamento do código externo"},{"name":"Recipients","description":"Recebedores e saldo por recebedor"},{"name":"Balances","description":"Saldos do cliente"},{"name":"Reconciliation","description":"Execuções e resultados de conciliação"},{"name":"Webhooks","description":"Avisos assinados enviados ao seu sistema"},{"name":"Deliveries","description":"Entregas com parceiro logístico custeadas pelo dinheiro do próprio pedido daquela unidade"},{"name":"Fleet Invoices","description":"Faturas do complemento dos ciclos de repasse da frota"},{"name":"Meta","description":"Documentação e verificação de conectividade"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer vpnp_live_<prefixo>.<segredo> — o segredo aparece uma única vez."}},"schemas":{"Envelope":{"type":"object","description":"Envelope usado em toda resposta da API.","properties":{"success":{"type":"boolean"},"data":{},"error":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"request_id":{"type":"string","format":"uuid"}},"required":["success","data","error","code","message","request_id"]},"ErrorEnvelope":{"type":"object","description":"Envelope de erro. success sempre false e data sempre null.","properties":{"success":{"type":"boolean","example":false},"data":{"type":"object","nullable":true,"example":null,"description":"Sempre null em erro."},"error":{"type":"string","description":"Mesmo valor de code, mantido por compatibilidade."},"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","idempotency_conflict","unprocessable","rate_limited","internal_error"]},"message":{"type":"string","description":"Texto legível, seguro para log. Nunca contém segredo."},"request_id":{"type":"string","format":"uuid"}},"required":["success","data","error","code","message","request_id"]},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["payment"]},"status":{"type":"string","enum":["CREATED","PENDING","PROCESSING","PAID","FAILED","CANCELED","EXPIRED","UNKNOWN","RECONCILIATION_REQUIRED"]},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"currency":{"type":"string","example":"BRL"},"merchant_id":{"type":"string","format":"uuid","nullable":true},"recipient_id":{"type":"string","format":"uuid","nullable":true},"external_reference":{"type":"string","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"br_code":{"type":"string","nullable":true,"description":"Pix copia e cola"},"qr_code":{"type":"string","nullable":true,"description":"Imagem do QR (base64 ou URL)"},"provider_connection_id":{"type":"string","format":"uuid","nullable":true}},"example":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PENDING","amount":4990,"currency":"BRL","external_reference":"pedido-1042","paid_at":null,"expires_at":"2026-09-12T22:30:00.000Z","created_at":"2026-09-12T22:00:00.000Z","br_code":"00020126…5204000053039865802BR","qr_code":"data:image/png;base64,iVBORw0K…"}},"PaymentCreate":{"type":"object","required":["amount","payer"],"description":"Dois modos. PIX (padrão, retrocompatível): devolve br_code/qr_code. CARD: exige checkout HOSTED e devolve checkout_url, página segura do provedor onde o cliente digita o cartão. A API NUNCA aceita número, CVV, validade ou token de cartão (400 CARD_DATA_NOT_ACCEPTED). O retorno do navegador não comprova pagamento: aguarde payment.paid (captura confirmada pelo provedor).","properties":{"method":{"type":"string","enum":["PIX","CARD"],"default":"PIX"},"checkout":{"type":"string","enum":["HOSTED"],"description":"Obrigatório quando method=CARD."},"installments":{"type":"integer","minimum":1,"default":1,"description":"Somente CARD. Limitado pela política de parcelas e pelo provedor."},"success_url":{"type":"string","format":"uri","description":"Somente CARD, https. Destino após o pagamento; não vale como confirmação."},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"currency":{"type":"string","default":"BRL"},"payer":{"type":"object","required":["name","document"],"properties":{"name":{"type":"string"},"document":{"type":"string","description":"CPF ou CNPJ"},"email":{"type":"string","format":"email","nullable":true,"description":"Obrigatório quando method=CARD."}}},"merchant_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"external_reference":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"provider_connection_id":{"type":"string","format":"uuid","description":"Opcional. Quando ausente, o Smart Routing escolhe a conexão elegível."},"expires_in_minutes":{"type":"integer","minimum":5,"default":60}},"example":{"amount":4990,"currency":"BRL","external_reference":"pedido-1042","expires_in_minutes":30,"payer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}},"examples":{"pix":{"amount":4990,"external_reference":"pedido-1042","payer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}},"card":{"method":"CARD","checkout":"HOSTED","installments":1,"amount":5890,"merchant_id":"0f1e2d3c-4b5a-4968-8776-655443322110","external_reference":"pedido-1043","success_url":"https://loja.exemplo.com/pedido/1043","payer":{"name":"Maria Souza","document":"12345678909","email":"maria@exemplo.com"}}}},"Payout":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["payout"]},"status":{"type":"string","enum":["CREATED","PENDING","PROCESSING","DONE","FAILED","CANCELED","BLOCKED","UNKNOWN","RECONCILIATION_REQUIRED"]},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"currency":{"type":"string"},"recipient_id":{"type":"string","format":"uuid"},"merchant_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"PayoutCreate":{"type":"object","required":["recipient_id","pix_key_id","amount"],"properties":{"recipient_id":{"type":"string","format":"uuid"},"pix_key_id":{"type":"string","format":"uuid","description":"Chave Pix ativa do recebedor"},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"currency":{"type":"string","default":"BRL"},"merchant_id":{"type":"string","format":"uuid"},"provider_connection_id":{"type":"string","format":"uuid"}},"example":{"recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","pix_key_id":"77aa1b2c-3d4e-4f50-9a6b-7c8d9e0f1a2b","amount":25000}},"Refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["refund"]},"status":{"type":"string","enum":["CREATED","PENDING","PROCESSING","DONE","FAILED","CANCELED","UNKNOWN","RECONCILIATION_REQUIRED"]},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"currency":{"type":"string"},"payment_id":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["CUSTOMER_CANCEL_BEFORE_DISPATCH","CUSTOMER_CANCEL_AFTER_DISPATCH","MERCHANT_OUT_OF_STOCK","MERCHANT_CANCEL_AFTER_PICKUP","DRIVER_NO_SHOW","DRIVER_FAILURE","PLATFORM_ERROR","FRAUD","DUPLICATE_PAYMENT"]},"created_at":{"type":"string","format":"date-time"}}},"RefundCreate":{"type":"object","required":["payment_id","amount","reason","liabilities"],"properties":{"payment_id":{"type":"string","format":"uuid"},"amount":{"type":"integer","minimum":1,"description":"Igual ao pagamento = total; menor = parcial"},"reason":{"type":"string","enum":["CUSTOMER_CANCEL_BEFORE_DISPATCH","CUSTOMER_CANCEL_AFTER_DISPATCH","MERCHANT_OUT_OF_STOCK","MERCHANT_CANCEL_AFTER_PICKUP","DRIVER_NO_SHOW","DRIVER_FAILURE","PLATFORM_ERROR","FRAUD","DUPLICATE_PAYMENT"]},"liabilities":{"type":"array","minItems":1,"description":"Quem assume o valor. A soma precisa ser exatamente igual a amount.","items":{"type":"object","required":["party","amount"],"properties":{"party":{"type":"string","enum":["MERCHANT","DRIVER","PARTNER","OTHER","PLATFORM"]},"amount":{"type":"integer","minimum":1,"description":"Valor inteiro em centavos. R$ 12,34 = 1234."},"recipient_id":{"type":"string","format":"uuid","description":"Obrigatório quando party não é PLATFORM"},"merchant_id":{"type":"string","format":"uuid"}}}},"notes":{"type":"string"}},"example":{"payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","amount":1500,"reason":"MERCHANT_OUT_OF_STOCK","liabilities":[{"party":"MERCHANT","amount":1500,"recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f"}]}},"Recipient":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["recipient"]},"type":{"type":"string","enum":["MERCHANT","DRIVER","PARTNER","OTHER"]},"legal_name":{"type":"string"},"display_name":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","UNDER_REVIEW","ACTIVE","BLOCKED","REJECTED"]},"kyc_status":{"type":"string","enum":["NOT_STARTED","PENDING","UNDER_REVIEW","APPROVED","REJECTED"]},"external_reference":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"RecipientCreate":{"type":"object","required":["type","legal_name"],"properties":{"type":{"type":"string","enum":["MERCHANT","DRIVER","PARTNER","OTHER"]},"legal_name":{"type":"string"},"display_name":{"type":"string"},"document_type":{"type":"string","enum":["CPF","CNPJ"]},"document_number":{"type":"string","description":"Validado com dígito verificador; único por cliente"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"external_reference":{"type":"string","description":"Código do recebedor no seu sistema; único por cliente"},"merchant_id":{"type":"string","format":"uuid","description":"Obrigatório para chave SELECTED: unidade autorizada à qual o cadastro fica ligado"}}},"Merchant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["merchant"]},"name":{"type":"string"},"external_reference":{"type":"string","description":"Código da loja no seu sistema"},"status":{"type":"string","enum":["ACTIVE","SUSPENDED","CLOSED","INACTIVE","ARCHIVED"]},"recipient_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"0b6f6a3e-1c2d-4e5f-8a9b-1234567890ab","object":"merchant","name":"Loja Centro (exemplo)","external_reference":"LOJA-001","status":"ACTIVE","recipient_id":null,"created_at":"2026-10-01T12:00:00Z"}},"MerchantCreate":{"type":"object","required":["name","external_reference"],"properties":{"name":{"type":"string","maxLength":200},"external_reference":{"type":"string","maxLength":120,"description":"Único por cliente (409 se repetido)"},"recipient_id":{"type":"string","format":"uuid","description":"Recebedor do mesmo cliente"}}},"MerchantUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"recipient_id":{"type":"string","format":"uuid"}},"description":"status, tenant_id e external_reference não podem ser alterados pela API (400)."},"Balance":{"type":"object","properties":{"account":{"type":"string","description":"Conta do razão (ex.: RECIPIENT:<id>)"},"currency":{"type":"string"},"available":{"type":"integer","minimum":0,"description":"Único saldo sacável"},"pending":{"type":"integer","minimum":0},"blocked":{"type":"integer","minimum":0},"receivable":{"type":"integer","minimum":0,"description":"A receber — nunca sacável"}}},"WebhookEvent":{"type":"object","description":"Corpo enviado ao seu endereço de aviso. Entrega at-least-once: deduplique pelo id do evento.","properties":{"id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid","description":"Mesmo valor de id; use para deduplicar."},"type":{"type":"string","enum":["payment.created","payment.paid","payment.failed","payment.settled","payment.chargeback","refund.created","refund.completed","refund.failed","payout.created","payout.completed","payout.failed","payout.blocked","recipient.updated","delivery.requested","delivery.quoted","delivery.charge_pending","delivery.authorized","delivery.failed","delivery.dispatched","delivery.dispatch_pending","delivery.status_changed","delivery.canceled","fleet_invoice.created","fleet_invoice.charge_available","fleet_invoice.paid","connect.message.received","connect.message.status","connect.message.failed"]},"created_at":{"type":"string","format":"date-time"},"delivery_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid","description":"Cliente dono da operação."},"merchant_id":{"type":"string","format":"uuid","nullable":true,"description":"Unidade comercial de origem, quando houver. Use para roteamento interno — nunca o domínio."},"data":{"type":"object","additionalProperties":true}},"required":["id","event_id","type","created_at","tenant_id","data"],"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.paid","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PAID","amount":4990,"external_reference":"pedido-1042"}}},"FleetInvoice":{"type":"object","description":"Fatura do complemento de um ciclo de repasse da frota. Valores em centavos. original_amount é o valor congelado no fechamento; remaining_amount é o saldo em aberto e vale 0 na fatura quitada. amount_due é igual a remaining_amount.","properties":{"id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string","nullable":true,"example":"FAT-2026-00002"},"status":{"type":"string","enum":["OPEN","OVERDUE","IN_REVIEW","PAID","FUNDED","PAYING","SETTLED"]},"status_label":{"type":"string","example":"Repassada"},"currency":{"type":"string","example":"BRL"},"period_end":{"type":"string","format":"date-time"},"closed_at":{"type":"string","format":"date-time","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true},"units":{"type":"array","items":{"type":"object"}},"deliveries":{"type":"object"},"coverage":{"type":"object"},"original_amount":{"type":"integer","minimum":1,"description":"Valor original do complemento congelado no fechamento"},"paid_amount":{"type":"integer","minimum":1,"description":"Valor já quitado"},"remaining_amount":{"type":"integer","minimum":1,"description":"Saldo restante; 0 na fatura quitada"},"amount_due":{"type":"integer","minimum":1,"description":"Igual a remaining_amount"},"charge":{"type":"object","nullable":true,"description":"Cobrança Pix. payment_link e pix só aparecem enquanto a cobrança está pendente e válida."}}},"Delivery":{"type":"object","description":"Entrega com parceiro logístico. O bloco funding mostra de onde saiu o dinheiro: sempre do próprio pedido daquela unidade.","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["delivery"]},"merchant_id":{"type":"string","format":"uuid","nullable":true},"payment_id":{"type":"string","format":"uuid","nullable":true,"description":"Pedido que custeia a entrega. null em cotação pré-checkout até o custeio; depois de custeado é imutável."},"checkout_mode":{"type":"string","enum":["PAYMENT_FIRST","PRE_CHECKOUT"],"description":"PAYMENT_FIRST: cotada a partir de um pedido existente. PRE_CHECKOUT: cotada antes da cobrança."},"external_reference":{"type":"string","nullable":true},"status":{"type":"string","description":"Situação pública da entrega.","enum":["REQUESTED","QUOTED","AUTHORIZED","DISPATCHING","DISPATCHED","IN_TRANSIT","COMPLETED","CANCELED","FAILED"]},"message":{"type":"string","nullable":true,"description":"Texto explicativo, seguro para exibir."},"financial_adjustment":{"type":"string","nullable":true,"enum":["PENDING_PARTNER_COST"],"description":"Presente quando o cancelamento aguarda a evidência da taxa do parceiro (ajuste no painel)."},"funding":{"type":"object","nullable":true,"properties":{"source":{"type":"string","enum":["ONLINE_ORDER_PIX","ONLINE_ORDER_CARD"]},"status":{"type":"string","enum":["RESERVED","RECOGNIZED","RELEASED","CANCELLED"]},"amount":{"type":"integer","description":"Total reservado em centavos."},"delivery_cost":{"type":"integer","description":"Custo do parceiro logístico."},"service_fee":{"type":"integer","description":"Tarifa de serviço da VPN Pay."},"refunded_amount":{"type":"integer"},"cancellation_fee":{"type":"integer","nullable":true},"dispatch":{"type":"string","nullable":true,"enum":["NOT_DISPATCHED","CREATED","DISPATCHING","DISPATCHED","TIMEOUT","FAILED","CANCELLED"],"description":"TIMEOUT mantém a reserva: resultado incerto nunca devolve dinheiro."},"currency":{"type":"string","example":"BRL"}}}},"example":{"id":"4e5f6a7b-8c9d-40e1-b2f3-a4b5c6d7e8f9","object":"delivery","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","external_reference":"pedido-1042","status":"DISPATCHED","message":null,"funding":{"source":"ONLINE_ORDER_CARD","status":"RESERVED","amount":1800,"delivery_cost":1500,"service_fee":300,"refunded_amount":0,"cancellation_fee":null,"dispatch":"DISPATCHED","currency":"BRL"}}},"DeliveryQuote":{"type":"object","nullable":true,"description":"Cotação do parceiro. Use quote.id no custeio antes de expires_at.","properties":{"id":{"type":"string","format":"uuid"},"delivery_cost":{"type":"integer","description":"Custo do parceiro em centavos."},"service_fee":{"type":"integer","description":"Tarifa de serviço da VPN Pay em centavos."},"total":{"type":"integer","description":"delivery_cost + service_fee: é o valor reservado."},"currency":{"type":"string","example":"BRL"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"7b2f1c3d-4e5a-4b6c-8d7e-9f0a1b2c3d4e","delivery_cost":1500,"service_fee":300,"total":1800,"currency":"BRL","expires_at":"2026-10-01T22:20:00.000Z"}},"DeliveryQuoteCreate":{"description":"Dois modos. Legado: payment_id + dropoff (o pedido já existe e define a unidade). Pré-checkout: merchant_id + external_reference + dropoff, sem payment_id — cota o frete antes de criar a cobrança. A cotação pré-checkout não reserva saldo, não cria custeio e não permite despacho.","oneOf":[{"title":"Legado (pedido já criado)","type":"object","required":["payment_id","dropoff"],"properties":{"payment_id":{"type":"string","format":"uuid","description":"Pedido da VPN Pay que vai custear a entrega. Define a unidade e o dinheiro usado."},"external_reference":{"type":"string","description":"Seu número de pedido."},"dropoff":{"type":"object","description":"Destino canônico LogisticsStop. Endereço textual/flat não é aceito nem interpretado. Campos extras não substituem campos obrigatórios.","required":["address","contact"],"properties":{"address":{"type":"object","required":["street","number","city","state","postalCode"],"properties":{"street":{"type":"string","minLength":3,"maxLength":200,"pattern":"^\\s*\\S[\\s\\S]{1,}\\S\\s*$"},"number":{"type":"string","minLength":1,"maxLength":40,"pattern":"^\\s*\\S[\\s\\S]*$"},"complement":{"type":"string","maxLength":200,"nullable":true},"district":{"type":"string","maxLength":120,"nullable":true},"city":{"type":"string","minLength":2,"maxLength":120,"pattern":"^\\s*\\S[\\s\\S]{0,}\\S\\s*$"},"state":{"type":"string","pattern":"^(?:[Aa][Cc]|[Aa][Ll]|[Aa][Pp]|[Aa][Mm]|[Bb][Aa]|[Cc][Ee]|[Dd][Ff]|[Ee][Ss]|[Gg][Oo]|[Mm][Aa]|[Mm][Tt]|[Mm][Ss]|[Mm][Gg]|[Pp][Aa]|[Pp][Bb]|[Pp][Rr]|[Pp][Ee]|[Pp][Ii]|[Rr][Jj]|[Rr][Nn]|[Rr][Ss]|[Rr][Oo]|[Rr][Rr]|[Ss][Cc]|[Ss][Pp]|[Ss][Ee]|[Tt][Oo])$","description":"UF brasileira com 2 letras."},"postalCode":{"type":"string","pattern":"^[0-9]{8}$","description":"CEP com 8 dígitos, sem máscara."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"latitude":{"minimum":-90,"maximum":90,"nullable":true,"description":"Número ou null (par com longitude)."},"longitude":{"minimum":-180,"maximum":180,"nullable":true,"description":"Número ou null (par com latitude)."}},"description":"Coordenadas opcionais: envie latitude e longitude juntas como números, ambas null ou omita as duas. Ambas null equivalem a sem coordenadas.","oneOf":[{"required":["latitude","longitude"],"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}},{"required":["latitude","longitude"],"properties":{"latitude":{"enum":[null]},"longitude":{"enum":[null]}}},{"not":{"anyOf":[{"required":["latitude"]},{"required":["longitude"]}]}}]},"contact":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120,"pattern":"^\\s*\\S[\\s\\S]{0,}\\S\\s*$"},"phone":{"type":"string","pattern":"^(?:\\+[0-9]{12,15}|[0-9]{10,15})$","description":"Somente dígitos: telefone nacional com DDD (10–11) ou internacional (12–15); + opcional para internacional."},"instructions":{"type":"string","maxLength":1000,"nullable":true}}}}},"pickup":{"type":"object","description":"Local de retirada (opcional). Precedência: este endereço, se enviado e válido, sempre vence; se omitido, usa o endereço padrão da configuração de entregas da unidade; sem nenhum dos dois, 422 PICKUP_REQUIRED. Enviado e inválido → 422 PICKUP_INVALID (o padrão nunca o substitui). O endereço resolvido é congelado na cotação e reutilizado no despacho.","required":["address"],"properties":{"address":{"type":"object","required":["street","number","city","state","postalCode"],"properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"UF com 2 letras"},"postalCode":{"type":"string","description":"CEP com 8 dígitos"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"contact":{"type":"object","description":"Opcional; se omitido usa o contato cadastrado da unidade.","properties":{"name":{"type":"string"},"phone":{"type":"string"},"instructions":{"type":"string"}}}}}}},{"title":"Pré-checkout (antes da cobrança)","type":"object","required":["merchant_id","external_reference","dropoff"],"properties":{"merchant_id":{"type":"string","format":"uuid","description":"Unidade; precisa estar no escopo da chave."},"external_reference":{"type":"string","description":"Seu número de pedido. A cobrança criada depois deve usar exatamente esta referência."},"dropoff":{"type":"object","description":"Destino canônico LogisticsStop. Endereço textual/flat não é aceito nem interpretado. Campos extras não substituem campos obrigatórios.","required":["address","contact"],"properties":{"address":{"type":"object","required":["street","number","city","state","postalCode"],"properties":{"street":{"type":"string","minLength":3,"maxLength":200,"pattern":"^\\s*\\S[\\s\\S]{1,}\\S\\s*$"},"number":{"type":"string","minLength":1,"maxLength":40,"pattern":"^\\s*\\S[\\s\\S]*$"},"complement":{"type":"string","maxLength":200,"nullable":true},"district":{"type":"string","maxLength":120,"nullable":true},"city":{"type":"string","minLength":2,"maxLength":120,"pattern":"^\\s*\\S[\\s\\S]{0,}\\S\\s*$"},"state":{"type":"string","pattern":"^(?:[Aa][Cc]|[Aa][Ll]|[Aa][Pp]|[Aa][Mm]|[Bb][Aa]|[Cc][Ee]|[Dd][Ff]|[Ee][Ss]|[Gg][Oo]|[Mm][Aa]|[Mm][Tt]|[Mm][Ss]|[Mm][Gg]|[Pp][Aa]|[Pp][Bb]|[Pp][Rr]|[Pp][Ee]|[Pp][Ii]|[Rr][Jj]|[Rr][Nn]|[Rr][Ss]|[Rr][Oo]|[Rr][Rr]|[Ss][Cc]|[Ss][Pp]|[Ss][Ee]|[Tt][Oo])$","description":"UF brasileira com 2 letras."},"postalCode":{"type":"string","pattern":"^[0-9]{8}$","description":"CEP com 8 dígitos, sem máscara."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"latitude":{"minimum":-90,"maximum":90,"nullable":true,"description":"Número ou null (par com longitude)."},"longitude":{"minimum":-180,"maximum":180,"nullable":true,"description":"Número ou null (par com latitude)."}},"description":"Coordenadas opcionais: envie latitude e longitude juntas como números, ambas null ou omita as duas. Ambas null equivalem a sem coordenadas.","oneOf":[{"required":["latitude","longitude"],"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}},{"required":["latitude","longitude"],"properties":{"latitude":{"enum":[null]},"longitude":{"enum":[null]}}},{"not":{"anyOf":[{"required":["latitude"]},{"required":["longitude"]}]}}]},"contact":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120,"pattern":"^\\s*\\S[\\s\\S]{0,}\\S\\s*$"},"phone":{"type":"string","pattern":"^(?:\\+[0-9]{12,15}|[0-9]{10,15})$","description":"Somente dígitos: telefone nacional com DDD (10–11) ou internacional (12–15); + opcional para internacional."},"instructions":{"type":"string","maxLength":1000,"nullable":true}}}}},"pickup":{"type":"object","description":"Local de retirada (opcional). Precedência: este endereço, se enviado e válido, sempre vence; se omitido, usa o endereço padrão da configuração de entregas da unidade; sem nenhum dos dois, 422 PICKUP_REQUIRED. Enviado e inválido → 422 PICKUP_INVALID (o padrão nunca o substitui). O endereço resolvido é congelado na cotação e reutilizado no despacho.","required":["address"],"properties":{"address":{"type":"object","required":["street","number","city","state","postalCode"],"properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"UF com 2 letras"},"postalCode":{"type":"string","description":"CEP com 8 dígitos"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"contact":{"type":"object","description":"Opcional; se omitido usa o contato cadastrado da unidade.","properties":{"name":{"type":"string"},"phone":{"type":"string"},"instructions":{"type":"string"}}}}}}}],"examples":{"legacy":{"summary":"Legado","value":{"payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","external_reference":"pedido-1042","dropoff":{"address":{"street":"Rua Cameron","number":"66","complement":"","district":"Miguel Couto","city":"Nova Iguaçu","state":"RJ","postalCode":"26070482","latitude":-22.7089395,"longitude":-43.4347412},"contact":{"name":"Diogo","phone":"+5521994977331","instructions":""}}}},"pre_checkout":{"summary":"Pré-checkout","value":{"merchant_id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","external_reference":"pedido-1043","dropoff":{"address":{"street":"Rua Cameron","number":"66","complement":"","district":"Miguel Couto","city":"Nova Iguaçu","state":"RJ","postalCode":"26070482","latitude":-22.7089395,"longitude":-43.4347412},"contact":{"name":"Diogo","phone":"+5521994977331","instructions":""}}}}},"example":{"merchant_id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","external_reference":"pedido-1043","dropoff":{"address":{"street":"Rua Cameron","number":"66","complement":"","district":"Miguel Couto","city":"Nova Iguaçu","state":"RJ","postalCode":"26070482","latitude":-22.7089395,"longitude":-43.4347412},"contact":{"name":"Diogo","phone":"+5521994977331","instructions":""}}}},"DeliveryFundingCreate":{"type":"object","required":["quote_id","funding_source"],"properties":{"quote_id":{"type":"string","format":"uuid","description":"Id devolvido em data.quote.id na cotação."},"payment_id":{"type":"string","format":"uuid","description":"Obrigatório quando a entrega foi cotada em pré-checkout: a cobrança paga daquele pedido. Precisa ser do mesmo tenant, da mesma unidade (merchant_id) e com o mesmo external_reference da entrega. O vínculo é feito na mesma transação da reserva e fica imutável. Um pagamento custeia no máximo uma entrega ativa. No fluxo legado é opcional e, se enviado, deve ser o pedido já vinculado."},"funding_source":{"type":"string","enum":["ONLINE_ORDER_PIX","ONLINE_ORDER_CARD"],"description":"ONLINE_ORDER_PIX consome o AVAILABLE daquele pedido. ONLINE_ORDER_CARD retém no PENDING daquele recebível e exige captura comprovada pelo provedor mais teto de adiantamento habilitado."}},"example":{"quote_id":"7b2f1c3d-4e5a-4b6c-8d7e-9f0a1b2c3d4e","payment_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","funding_source":"ONLINE_ORDER_PIX"}}}},"security":[{"apiKey":[]}],"x-scopes":["connect:send","connect:read","connect:templates:read","connect:templates:write","fiscal:read","fiscal:write","payments:read","payments:write","recipients:read","recipients:write","payouts:read","payouts:write","refunds:read","refunds:write","balances:read","reconciliation:read","webhooks:manage","delivery:read","delivery:write","fleet:read","fleet:write","fleet_invoices:read","merchants:read","merchants:write"],"x-scope-labels":{"connect:send":"Enviar WhatsApp (VPN Connect)","connect:read":"Consultar status de WhatsApp","connect:templates:read":"Consultar modelos WhatsApp da WABA","connect:templates:write":"Criar modelos WhatsApp na WABA","fiscal:read":"Consultar notas fiscais e documentos recebidos","fiscal:write":"Emitir notas fiscais e registrar eventos","payments:read":"Consultar cobranças","payments:write":"Criar cobranças","recipients:read":"Consultar recebedores","recipients:write":"Cadastrar recebedores","payouts:read":"Consultar repasses","payouts:write":"Solicitar repasses","refunds:read":"Consultar devoluções","refunds:write":"Criar devoluções","balances:read":"Consultar saldos","reconciliation:read":"Consultar conciliação","webhooks:manage":"Gerenciar avisos (webhooks)","delivery:read":"Consultar entregas","delivery:write":"Solicitar entregas","fleet:read":"Consultar entregas da frota própria","fleet:write":"Registrar entregas da frota própria","fleet_invoices:read":"Consultar faturas de repasse da frota","merchants:read":"Consultar unidades","merchants:write":"Cadastrar unidades e vincular recebedor"},"x-enums":{"payment_status":["CREATED","PENDING","PROCESSING","PAID","FAILED","CANCELED","EXPIRED","UNKNOWN","RECONCILIATION_REQUIRED"],"payout_status":["CREATED","PENDING","PROCESSING","DONE","FAILED","CANCELED","BLOCKED","UNKNOWN","RECONCILIATION_REQUIRED"],"refund_status":["CREATED","PENDING","PROCESSING","DONE","FAILED","CANCELED","UNKNOWN","RECONCILIATION_REQUIRED"],"refund_reason":["CUSTOMER_CANCEL_BEFORE_DISPATCH","CUSTOMER_CANCEL_AFTER_DISPATCH","MERCHANT_OUT_OF_STOCK","MERCHANT_CANCEL_AFTER_PICKUP","DRIVER_NO_SHOW","DRIVER_FAILURE","PLATFORM_ERROR","FRAUD","DUPLICATE_PAYMENT"],"liability_party":["MERCHANT","DRIVER","PARTNER","OTHER","PLATFORM"],"recipient_type":["MERCHANT","DRIVER","PARTNER","OTHER"],"recipient_status":["PENDING","UNDER_REVIEW","ACTIVE","BLOCKED","REJECTED"],"kyc_status":["NOT_STARTED","PENDING","UNDER_REVIEW","APPROVED","REJECTED"],"error_code":["invalid_request","unauthorized","forbidden","not_found","conflict","idempotency_conflict","unprocessable","rate_limited","internal_error"]},"x-pagination":{"supported":false,"description":"Pagamentos, repasses, devoluções, recebedores e conciliação não expõem page, offset nem cursor: devolvem os registros mais recentes, com teto por recurso. As faturas da frota (/fleet/invoices) têm paginação estável por cursor (limit + starting_after), com ordem fixa period_end desc, id desc.","limits":{"payments":50,"payouts":100,"refunds":100,"recipients":200,"reconciliation":50},"cursor_endpoints":{"/fleet/invoices":{"style":"cursor","order":"period_end desc, id desc","default_limit":20,"max_limit":100}}},"x-rate-limit":{"window_seconds":60,"read_default":240,"write_default":60,"headers":["X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset","Retry-After"]},"x-http-status-policy":{"409":"idempotency_conflict (mesma chave, corpo diferente) ou conflict (estado atual impede a operação).","503":"Não utilizado. Indisponibilidade de provedor é devolvida como 422 unprocessable."},"x-scenarios":{"smart_routing_automatico":{"summary":"Cobrança sem provider_connection_id — o Smart Routing escolhe a conexão","request":{"method":"POST","path":"/payments","headers":{"Idempotency-Key":"pedido-1042-pagamento-1"},"body":{"amount":4990,"external_reference":"pedido-1042","payer":{"name":"Maria Souza","document":"12345678909"}}},"response":{"status":201,"body":{"success":true,"data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PENDING","amount":4990,"currency":"BRL","provider_connection_id":"2f632c7c-9625-4778-aebc-1f7ccdc39359","br_code":"00020126…5204000053039865802BR"},"error":null,"code":null,"message":null,"request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"sem_conexao_elegivel":{"summary":"Nenhuma conexão elegível para o Smart Routing","response":{"status":422,"body":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Nenhuma conexão elegível para esta operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"payout_bloqueado_por_risco":{"summary":"Repasse recusado pelo monitoramento de risco — o provedor não é chamado","response":{"status":422,"body":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Repasse bloqueado por análise de risco para este recebedor","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}},"note":"A tentativa fica registrada com status BLOCKED e nada é reservado no saldo."},"saldo_insuficiente":{"summary":"Repasse maior que o saldo disponível do recebedor","response":{"status":422,"body":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"provider_indisponivel":{"summary":"Provedor fora do ar ou recusando a chamada","response":{"status":422,"body":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Provedor indisponível no momento. Tente novamente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}},"note":"Esta API NÃO devolve 503. Indisponibilidade de provedor é uma recusa de negócio e volta como 422 unprocessable, para manter um único contrato de erro. Repita a chamada com a MESMA Idempotency-Key."},"resultado_desconhecido":{"summary":"Resposta ambígua do provedor (timeout) — status UNKNOWN","response":{"status":201,"body":{"success":true,"data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"UNKNOWN","amount":4990,"currency":"BRL"},"error":null,"code":null,"message":null,"request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}},"note":"UNKNOWN significa que a VPN Pay não sabe se a operação existe no provedor. Nunca refaça a operação em outro provedor: aguarde o aviso ou a conciliação."},"conciliacao_necessaria":{"summary":"Divergência entre VPN Pay e provedor — status RECONCILIATION_REQUIRED","response":{"status":200,"body":{"success":true,"data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"RECONCILIATION_REQUIRED","amount":4990,"currency":"BRL"},"error":null,"code":null,"message":null,"request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}},"note":"O valor não é liberado enquanto a conciliação não resolver a divergência."},"idempotency_conflict":{"summary":"Mesma Idempotency-Key reaproveitada com outro corpo","response":{"status":409,"body":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}},"note":"Mesma chave + mesmo corpo devolve a resposta original, sem criar nova operação."}},"x-webhook-events":["payment.created","payment.paid","payment.failed","payment.settled","payment.chargeback","refund.created","refund.completed","refund.failed","payout.created","payout.completed","payout.failed","payout.blocked","recipient.updated","delivery.requested","delivery.quoted","delivery.charge_pending","delivery.authorized","delivery.failed","delivery.dispatched","delivery.dispatch_pending","delivery.status_changed","delivery.canceled","fleet_invoice.created","fleet_invoice.charge_available","fleet_invoice.paid","connect.message.received","connect.message.status","connect.message.failed"],"x-webhook-event-labels":{"payment.created":"Cobrança criada","payment.paid":"Cobrança paga","payment.failed":"Cobrança falhou","payment.settled":"Recebível liquidado (líquido disponível)","payment.chargeback":"Contestação de cartão aberta ou revertida","refund.created":"Devolução criada","refund.completed":"Devolução concluída","refund.failed":"Devolução falhou","payout.created":"Repasse criado","payout.completed":"Repasse concluído","payout.failed":"Repasse falhou","payout.blocked":"Repasse bloqueado","recipient.updated":"Recebedor atualizado","delivery.requested":"Entrega solicitada","delivery.quoted":"Entrega cotada","delivery.charge_pending":"Cobrança da entrega em processamento","delivery.authorized":"Entrega autorizada","delivery.failed":"Entrega não autorizada","delivery.dispatched":"Corrida criada no parceiro","delivery.dispatch_pending":"Corrida em confirmação com o parceiro","delivery.status_changed":"Situação da corrida atualizada","delivery.canceled":"Entrega cancelada","fleet_invoice.created":"Fatura da frota criada","fleet_invoice.charge_available":"Cobrança da fatura disponível","fleet_invoice.paid":"Pagamento da fatura confirmado","connect.message.received":"WhatsApp: mensagem recebida","connect.message.status":"WhatsApp: enviada, entregue ou lida","connect.message.failed":"WhatsApp: falha no envio"},"x-webhook-signature":{"headers":["X-VPNPay-Event","X-VPNPay-Delivery","X-VPNPay-Timestamp","X-VPNPay-Signature"],"algorithm":"HMAC SHA-256 sobre `timestamp + \".\" + corpo bruto`, enviado como sha256=<hex>","signed_payload":"X-VPNPay-Timestamp + \".\" + corpo bruto exatamente como recebido (sem reserializar)","signed_payload_example":"1789243804.{\"id\":\"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071\",\"type\":\"payment.paid\",\"created_at\":\"2026-09-12T22:10:04.000Z\",\"data\":{\"id\":\"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d\",\"status\":\"PAID\",\"amount\":4990}}","tolerance_seconds":300,"delivery":"at-least-once — trate duplicidade pelo id do evento ou pelo delivery_id","retries":["30s","2min","10min","1h","6h","24h"],"expected_response":"HTTP 2xx em até 10s. Qualquer outro status agenda nova tentativa.","examples":{"node":"import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n// IMPORTANTE: use o corpo BRUTO da requisição, sem JSON.parse antes de validar.\n// Cabeçalho ausente ou malformado devolve false — nunca lança exceção.\nexport function verifyVpnPay(rawBody: string, headers: Record<string, string | undefined>, secret: string) {\n  const timestamp = headers[\"x-vpnpay-timestamp\"];\n  const signature = headers[\"x-vpnpay-signature\"];\n  if (typeof timestamp !== \"string\" || typeof signature !== \"string\") return false;\n\n  // Timestamp: só dígitos e inteiro seguro (evita NaN passar na tolerância).\n  if (!/^\\d{1,15}$/.test(timestamp.trim())) return false;\n  const ts = Number(timestamp.trim());\n  if (!Number.isSafeInteger(ts)) return false;\n  if (Math.abs(Date.now() - ts * 1000) > 5 * 60_000) return false;\n\n  // Assinatura: sha256= + 64 caracteres hexadecimais.\n  const received = signature.trim().replace(/^sha256=/, \"\");\n  if (!/^[0-9a-f]{64}$/i.test(received)) return false;\n\n  const expected = createHmac(\"sha256\", secret).update(timestamp.trim() + \".\" + rawBody).digest(\"hex\");\n  const a = Buffer.from(expected, \"hex\");\n  const b = Buffer.from(received.toLowerCase(), \"hex\");\n  if (a.length !== b.length) return false; // timingSafeEqual lança se os tamanhos diferem\n  return timingSafeEqual(a, b);\n}","php":"<?php\n// IMPORTANTE: use o corpo BRUTO da requisição, sem json_decode antes de validar.\n$rawBody   = file_get_contents('php://input');\n$timestamp = $_SERVER['HTTP_X_VPNPAY_TIMESTAMP'] ?? '';\n$received  = preg_replace('/^sha256=/', '', $_SERVER['HTTP_X_VPNPAY_SIGNATURE'] ?? '');\n$secret    = getenv('VPNPAY_WEBHOOK_SECRET');\n\nif ($timestamp === '' || $received === '') { http_response_code(400); exit; }\nif (abs(time() - (int) $timestamp) > 300) { http_response_code(400); exit; }\n\n$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);\n\nif (!hash_equals($expected, $received)) { http_response_code(401); exit; }\n\n$event = json_decode($rawBody, true);\n// Entrega at-least-once: ignore se já processou $event['id'].\nhttp_response_code(200);"},"schema":{"$ref":"#/components/schemas/WebhookEvent"}},"webhooks":{"payment.created":{"post":{"operationId":"webhookPaymentCreated","tags":["Webhooks"],"summary":"Cobrança criada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.created","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PENDING","amount":4990,"currency":"BRL","external_reference":"pedido-1042","created_at":"2026-09-12T22:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payment.paid":{"post":{"operationId":"webhookPaymentPaid","tags":["Webhooks"],"summary":"Cobrança paga","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.paid","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PAID","amount":4990,"currency":"BRL","external_reference":"pedido-1042","paid_at":"2026-09-12T22:10:03.000Z","created_at":"2026-09-12T22:00:00.000Z","updated_at":"2026-09-12T22:10:03.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payment.failed":{"post":{"operationId":"webhookPaymentFailed","tags":["Webhooks"],"summary":"Cobrança falhou","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.failed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"FAILED","amount":4990,"currency":"BRL","external_reference":"pedido-1042","created_at":"2026-09-12T22:00:00.000Z","updated_at":"2026-09-12T22:40:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payment.settled":{"post":{"operationId":"webhookPaymentSettled","tags":["Webhooks"],"summary":"Recebível liquidado (líquido disponível)","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.settled","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PAID","amount":4990,"currency":"BRL","external_reference":"pedido-1042","released_amount":4512}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payment.chargeback":{"post":{"operationId":"webhookPaymentChargeback","tags":["Webhooks"],"summary":"Contestação de cartão aberta ou revertida","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payment.chargeback","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","object":"payment","status":"PAID","amount":4990,"currency":"BRL","external_reference":"pedido-1042","chargeback_status":"OPENED"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"refund.created":{"post":{"operationId":"webhookRefundCreated","tags":["Webhooks"],"summary":"Devolução criada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"refund.created","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"1a2b3c4d-5e6f-4a0b-9c1d-2e3f4a5b6c7d","object":"refund","status":"CREATED","amount":1500,"currency":"BRL","payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","created_at":"2026-09-12T22:20:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"refund.completed":{"post":{"operationId":"webhookRefundCompleted","tags":["Webhooks"],"summary":"Devolução concluída","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"refund.completed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"1a2b3c4d-5e6f-4a0b-9c1d-2e3f4a5b6c7d","object":"refund","status":"DONE","amount":1500,"currency":"BRL","payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","created_at":"2026-09-12T22:20:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"refund.failed":{"post":{"operationId":"webhookRefundFailed","tags":["Webhooks"],"summary":"Devolução falhou","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"refund.failed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"1a2b3c4d-5e6f-4a0b-9c1d-2e3f4a5b6c7d","object":"refund","status":"FAILED","amount":1500,"currency":"BRL","payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","created_at":"2026-09-12T22:20:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payout.created":{"post":{"operationId":"webhookPayoutCreated","tags":["Webhooks"],"summary":"Repasse criado","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payout.created","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","object":"payout","status":"CREATED","amount":25000,"currency":"BRL","recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","created_at":"2026-09-12T23:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payout.completed":{"post":{"operationId":"webhookPayoutCompleted","tags":["Webhooks"],"summary":"Repasse concluído","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payout.completed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","object":"payout","status":"DONE","amount":25000,"currency":"BRL","recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","completed_at":"2026-09-12T23:05:00.000Z","created_at":"2026-09-12T23:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payout.failed":{"post":{"operationId":"webhookPayoutFailed","tags":["Webhooks"],"summary":"Repasse falhou","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payout.failed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","object":"payout","status":"FAILED","amount":25000,"currency":"BRL","recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","created_at":"2026-09-12T23:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"payout.blocked":{"post":{"operationId":"webhookPayoutBlocked","tags":["Webhooks"],"summary":"Repasse bloqueado","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"payout.blocked","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","object":"payout","status":"BLOCKED","amount":25000,"currency":"BRL","recipient_id":"b3c1a2d4-55e6-4f77-8899-0a1b2c3d4e5f","created_at":"2026-09-12T23:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"recipient.updated":{"post":{"operationId":"webhookRecipientUpdated","tags":["Webhooks"],"summary":"Recebedor atualizado","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"recipient.updated","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b","data":{"id":"c4d3b2a1-66f7-4e88-99aa-1b2c3d4e5f6a","object":"recipient","status":"ACTIVE","type":"DRIVER","legal_name":"Diogo Xavier Correa","created_at":"2026-09-12T20:00:00.000Z"}}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.requested":{"post":{"operationId":"webhookDeliveryRequested","tags":["Webhooks"],"summary":"Entrega solicitada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.requested","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.quoted":{"post":{"operationId":"webhookDeliveryQuoted","tags":["Webhooks"],"summary":"Entrega cotada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.quoted","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.charge_pending":{"post":{"operationId":"webhookDeliveryCharge_pending","tags":["Webhooks"],"summary":"Cobrança da entrega em processamento","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.charge_pending","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.authorized":{"post":{"operationId":"webhookDeliveryAuthorized","tags":["Webhooks"],"summary":"Entrega autorizada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.authorized","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.failed":{"post":{"operationId":"webhookDeliveryFailed","tags":["Webhooks"],"summary":"Entrega não autorizada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.failed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.dispatched":{"post":{"operationId":"webhookDeliveryDispatched","tags":["Webhooks"],"summary":"Corrida criada no parceiro","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.dispatched","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.dispatch_pending":{"post":{"operationId":"webhookDeliveryDispatch_pending","tags":["Webhooks"],"summary":"Corrida em confirmação com o parceiro","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.dispatch_pending","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.status_changed":{"post":{"operationId":"webhookDeliveryStatus_changed","tags":["Webhooks"],"summary":"Situação da corrida atualizada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.status_changed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"delivery.canceled":{"post":{"operationId":"webhookDeliveryCanceled","tags":["Webhooks"],"summary":"Entrega cancelada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"delivery.canceled","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"fleet_invoice.created":{"post":{"operationId":"webhookFleet_invoiceCreated","tags":["Webhooks"],"summary":"Fatura da frota criada","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"fleet_invoice.created","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"fleet_invoice.charge_available":{"post":{"operationId":"webhookFleet_invoiceCharge_available","tags":["Webhooks"],"summary":"Cobrança da fatura disponível","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"fleet_invoice.charge_available","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"fleet_invoice.paid":{"post":{"operationId":"webhookFleet_invoicePaid","tags":["Webhooks"],"summary":"Pagamento da fatura confirmado","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"fleet_invoice.paid","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"connect.message.received":{"post":{"operationId":"webhookConnectMessageReceived","tags":["Webhooks"],"summary":"WhatsApp: mensagem recebida","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"connect.message.received","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"connect.message.status":{"post":{"operationId":"webhookConnectMessageStatus","tags":["Webhooks"],"summary":"WhatsApp: enviada, entregue ou lida","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"connect.message.status","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}},"connect.message.failed":{"post":{"operationId":"webhookConnectMessageFailed","tags":["Webhooks"],"summary":"WhatsApp: falha no envio","description":"A VPN Pay envia este aviso por POST ao endereço que você cadastrou em \"API e integrações → Avisos automáticos\". Assinatura HMAC SHA-256 em X-VPNPay-Signature sobre o texto timestamp + \".\" + corpo bruto. Responda com HTTP 2xx em até 10s; qualquer outro status agenda reenvio (30s, 2min, 10min, 1h, 6h, 24h). Entrega at-least-once: deduplique pelo id do evento ou pelo delivery_id. Um cliente pode ter vários endereços cadastrados: o mesmo evento é entregue a todos os elegíveis, cada um com segredo, histórico e reenvio próprios. Roteie sempre por tenant_id/merchant_id/external_reference.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","event_id":"3c9a4b5c-6d7e-4f80-9a1b-2c3d4e5f6071","type":"connect.message.failed","created_at":"2026-09-12T22:10:04.000Z","delivery_id":"a71f0b1c-2d3e-4f50-8a6b-9c0d1e2f3a4b","tenant_id":"5b7c8d9e-0f11-4223-8455-66778899aabb","merchant_id":"9d8c7b6a-5e4f-4312-9a8b-7c6d5e4f3a2b"}}}},"responses":{"200":{"description":"Aviso recebido com sucesso. Não agenda reenvio."},"400":{"description":"Não recebido — agenda reenvio."},"401":{"description":"Assinatura inválida — o receptor deve recusar. Agenda reenvio."}}}}},"paths":{"/connect/templates":{"get":{"operationId":"listConnectTemplates","tags":["Connect"],"summary":"Consultar modelos da WABA da conexão","x-scope":"connect:templates:read","description":"accountId obrigatório. WABA resolvida no servidor pela conta do tenant/unidade da chave. Nunca aceita WABA enviada pelo cliente. Retorna data.templates, data.after, data.wabaId e providerHttpStatus. after só é retornado quando existe próxima página.","parameters":[{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"after","in":"query","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"Modelos e status atuais da Meta"},"401":{"description":"Chave inválida"},"403":{"description":"Sem connect:templates:read"},"404":{"description":"Conta fora do escopo"},"422":{"description":"data.ok=false; providerHttpStatus e códigos seguros da Meta"}}},"post":{"operationId":"createConnectTemplate","tags":["Connect"],"summary":"Criar modelo na WABA da conexão","x-scope":"connect:templates:write","description":"Não envia mensagens. Credencial real da conta, sem fallback. Modelo aguarda aprovação Meta. Idempotência por tenant+WABA+chave; resultado incerto nunca é repetido automaticamente. Categorias UTILITY/MARKETING; componentes de texto e até três botões QUICK_REPLY/URL/PHONE_NUMBER/COPY_CODE. Variáveis numéricas sequenciais com exemplos obrigatórios. AUTHENTICATION (OTP): components = [BODY{add_security_recommendation}, FOOTER{code_expiration_minutes 1–90}, BUTTONS[{type:OTP, otp_type:COPY_CODE}]]; no envio use message.otpCode.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","template"],"properties":{"accountId":{"type":"string","format":"uuid"},"template":{"type":"object","additionalProperties":false,"required":["name","language","category","components"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9_]+$","maxLength":512},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$"},"category":{"type":"string","enum":["UTILITY","MARKETING"]},"components":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["HEADER","BODY","FOOTER","BUTTONS"]},"format":{"type":"string","enum":["TEXT","IMAGE"],"description":"IMAGE exige example.header_url com 1 link HTTPS JPG/PNG até 5 MB; a VPN Pay envia a amostra à Meta"},"text":{"type":"string","maxLength":1024},"example":{"type":"object"},"buttons":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object"}}}}}}}}},"example":{"accountId":"11111111-1111-4111-8111-111111111111","template":{"name":"segunda_via_pedido","language":"pt_BR","category":"UTILITY","components":[{"type":"BODY","text":"Olá, recebemos sua solicitação de segunda via do pedido {{1}}. Acesse o link abaixo para consultar os detalhes e concluir o pagamento.","example":{"body_text":[["106024"]]}},{"type":"BUTTONS","buttons":[{"type":"URL","text":"Consultar pedido","url":"https://example.com/pedidos/{{1}}","example":["https://example.com/pedidos/106024"]}]}]}}}}},"responses":{"200":{"description":"Replay, sem nova criação"},"201":{"description":"Criado na Meta; data.template.id/status/category; não significa aprovado"},"202":{"description":"Resultado incerto; consultar modelos, não reenviar"},"401":{"description":"Chave inválida"},"403":{"description":"Sem connect:templates:write"},"404":{"description":"Conta fora do escopo"},"409":{"description":"Conflito, andamento ou resultado incerto"},"422":{"description":"Meta recusou ou credencial indisponível; consultar data.ok/providerHttpStatus/errorCode"}}}},"/connect/templates/{name}":{"delete":{"operationId":"deleteConnectTemplate","tags":["Connect"],"summary":"Excluir modelo da WABA da conexão","x-scope":"connect:templates:write","description":"Exclui na Meta o modelo com este nome na WABA da conta (todos os idiomas). Com templateId, exclui só aquele idioma. WABA nunca é enviada pelo cliente. Sem repetição automática; 202 = resultado incerto, consulte a lista. A Meta impede recriar o mesmo nome por 30 dias.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9_]{1,512}$"}},{"name":"accountId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"templateId","in":"query","schema":{"type":"string","pattern":"^\\d{1,32}$"},"description":"ID do modelo na Meta (data.templates[].id)"}],"responses":{"200":{"description":"Excluído; data.deleted=true"},"202":{"description":"Resultado incerto; consultar lista"},"401":{"description":"Chave inválida"},"403":{"description":"Sem connect:templates:write"},"404":{"description":"Conta fora do escopo"},"422":{"description":"Meta recusou; ver errorCode/providerError"}}}},"/connect/messages":{"post":{"operationId":"sendConnectMessage","tags":["Connect"],"summary":"Enviar WhatsApp","description":"Exige connect:send. Conta do tenant da chave e unidade autorizada; contas sem unidade exigem ALL. Usa apenas a credencial real cifrada. TEST aceita somente destinatários homologados. Texto livre exige janela de 24h. Nunca repete automaticamente; unknown exige consulta. O sucesso do envelope indica processamento, data.ok indica aceite da Meta.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["accountId","message"],"properties":{"accountId":{"type":"string","format":"uuid"},"to":{"type":"string","maxLength":32,"description":"Telefone E.164; exclusivo com recipientIndex"},"recipientIndex":{"type":"integer","minimum":0,"maximum":4},"message":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":4096}}},{"type":"object","required":["type","name","language"],"properties":{"type":{"type":"string","enum":["template"]},"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$"},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$"},"bodyParams":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":1024}},"headerImageUrl":{"type":"string","format":"uri","pattern":"^https://","description":"Obrigatório para modelos com cabeçalho IMAGE: link HTTPS público JPG/PNG"}}}]}},"oneOf":[{"required":["to"],"not":{"required":["recipientIndex"]}},{"required":["recipientIndex"],"not":{"required":["to"]}}]}}}},"responses":{"200":{"description":"Repetição idempotente; sem novo envio"},"201":{"description":"Meta aceitou; data contém messageId, status, waMessageId, errorCode e ok"},"202":{"description":"Resultado desconhecido ou em andamento; não reenviar"},"401":{"description":"Chave inválida"},"403":{"description":"Sem connect:send"},"404":{"description":"Conta ausente ou fora do escopo"},"409":{"description":"Conflito de idempotência ou envio em andamento"},"422":{"description":"Bloqueio de TEST, janela fechada, credencial indisponível ou rejeição Meta"},"429":{"description":"Limite de chamadas"}}}},"/connect/messages/{id}":{"get":{"operationId":"getConnectMessage","tags":["Connect"],"summary":"Consultar status WhatsApp","description":"Exige connect:read e escopo da conta. Retorna messageId, status, waMessageId e errorCode, sem texto, telefone ou token. Status atualizado pelo webhook Meta; não encaminha eventos ao webhook do cliente nesta versão.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status atual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Chave inválida"},"403":{"description":"Sem connect:read"},"404":{"description":"Mensagem ausente ou fora do escopo"}}}},"/fleet/invoices":{"get":{"operationId":"listFleetInvoices","tags":["Fleet Invoices"],"summary":"Lista faturas do complemento da frota","description":"Faturas dos ciclos de repasse com complemento. Paginação estável por cursor: ordem fixa period_end desc, id desc. Use pagination.next_cursor em starting_after para a próxima página. A chave só enxerga as unidades autorizadas nela.","security":[{"apiKey":[]}],"x-scope":"fleet_invoices:read","x-pagination":{"supported":true,"style":"cursor","order":"period_end desc, id desc","max_limit":100,"default_limit":20},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Id da última fatura da página anterior (pagination.next_cursor)."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["OPEN","OVERDUE","IN_REVIEW","PAID","FUNDED","PAYING","SETTLED"]}},{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/FleetInvoice"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","format":"uuid","nullable":true}}}}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/fleet/invoices/{id_or_number}":{"get":{"operationId":"getFleetInvoice","tags":["Fleet Invoices"],"summary":"Detalha uma fatura por id do ciclo ou número (FAT-AAAA-NNNNN)","security":[{"apiKey":[]}],"x-scope":"fleet_invoices:read","parameters":[{"name":"id_or_number","in":"path","required":true,"schema":{"type":"string"},"description":"UUID do ciclo ou número da fatura, ex.: FAT-2026-00002."}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/FleetInvoice"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/payments":{"get":{"operationId":"listPayments","tags":["Payments"],"summary":"Lista cobranças","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 50 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"payments:read","x-pagination":{"supported":false,"max_items":50,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}},"post":{"operationId":"createPayment","tags":["Payments"],"summary":"Cria cobrança Pix ou cartão (checkout HOSTED)","security":[{"apiKey":[]}],"x-scope":"payments:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Payment"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/payments/{id}":{"get":{"operationId":"getPayment","tags":["Payments"],"summary":"Detalha cobrança","security":[{"apiKey":[]}],"x-scope":"payments:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Payment"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/payouts":{"get":{"operationId":"listPayouts","tags":["Payouts"],"summary":"Lista repasses","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 100 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"payouts:read","x-pagination":{"supported":false,"max_items":100,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}},"post":{"operationId":"createPayout","tags":["Payouts"],"summary":"Solicita repasse Pix","security":[{"apiKey":[]}],"x-scope":"payouts:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Payout"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/payouts/{id}":{"get":{"operationId":"getPayout","tags":["Payouts"],"summary":"Detalha repasse","security":[{"apiKey":[]}],"x-scope":"payouts:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Payout"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/refunds":{"get":{"operationId":"listRefunds","tags":["Refunds"],"summary":"Lista devoluções","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 100 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"refunds:read","x-pagination":{"supported":false,"max_items":100,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}},"post":{"operationId":"createRefund","tags":["Refunds"],"summary":"Cria devolução","security":[{"apiKey":[]}],"x-scope":"refunds:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Refund"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/refunds/{id}":{"get":{"operationId":"getRefund","tags":["Refunds"],"summary":"Detalha devolução","security":[{"apiKey":[]}],"x-scope":"refunds:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Refund"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/recipients":{"get":{"operationId":"listRecipients","tags":["Recipients"],"summary":"Lista recebedores","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 200 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"recipients:read","x-pagination":{"supported":false,"max_items":200,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}},"post":{"operationId":"createRecipient","tags":["Recipients"],"summary":"Cadastra recebedor","security":[{"apiKey":[]}],"x-scope":"recipients:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Recipient"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/merchants":{"get":{"operationId":"listMerchants","tags":["Merchants"],"summary":"Lista unidades autorizadas pela chave","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 200 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"merchants:read","x-pagination":{"supported":false,"max_items":200,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}},"parameters":[{"name":"external_reference","in":"query","required":false,"schema":{"type":"string"},"description":"Filtra pelo código no seu sistema"}]},"post":{"operationId":"createMerchant","tags":["Merchants"],"summary":"Cadastra unidade (exige chave ALL)","security":[{"apiKey":[]}],"x-scope":"merchants:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Merchant"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}},"description":"Cria a unidade já mapeada ao seu código. Chave SELECTED recebe 403. A nova unidade não entra automaticamente em chaves SELECTED existentes: inclua-a no painel. Ativação, suspensão e KYC do recebedor seguem no painel."}},"/merchants/{id}":{"get":{"operationId":"getMerchant","tags":["Merchants"],"summary":"Detalha unidade","security":[{"apiKey":[]}],"x-scope":"merchants:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Merchant"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}},"patch":{"operationId":"updateMerchant","tags":["Merchants"],"summary":"Altera nome ou vincula recebedor","security":[{"apiKey":[]}],"x-scope":"merchants:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdate"}}}},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Merchant"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/recipients/{id}":{"get":{"operationId":"getRecipient","tags":["Recipients"],"summary":"Detalha recebedor","security":[{"apiKey":[]}],"x-scope":"recipients:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Recipient"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/recipients/{id}/balance":{"get":{"operationId":"getRecipientBalance","tags":["Recipients"],"summary":"Saldo disponível do recebedor","security":[{"apiKey":[]}],"x-scope":"balances:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","default":"BRL"},"description":"Moeda do saldo. Único filtro aceito neste endpoint."}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Balance"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries":{"get":{"operationId":"listDeliveries","tags":["Deliveries"],"summary":"Lista entregas das unidades autorizadas na chave","description":"Mais recentes primeiro. A chave só enxerga as unidades autorizadas nela; entrega de outra unidade responde 404 neutro.","security":[{"apiKey":[]}],"x-scope":"delivery:read","x-pagination":{"supported":false,"max_items":100,"order":"created_at desc"},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries/quotes":{"post":{"operationId":"createDeliveryQuote","tags":["Deliveries"],"summary":"Cria a solicitação e cota a entrega no parceiro","description":"Primeiro passo do fluxo. Devolve a entrega e a cotação (com expires_at); guarde quote.id para o custeio. Legado: payment_id define a unidade e o dinheiro. Pré-checkout: merchant_id + external_reference, sem payment_id — use o total da cotação para compor a cobrança; nada é reservado e a entrega não pode ser despachada até o custeio com payment_id. Unidade fora do escopo da chave devolve 404.","security":[{"apiKey":[]}],"x-scope":"delivery:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryQuoteCreate"},"examples":{"legacy":{"summary":"Legado","value":{"payment_id":"8f0c2f1e-6c1a-4f0b-9f71-1d0f2a3b4c5d","external_reference":"pedido-1042","dropoff":{"address":{"street":"Rua Cameron","number":"66","complement":"","district":"Miguel Couto","city":"Nova Iguaçu","state":"RJ","postalCode":"26070482","latitude":-22.7089395,"longitude":-43.4347412},"contact":{"name":"Diogo","phone":"+5521994977331","instructions":""}}}},"pre_checkout":{"summary":"Pré-checkout","value":{"merchant_id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","external_reference":"pedido-1043","dropoff":{"address":{"street":"Rua Cameron","number":"66","complement":"","district":"Miguel Couto","city":"Nova Iguaçu","state":"RJ","postalCode":"26070482","latitude":-22.7089395,"longitude":-43.4347412},"contact":{"name":"Diogo","phone":"+5521994977331","instructions":""}}}}}}}},"responses":{"201":{"description":"Entrega criada e cotada","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/Delivery"},"quote":{"$ref":"#/components/schemas/DeliveryQuote"}}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries/{id}":{"get":{"operationId":"getDelivery","tags":["Deliveries"],"summary":"Detalhe e estado financeiro da entrega","security":[{"apiKey":[]}],"x-scope":"delivery:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries/{id}/funding":{"post":{"operationId":"fundDelivery","tags":["Deliveries"],"summary":"Reserva o custo no dinheiro do próprio pedido","description":"ONLINE_ORDER_PIX consome o saldo AVAILABLE gerado por aquele pedido. ONLINE_ORDER_CARD retém no PENDING daquele recebível e exige captura comprovada pelo provedor mais o teto de adiantamento habilitado para a unidade. Nunca usa saldo de outro pedido, de outra unidade nem crédito da VPN Pay. No pré-checkout envie payment_id: cotação válida, mesmo tenant, mesma unidade, mesmo external_reference, estado financeiro exigido, fundos suficientes e ausência de custeio conflitante são validados de forma atômica antes de vincular e reservar. O motivo vem no campo code do envelope: 409 QUOTE_EXPIRED, DELIVERY_ALREADY_FUNDED, PAYMENT_ALREADY_BOUND; 422 PAYMENT_MERCHANT_MISMATCH, PAYMENT_REFERENCE_MISMATCH, PAYMENT_REQUIRED, QUOTE_MISMATCH, PAYMENT_NOT_CONFIRMED, CAPTURE_NOT_CONFIRMED, PROVIDER_CAPTURE_EVIDENCE_MISSING, FUNDING_SOURCE_MISMATCH; 402 EXPOSURE_NOT_ENABLED, EXPOSURE_SINGLE_LIMIT, EXPOSURE_LIMIT_REACHED, INSUFFICIENT_BALANCE; 404 PAYMENT_NOT_FOUND. Repetir com a mesma Idempotency-Key e o mesmo corpo devolve o resultado anterior.","security":[{"apiKey":[]}],"x-scope":"delivery:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryFundingCreate"}}}},"responses":{"201":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries/{id}/dispatch":{"post":{"operationId":"dispatchDelivery","tags":["Deliveries"],"summary":"Contrata a corrida no parceiro","description":"Resposta 202. Timeout ou retorno inconclusivo do parceiro MANTÊM a reserva, devolvem dispatch TIMEOUT e emitem delivery.dispatch_pending — não trate como falha nem repita com outra Idempotency-Key. A reserva só é devolvida em falha definitiva, sem corrida e sem custo devido.","security":[{"apiKey":[]}],"x-scope":"delivery:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/deliveries/{id}/cancel":{"post":{"operationId":"cancelDelivery","tags":["Deliveries"],"summary":"Cancela a entrega","description":"Sem custo do parceiro, a reserva volta integralmente (AVAILABLE se o recebível já foi liquidado, senão PENDING). Com taxa do parceiro, a entrega fica com financial_adjustment PENDING_PARTNER_COST e o ajuste é concluído no painel mediante evidência. Taxa maior que o reservado é recusada (FEE_EXCEEDS_RESERVATION): nada é debitado em silêncio.","security":[{"apiKey":[]}],"x-scope":"delivery:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Mesma chave + mesmo corpo devolve o mesmo resultado, sem criar nova operação. Corpo diferente devolve 409.","example":"pedido-1042-pagamento-1"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Motivo livre registrado na auditoria.","example":"customer_canceled"}}}}}},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/docs.md":{"get":{"operationId":"getDocsMarkdown","tags":["Meta"],"summary":"Documentação completa em Markdown puro (público, sem envelope)","description":"text/markdown; charset=utf-8. Sem login e sem JavaScript.","security":[],"responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/balances":{"get":{"operationId":"listBalances","tags":["Balances"],"summary":"Saldos do cliente","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 500 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"balances:read","x-pagination":{"supported":false,"max_items":500,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Balance"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/reconciliation":{"get":{"operationId":"listReconciliationRuns","tags":["Reconciliation"],"summary":"Execuções de conciliação","description":"Lista os registros mais recentes do cliente da chave, em ordem decrescente de criação. Esta versão da API não aceita paginação nem filtros por query string: são devolvidos no máximo 50 registros por chamada. Para histórico completo use os avisos (webhooks) e guarde os registros do seu lado.","security":[{"apiKey":[]}],"x-scope":"reconciliation:read","x-pagination":{"supported":false,"max_items":50,"order":"created_at desc"},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"type":"object"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/reconciliation/{id}":{"get":{"operationId":"getReconciliationRun","tags":["Reconciliation"],"summary":"Resultado de uma conciliação","security":[{"apiKey":[]}],"x-scope":"reconciliation:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"array","items":{"type":"object"}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/ping":{"get":{"operationId":"ping","tags":["Meta"],"summary":"Confere se a chave de API está válida","security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"tenant_id":{"type":"string","format":"uuid"}}}}}]}}}},"400":{"description":"invalid_request — campo ausente, tipo errado ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"invalid_request","code":"invalid_request","message":"Campo amount deve ser inteiro positivo em centavos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"401":{"description":"unauthorized — chave de API ausente, inválida, revogada ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unauthorized","code":"unauthorized","message":"Chave de API ausente, inválida ou revogada","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"403":{"description":"forbidden — chave sem o escopo necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"forbidden","code":"forbidden","message":"Esta chave não possui o escopo payments:write","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"404":{"description":"not_found — recurso inexistente ou de outro cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"not_found","code":"not_found","message":"Recurso não encontrado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"409":{"description":"idempotency_conflict — mesma Idempotency-Key com corpo diferente; conflict — estado atual não permite a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"idempotency_conflict","code":"idempotency_conflict","message":"Esta Idempotency-Key já foi usada com um corpo diferente","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"422":{"description":"unprocessable — regra de negócio recusou (saldo insuficiente, bloqueio de risco, provedor indisponível)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"unprocessable","code":"unprocessable","message":"Saldo disponível insuficiente para o repasse solicitado","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}},"429":{"description":"rate_limited — limite de chamadas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"rate_limited","code":"rate_limited","message":"Limite de chamadas excedido. Tente novamente em alguns segundos","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Chamadas permitidas na janela de 60s"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Chamadas restantes na janela"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Quando a janela reinicia"},"Retry-After":{"schema":{"type":"integer"},"description":"Segundos"}}},"500":{"description":"internal_error — falha inesperada da VPN Pay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"data":null,"error":"internal_error","code":"internal_error","message":"Não foi possível concluir a operação","request_id":"0f7f1a7c-1f0e-4a1e-9f3d-6f0f0a1b2c3d"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["Meta"],"summary":"Esta documentação (público, sem envelope)","description":"Único endpoint que devolve JSON puro — pronto para Swagger UI, Redoc e Postman.","security":[],"responses":{"200":{"description":"Documento OpenAPI 3.0.3","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}