{ "openapi": "3.1.0", "info": { "title": "PhanterPay API", "version": "1.1.0", "description": "API pública da PhanterPay para Pix cash-in e cash-out. JSON em snake_case, autenticação por chave de API (bp__) e idempotência obrigatória nos POSTs financeiros. NÃO existe sandbox: todas as chamadas atingem a rede Pix real e movimentam dinheiro real.", "contact": { "name": "Suporte PhanterPay", "url": "https://phanterpay.com.br/contato" } }, "servers": [ { "url": "https://api.phanterpay.com.br/v1", "description": "Produção (único ambiente)" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Cash-in", "description": "Cobranças Pix" }, { "name": "Cash-out", "description": "Saques Pix" }, { "name": "Transações", "description": "Timeline unificada de entradas e saídas" }, { "name": "Saldo" }, { "name": "MED", "description": "Infrações Pix" }, { "name": "Cripto", "description": "Reservado — API pública de Cripto em desenvolvimento. Atualmente responde 501 FEATURE_NOT_AVAILABLE." }, { "name": "Boleto", "description": "Reservado — responde 501" }, { "name": "Cartão", "description": "Reservado — responde 501" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer bp__" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternativa equivalente ao Bearer." } }, "schemas": { "Error": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "Charge": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "example": "chg_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "txid": { "type": [ "string", "null" ], "description": "Identificador do adquirente (legado)." }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "example": 150 }, "test_mode": { "type": "boolean", "description": "true quando amount <= 5.00. Não é sandbox: o Pix é real." }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "description": { "type": [ "string", "null" ] }, "pix": { "type": "object", "properties": { "copy_paste": { "type": [ "string", "null" ], "description": "Pix copia e cola (EMV)." }, "qr_code_image": { "type": [ "string", "null" ], "description": "Imagem do QR Code em data URL, quando disponível." } } }, "end_to_end_id": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Payout": { "type": "object", "properties": { "id": { "type": "string", "example": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b" }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "description": "Valor líquido creditado ao destinatário (igual ao amount enviado)." }, "fee": { "type": [ "number", "null" ], "description": "Taxa cobrada, debitada do saldo além do líquido." }, "net_amount": { "type": [ "number", "null" ], "description": "Igual a amount." }, "gross_amount": { "type": [ "number", "null" ], "description": "amount + fee — total debitado do saldo." }, "test_mode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "reversed" ], "description": "Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial." }, "pix": { "type": "object", "properties": { "key": { "type": "string" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_document": { "type": [ "string", "null" ] } } }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_in_..." }, "type": { "type": "string", "enum": [ "cash_in", "cash_out" ] }, "resource_id": { "type": [ "string", "null" ], "description": "ID público da cobrança (chg_...) ou do saque (pyt_...)." }, "amount": { "type": "number", "example": 10 }, "fee": { "type": "number", "example": 1.2 }, "net_amount": { "type": "number", "description": "Valor líquido creditado (cash_in) ou enviado (cash_out)." }, "gross_amount": { "type": "number", "description": "Valor bruto movimentado (total debitado no cash_out)." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled", "refunded" ] }, "method": { "type": "string", "enum": [ "pix" ] }, "origin": { "type": "string", "enum": [ "api", "manual" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" } } }, "Infraction": { "type": "object", "properties": { "id": { "type": "string", "example": "inf_5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "external_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "open" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_submitted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InfractionDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "inf_5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "external_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "open" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_text": { "type": [ "string", "null" ] }, "defense_evidence_url": { "type": [ "string", "null" ] } } }, "Balance": { "type": "object", "required": [ "available_balance", "pending_balance", "blocked_balance", "total_balance", "currency" ], "properties": { "available_balance": { "type": "number", "description": "Disponível para saque agora." }, "pending_balance": { "type": "number", "description": "Recebido, aguardando liberação." }, "blocked_balance": { "type": "number", "description": "Retido por infração Pix (MED) ou análise." }, "total_balance": { "type": "number", "description": "available + pending + blocked." }, "currency": { "type": "string", "enum": [ "BRL" ] } } } } }, "paths": { "/charges": { "get": { "tags": [ "Cash-in" ], "summary": "Listar cobranças Pix", "description": "Escopo: charges:read. Paginação por cursor (limit + starting_after). Não há offset nem filtro de status.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "200": { "description": "Página de cobranças, mais recentes primeiro", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_starting_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "example": "chg_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "txid": { "type": [ "string", "null" ], "description": "Identificador do adquirente (legado)." }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "example": 150 }, "test_mode": { "type": "boolean", "description": "true quando amount <= 5.00. Não é sandbox: o Pix é real." }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "description": { "type": [ "string", "null" ] }, "pix": { "type": "object", "properties": { "copy_paste": { "type": [ "string", "null" ], "description": "Pix copia e cola (EMV)." }, "qr_code_image": { "type": [ "string", "null" ], "description": "Imagem do QR Code em data URL, quando disponível." } } }, "end_to_end_id": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_starting_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "tags": [ "Cash-in" ], "summary": "Criar cobrança Pix", "description": "Escopo: charges:write. Idempotency-Key obrigatório. Envio de split_rule_id/split é recusado com 422 split_not_available.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "minimum": 2, "example": 150, "description": "Mínimo R$ 2,00. Dinheiro real." }, "description": { "type": "string", "maxLength": 140 }, "payer_name": { "type": "string", "maxLength": 200 }, "payer_document": { "type": "string", "maxLength": 20 }, "expires_in": { "type": "integer", "minimum": 60, "maximum": 86400 }, "external_id": { "type": "string", "maxLength": 120 }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "external_id já existente — devolve a cobrança original (deduplicação semântica)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "example": "chg_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "txid": { "type": [ "string", "null" ], "description": "Identificador do adquirente (legado)." }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "example": 150 }, "test_mode": { "type": "boolean", "description": "true quando amount <= 5.00. Não é sandbox: o Pix é real." }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "description": { "type": [ "string", "null" ] }, "pix": { "type": "object", "properties": { "copy_paste": { "type": [ "string", "null" ], "description": "Pix copia e cola (EMV)." }, "qr_code_image": { "type": [ "string", "null" ], "description": "Imagem do QR Code em data URL, quando disponível." } } }, "end_to_end_id": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "201": { "description": "Cobrança criada", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "example": "chg_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "txid": { "type": [ "string", "null" ], "description": "Identificador do adquirente (legado)." }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "example": 150 }, "test_mode": { "type": "boolean", "description": "true quando amount <= 5.00. Não é sandbox: o Pix é real." }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "description": { "type": [ "string", "null" ] }, "pix": { "type": "object", "properties": { "copy_paste": { "type": [ "string", "null" ], "description": "Pix copia e cola (EMV)." }, "qr_code_image": { "type": [ "string", "null" ], "description": "Imagem do QR Code em data URL, quando disponível." } } }, "end_to_end_id": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/charges/{id}": { "get": { "tags": [ "Cash-in" ], "summary": "Consultar cobrança", "description": "Escopo: charges:read. Aceita o id público (chg_...), o txid do adquirente ou ext:.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cobrança", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "example": "chg_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "txid": { "type": [ "string", "null" ], "description": "Identificador do adquirente (legado)." }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "example": 150 }, "test_mode": { "type": "boolean", "description": "true quando amount <= 5.00. Não é sandbox: o Pix é real." }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled", "refunded" ] }, "description": { "type": [ "string", "null" ] }, "pix": { "type": "object", "properties": { "copy_paste": { "type": [ "string", "null" ], "description": "Pix copia e cola (EMV)." }, "qr_code_image": { "type": [ "string", "null" ], "description": "Imagem do QR Code em data URL, quando disponível." } } }, "end_to_end_id": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/payouts": { "get": { "tags": [ "Cash-out" ], "summary": "Listar saques Pix", "description": "Escopo: payouts:read. Paginação por cursor (limit + starting_after). Não há offset nem filtro de status.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "200": { "description": "Página de saques, mais recentes primeiro", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_starting_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b" }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "description": "Valor líquido creditado ao destinatário (igual ao amount enviado)." }, "fee": { "type": [ "number", "null" ], "description": "Taxa cobrada, debitada do saldo além do líquido." }, "net_amount": { "type": [ "number", "null" ], "description": "Igual a amount." }, "gross_amount": { "type": [ "number", "null" ], "description": "amount + fee — total debitado do saldo." }, "test_mode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "reversed" ], "description": "Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial." }, "pix": { "type": "object", "properties": { "key": { "type": "string" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_document": { "type": [ "string", "null" ] } } }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_starting_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "tags": [ "Cash-out" ], "summary": "Criar saque Pix", "description": "Escopo: payouts:write. Idempotency-Key obrigatório. Semântica líquida: o destinatário recebe exatamente `amount`; a taxa é somada e o total (gross_amount) é debitado do saldo. Saques via API são automáticos, sem aprovação manual.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pix_key" ], "properties": { "amount": { "type": "number", "minimum": 2, "example": 50, "description": "Mínimo R$ 2,00. Valor líquido ao destinatário." }, "pix_key": { "type": "string", "minLength": 1 }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ] }, "recipient_name": { "type": "string", "maxLength": 200 }, "recipient_document": { "type": "string", "maxLength": 20 }, "description": { "type": "string", "maxLength": 140 }, "external_id": { "type": "string", "maxLength": 120 }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "external_id já existente — devolve o saque original", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b" }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "description": "Valor líquido creditado ao destinatário (igual ao amount enviado)." }, "fee": { "type": [ "number", "null" ], "description": "Taxa cobrada, debitada do saldo além do líquido." }, "net_amount": { "type": [ "number", "null" ], "description": "Igual a amount." }, "gross_amount": { "type": [ "number", "null" ], "description": "amount + fee — total debitado do saldo." }, "test_mode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "reversed" ], "description": "Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial." }, "pix": { "type": "object", "properties": { "key": { "type": "string" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_document": { "type": [ "string", "null" ] } } }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "201": { "description": "Saque criado. Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial.", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b" }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "description": "Valor líquido creditado ao destinatário (igual ao amount enviado)." }, "fee": { "type": [ "number", "null" ], "description": "Taxa cobrada, debitada do saldo além do líquido." }, "net_amount": { "type": [ "number", "null" ], "description": "Igual a amount." }, "gross_amount": { "type": [ "number", "null" ], "description": "amount + fee — total debitado do saldo." }, "test_mode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "reversed" ], "description": "Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial." }, "pix": { "type": "object", "properties": { "key": { "type": "string" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_document": { "type": [ "string", "null" ] } } }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "id": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b", "external_id": "payout_001", "amount": 50, "fee": 2, "net_amount": 50, "gross_amount": 52, "test_mode": false, "status": "processing", "pix": { "key": "financeiro@empresa.com", "recipient_name": null, "recipient_document": null }, "description": null, "end_to_end_id": null, "error_message": null, "created_at": "2026-01-31T12:00:00.000Z", "completed_at": null } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "402": { "description": "Saldo insuficiente para líquido + taxa", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/payouts/{id}": { "get": { "tags": [ "Cash-out" ], "summary": "Consultar saque", "description": "Escopo: payouts:read. Aceita pyt_... ou o uuid interno.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saque", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "pyt_9c1d0e5f6a7b8c9d3f9a1c0b8e7d4a2b" }, "external_id": { "type": [ "string", "null" ] }, "amount": { "type": "number", "description": "Valor líquido creditado ao destinatário (igual ao amount enviado)." }, "fee": { "type": [ "number", "null" ], "description": "Taxa cobrada, debitada do saldo além do líquido." }, "net_amount": { "type": [ "number", "null" ], "description": "Igual a amount." }, "gross_amount": { "type": [ "number", "null" ], "description": "amount + fee — total debitado do saldo." }, "test_mode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "reversed" ], "description": "Pode retornar processing, completed ou failed conforme o resultado obtido durante a sincronização inicial." }, "pix": { "type": "object", "properties": { "key": { "type": "string" }, "recipient_name": { "type": [ "string", "null" ] }, "recipient_document": { "type": [ "string", "null" ] } } }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/transactions": { "get": { "tags": [ "Transações" ], "summary": "Listar transações", "description": "Retorna uma timeline unificada de entradas e saídas Pix da conta. Escopos aceitos: transactions:read ou (charges:read E payouts:read).", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "all", "cash_in", "cash_out" ], "default": "all" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled", "refunded" ] } }, { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "api", "manual" ] } }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Página de transações unificadas", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_starting_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_in_..." }, "type": { "type": "string", "enum": [ "cash_in", "cash_out" ] }, "resource_id": { "type": [ "string", "null" ], "description": "ID público da cobrança (chg_...) ou do saque (pyt_...)." }, "amount": { "type": "number", "example": 10 }, "fee": { "type": "number", "example": 1.2 }, "net_amount": { "type": "number", "description": "Valor líquido creditado (cash_in) ou enviado (cash_out)." }, "gross_amount": { "type": "number", "description": "Valor bruto movimentado (total debitado no cash_out)." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled", "refunded" ] }, "method": { "type": "string", "enum": [ "pix" ] }, "origin": { "type": "string", "enum": [ "api", "manual" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" } } } }, "has_more": { "type": "boolean" }, "next_starting_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/balance": { "get": { "tags": [ "Saldo" ], "summary": "Consultar saldo", "description": "Escopo: balance:read.", "responses": { "200": { "description": "Saldo da conta em BRL", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "available_balance": 12530.45, "pending_balance": 320, "blocked_balance": 0, "total_balance": 12850.45, "currency": "BRL" } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/med": { "get": { "tags": [ "MED" ], "summary": "Listar infrações Pix (MED)", "description": "Escopo: med:read (charges:read também é aceito). Paginação por cursor.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Quantidade de itens por página (1 a 100)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo status exato (ex.: open, under_review)." } ], "responses": { "200": { "description": "Página de infrações", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_starting_after" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "inf_5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "external_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "open" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_submitted_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "has_more": { "type": "boolean" }, "next_starting_after": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/med/{id}": { "get": { "tags": [ "MED" ], "summary": "Consultar infração", "description": "Escopo: med:read (charges:read também é aceito).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Infração", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "inf_5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "external_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "open" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_text": { "type": [ "string", "null" ] }, "defense_evidence_url": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }, "post": { "tags": [ "MED" ], "summary": "Enviar defesa da infração", "description": "Escopo: med:write (charges:write também é aceito). Não exige Idempotency-Key: a operação é um update determinístico que move o status para under_review.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "defense_text" ], "properties": { "defense_text": { "type": "string", "minLength": 1 }, "defense_evidence_url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "responses": { "200": { "description": "Defesa registrada", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Teto da janela (600)." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix timestamp do reset." }, "x-request-id": { "schema": { "type": "string" }, "description": "Identificador da requisição." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "inf_5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "external_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "open" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "defense_text": { "type": [ "string", "null" ] }, "defense_evidence_url": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key ausente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "403": { "description": "Escopo insuficiente", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "404": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "409": { "description": "Conflito de idempotência", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "422": { "description": "Limite por transação excedido", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit (600 req/min por chave)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "500": { "description": "Erro interno", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "502": { "description": "Adquirentes indisponíveis", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "503": { "description": "Serviço temporariamente indisponível (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } } }, "/crypto/charges": { "get": { "tags": [ "Cripto" ], "summary": "Listar cobranças cripto (reservado — 501)", "description": "Rota reservada para futura ativação. Hoje a PhanterPay NÃO processa pagamentos cripto através da API pública. As rotas existem para preservar o contrato da API e permitir ativação sem mudança de endpoint.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cripto estará disponível em breve.", "retryable": false }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } }, "post": { "tags": [ "Cripto" ], "summary": "Criar cobrança cripto (reservado — 501)", "description": "Rota reservada para futura ativação. Contrato futuro documentado abaixo. Hoje responde 501 FEATURE_NOT_AVAILABLE.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "minimum": 1e-8, "description": "Valor da cobrança, positivo." }, "currency": { "type": "string", "description": "Moeda (ex: BTC, ETH, USDT)." }, "settle_currency": { "type": "string", "enum": [ "brl", "usd" ], "description": "Moeda de liquidação." }, "description": { "type": "string", "maxLength": 200 }, "customer_email": { "type": "string", "format": "email" }, "external_id": { "type": "string", "maxLength": 120 }, "postback_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Resposta futura esperada (mock)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "pay_currency": { "type": "string" }, "pay_amount": { "type": "number" }, "pay_address": { "type": "string" }, "fee_amount": { "type": "number" }, "net_amount": { "type": "number" }, "external_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time" } } } } } }, "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cripto estará disponível em breve.", "retryable": false }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } }, "/crypto/payouts": { "get": { "tags": [ "Cripto" ], "summary": "Listar saques cripto (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cripto estará disponível em breve.", "retryable": false }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } }, "post": { "tags": [ "Cripto" ], "summary": "Criar saque cripto (reservado — 501)", "description": "Rota reservada para futura ativação. Contrato futuro documentado abaixo. Hoje responde 501 FEATURE_NOT_AVAILABLE.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "address" ], "properties": { "amount": { "type": "number", "minimum": 1e-8, "description": "Valor bruto do saque." }, "currency": { "type": "string", "description": "Moeda a ser enviada." }, "address": { "type": "string", "description": "Endereço de destino." }, "network": { "type": "string", "description": "Rede (ex: ERC20, TRC20, BEP20)." }, "extra_id": { "type": "string", "description": "Tag/Memo se necessário." }, "external_id": { "type": "string", "maxLength": 120 } } } } } }, "responses": { "201": { "description": "Resposta futura esperada (mock)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "network": { "type": "string" }, "address": { "type": "string" }, "settle_currency": { "type": "string" }, "amount": { "type": "number" }, "fee_amount": { "type": "number" }, "net_amount": { "type": "number" }, "amount_crypto": { "type": "number" }, "amount_crypto_sent": { "type": "number" }, "tx_hash": { "type": "string" }, "error_message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": "string", "format": "date-time" } } } } } }, "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cripto estará disponível em breve.", "retryable": false }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } }, "/boletos": { "get": { "tags": [ "Boleto" ], "summary": "Listar boleto (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE. Contrato futuro: paginação limit/starting_after igual a /charges.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Boleto estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } }, "post": { "tags": [ "Boleto" ], "summary": "Criar boleto (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE. O contrato futuro exigirá Idempotency-Key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "payer_name", "payer_document", "due_date" ], "properties": { "amount": { "type": "number", "minimum": 2 }, "due_date": { "type": "string", "format": "date" }, "description": { "type": "string", "maxLength": 140 }, "payer_name": { "type": "string", "maxLength": 200 }, "payer_document": { "type": "string", "maxLength": 20 }, "external_id": { "type": "string", "maxLength": 120 }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500 } } } } } }, "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Boleto estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } }, "/boletos/{id}": { "get": { "tags": [ "Boleto" ], "summary": "Consultar boleto (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Boleto estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } }, "/card/charges": { "get": { "tags": [ "Cartão" ], "summary": "Listar cartão (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE. Contrato futuro: paginação limit/starting_after igual a /charges.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Quantidade de itens por página (1 a 200)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: id da última linha da página anterior (use next_starting_after). Retorna apenas registros mais antigos." } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cartão estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } }, "post": { "tags": [ "Cartão" ], "summary": "Criar cartão (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE. O contrato futuro exigirá Idempotency-Key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Obrigatório em POSTs financeiros. Chave única por operação (8-255 caracteres). Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "card_token" ], "properties": { "amount": { "type": "number", "minimum": 2 }, "card_token": { "type": "string", "description": "Token do cartão (nunca PAN em claro)." }, "installments": { "type": "integer", "minimum": 1, "maximum": 12 }, "description": { "type": "string", "maxLength": 140 }, "payer_name": { "type": "string", "maxLength": 200 }, "payer_document": { "type": "string", "maxLength": 20 }, "external_id": { "type": "string", "maxLength": 120 }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500 } } } } } }, "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cartão estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } }, "/card/charges/{id}": { "get": { "tags": [ "Cartão" ], "summary": "Consultar cartão (reservado — 501)", "description": "Rota reservada. Hoje responde 501 FEATURE_NOT_AVAILABLE.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "501": { "description": "FEATURE_NOT_AVAILABLE — rota reservada, ainda não disponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "request_id": { "type": "string", "example": "req_9f0c1c2d3e4f" }, "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "example": { "success": false, "error": { "code": "FEATURE_NOT_AVAILABLE", "message": "Cartão estará disponível em breve.", "retryable": false, "availability": "coming_soon" }, "request_id": "req_89c0aaa30f1b4c2d" } } } } } } } } }