{ "openapi": "3.1.0", "info": { "title": "BluntPay API", "version": "1.1.0", "description": "API pública da BluntPay para Pix e Cripto (cash-in e cash-out). JSON em snake_case, autenticação por chave de API (bp__) e idempotência obrigatória nos POSTs financeiros. Para começar a integrar, o único requisito é a BLUNTPAY_API_KEY — não é necessário cadastrar webhook, URL de callback nem segredo de webhook. Webhooks são opcionais e recomendados para confirmação em tempo real e menos polling; sem eles, cash-in Pix, saques Pix e cash-in cripto continuam funcionais pelos GETs de consulta com sync-on-read. Ao optar por webhooks, cadastre a URL de callback e valide a assinatura conforme a documentação.", "contact": { "name": "Suporte BluntPay", "url": "https://bluntpay.com.br/contato" } }, "servers": [ { "url": "https://api.bluntpay.com.br/v1", "description": "API BluntPay v1" } ], "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": "Depósitos e saques em cripto. Cash-in: mínimo comercial por moeda/rede somado ao mínimo técnico dinâmico. Cash-out: trx, usdtbsc, btc, ltc e usdterc20 (usdttrc20 não é aceito no saque), mínimo efetivo dinâmico = max(20 USDT comercial, mínimo técnico dinâmico real da rede)." }, { "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 }, "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": "Tarifa 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." }, "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 }, "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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. Requer autenticação, o header Idempotency-Key (OBRIGATÓRIO, 8 a 255 caracteres; ausência devolve 400 idempotency_key_required) e o corpo mínimo { \"amount\": 100.00 }. external_id é opcional. Reenvio do mesmo external_id com o mesmo amount devolve a cobrança original (HTTP 200); amount diferente devolve 409 EXTERNAL_ID_CONFLICT. O array split (split interno) só funciona em contas habilitadas pelo admin da BluntPay — não vem liberado por padrão e não faz parte da integração básica; contas sem o recurso habilitado recebem 403 split_disabled. O campo split_rule_id não é suportado e devolve 422 split_not_available.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "OBRIGATÓRIO em POST /charges (8 a 255 caracteres). Ausência devolve 400 idempotency_key_required. Chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "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." }, "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, "example": "pedido_847293", "description": "Opcional. Identificador do pedido no seu sistema; ativa a deduplicação semântica. Valor novo para pedido novo; mesmo valor ao repetir a mesma operação. Reenvio com o mesmo amount devolve a cobrança original (200); amount diferente devolve 409 EXTERNAL_ID_CONFLICT. Consultável em GET /charges/ext:{external_id}." }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Opcional. Se utilizada, a URL deve estar previamente cadastrada e ativa nos endpoints de webhook da conta; caso contrário a API devolve 400 postback_url_not_registered. A entrega usa a mesma fila persistente e as mesmas retentativas do endpoint global (at-least-once, tentativa imediata + retries), sem duplicar quando a URL já é um endpoint global ativo que assina o evento. Valide a assinatura sobre o corpo cru, responda 2xx rápido e deduplique por event.id." }, "split": { "type": "array", "maxItems": 5, "description": "Opcional. Split interno: divide o valor líquido (bruto menos a taxa BluntPay) entre até 5 contas BluntPay (soma das porcentagens até 100). O restante fica com o criador da cobrança. O crédito é saldo interno, não gera Pix automático. Beneficiários precisam estar ativos e com KYC aprovado. MED, chargeback e estorno são de responsabilidade integral do criador da cobrança; beneficiários têm exposição zero.", "items": { "type": "object", "required": [ "recipient_email", "percentage" ], "properties": { "recipient_email": { "type": "string", "format": "email", "maxLength": 200 }, "percentage": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } } } } } } } } }, "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 }, "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 }, "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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:. O webhook charge.paid é o caminho principal de confirmação em tempo real; este GET é o fallback/reconciliação e faz sync-on-read: se a cobrança ainda estiver pending e não expirada, a BluntPay consulta a situação autoritativa antes de responder. Nunca marque como pago localmente; use polling moderado com backoff.", "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 }, "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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": "Tarifa 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." }, "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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. `external_id` é OBRIGATÓRIO, imutável e identifica uma única intenção de saque; Idempotency-Key é opcional. Reenvio equivalente devolve o mesmo saque (HTTP 200) em qualquer status, inclusive failed/reversed; divergência devolve 409 EXTERNAL_ID_CONFLICT. Uma nova tentativa operacional após failed/reversed exige nova intenção com NOVO external_id. 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. Se `postback_url` for enviada, a URL precisa estar previamente cadastrada e ativa nos endpoints de webhook da conta; caso contrário a API devolve 400 postback_url_not_registered. HTTP 504 com code `ambiguous_payout_status` exige consulta por GET antes de qualquer decisão.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Opcional (proteção avançada). Se enviada, use 8 a 255 caracteres: chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header presente porém fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pix_key", "external_id" ], "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, "example": "saque_847293", "description": "Obrigatório e imutável. Identifica uma única intenção e permanece ligado ao recurso em failed/reversed. Uma nova tentativa operacional exige nova intenção e novo external_id. Consultável em GET /payouts/ext:{external_id}." }, "postback_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Opcional. Se utilizada, a URL deve estar previamente cadastrada e ativa nos endpoints de webhook da conta; caso contrário a API devolve 400 postback_url_not_registered." } } } } } }, "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": "Tarifa 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." }, "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": "Tarifa 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." }, "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, "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 malformada (invalid_idempotency_key)", "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. O code real é `insufficient_balance_for_fees` (não o genérico INSUFFICIENT_BALANCE). O corpo traz `details.max_withdrawable`, o maior `amount` líquido que pode ser solicitado agora com o saldo 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": "insufficient_balance_for_fees", "message": "Insufficient balance", "retryable": false, "required": 52, "fee": 2, "net": 50, "details": { "requested_amount": 50, "available_balance": 40, "fee_amount": 2, "total_required": 52, "max_withdrawable": 38, "additional_balance_needed": 12 } }, "request_id": "req_9c1d0e5f6a7b8c9d" } } } }, "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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" } } } } } } } } } } }, "504": { "description": "Resultado do envio não confirmado (code: ambiguous_payout_status). Não repetir POST automaticamente; consultar primeiro o payout existente por GET /payouts/{id} ou GET /payouts/ext:{external_id}.", "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_..., o uuid interno ou ext: (ex.: /payouts/ext:saque_847293). Use esta consulta antes de qualquer nova tentativa quando o POST tiver devolvido ambiguous_payout_status. A confirmação em tempo real vem pelo webhook de saque; este GET é o fallback/reconciliação e faz sync-on-read: em processing a BluntPay consulta a situação autoritativa antes de responder e só aplica status terminal confirmado. Nunca marque pago localmente por tempo decorrido; polling moderado com backoff.", "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": "Tarifa 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." }, "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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 malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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/currencies": { "get": { "tags": [ "Cripto" ], "summary": "Listar moedas e redes suportadas", "description": "Escopo: charges:read ou payouts:read.\n\nFonte oficial dos códigos aceitos em `pay_currency` (depósito) e `currency` (saque). Consulte este endpoint em vez de chumbar códigos: novas moedas/redes aparecem aqui primeiro.\n`code` é o identificador a enviar na API; `network` é o slug estável da rede; `requires_memo` indica que o destino exige memo/tag junto do endereço.", "parameters": [ { "name": "flow", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "deposit", "withdrawal" ] }, "description": "Filtra apenas as moedas habilitadas para o fluxo informado." } ], "responses": { "200": { "description": "Moedas suportadas", "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": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "usdtbsc" }, "symbol": { "type": "string", "example": "USDT" }, "name": { "type": "string", "example": "Tether USD" }, "network": { "type": "string", "example": "bsc" }, "network_name": { "type": "string", "example": "BNB Chain (BEP20)" }, "can_deposit": { "type": "boolean" }, "can_withdraw": { "type": "boolean" }, "requires_memo": { "type": "boolean" } } } } } }, "example": { "object": "list", "data": [ { "code": "usdtbsc", "symbol": "USDT", "name": "Tether USD", "network": "bsc", "network_name": "BNB Chain (BEP20)", "can_deposit": true, "can_withdraw": true, "requires_memo": false }, { "code": "trx", "symbol": "TRX", "name": "TRON", "network": "tron", "network_name": "Tron", "can_deposit": true, "can_withdraw": true, "requires_memo": false } ] } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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/quotes": { "post": { "tags": [ "Cripto" ], "summary": "Criar cotação em cripto", "description": "Escopos: `withdrawal` exige `payouts:read`; `deposit` exige `charges:read`; `conversion` (informativa) aceita `charges:read` OU `payouts:read`.\n\nCotação INFORMATIVA de conversão, calculada com as mesmas fontes autoritativas usadas na criação. NÃO trava preço, não reserva saldo, não cria recurso e não é aceita como parâmetro por nenhum outro endpoint — o valor final é sempre recalculado no POST de depósito/saque.\nSaque (`withdrawal`): `from` é sempre `usdt` (moeda do saldo da conta) e `amount` está em USDT; `estimated_amount` é o valor estimado na moeda de destino. Nunca assuma paridade 1:1, nem entre redes da mesma stablecoin.\nDepósito (`deposit`): `from` é sempre `usd` (moeda de precificação) e `estimated_amount` é a quantidade aproximada de cripto que o pagador enviaria.\nConversão (`conversion`): cotação informativa de `usd`/`usdt` para `brl`, para a plataforma converter o saldo interno do jogador. `network` vem `null`, `minimum` não se aplica (`null`) e nada é reservado ou criado.\n`minimum` vem da mesma fonte de mínimo usada na criação e está na moeda de `from`; quando não é possível determiná-lo, vem `null` — nenhum número é inventado. Não existe máximo publicado nesta resposta.\n`expires_at` expira em 60 segundos: cotação vencida deve ser refeita. `quote_id` é opaco e serve apenas para correlação em suporte/logs.\nErros: 422 `unsupported_currency`, `unsupported_network`, `unsupported_route`, `invalid_amount`, `below_minimum`. 503 `quote_unavailable` para indisponibilidade temporária — é transitório e deve ser repetido com backoff, nunca tratado como saldo insuficiente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "amount", "operation" ], "properties": { "from": { "type": "string", "example": "usdt", "description": "`usdt` para saque, `usd` para depósito, `usd`/`usdt` em conversion." }, "to": { "type": "string", "example": "trx", "description": "Código de GET /crypto/currencies; `brl` em conversion." }, "amount": { "type": "number", "example": 100 }, "network": { "type": "string", "example": "tron", "description": "Opcional; valida a rede da moeda. Ignorado em conversion." }, "operation": { "type": "string", "enum": [ "deposit", "withdrawal", "conversion" ] } } }, "example": { "from": "usdt", "to": "trx", "amount": 100, "network": "tron", "operation": "withdrawal" } } } }, "responses": { "200": { "description": "Cotação gerada", "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": { "example": { "object": "crypto_quote", "quote_id": "cq_9f2c41ab7d3e5068b1c4a7e29d05f831", "operation": "withdrawal", "from": "usdt", "to": "trx", "network": "tron", "amount": 100, "estimated_amount": 431.20516, "rate": 4.3120516, "minimum": 20, "minimum_currency": "usdt", "price_locked": false, "expires_at": "2026-08-24T15:31:00.000Z", "created_at": "2026-08-24T15:30:00.000Z" } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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": "unsupported_currency / unsupported_network / unsupported_route / invalid_amount / below_minimum", "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": "quote_unavailable — cotação temporariamente indisponível (transitório)", "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 depósitos em cripto", "description": "Escopo: charges:read. Restrito à conta autenticada. Filtre por external_id ou customer_id para conciliar o jogador.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de depósitos", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ccr_8a1c0b3f9e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_charge" ] }, "status": { "type": "string", "enum": [ "processing", "waiting", "confirming", "partially_paid", "paid", "failed", "expired", "refunded" ], "description": "Status do depósito. `processing` é transitório: o endereço ainda está sendo provisionado ou recuperado — repita a MESMA Idempotency-Key/external_id até receber `waiting`. `paid` significa RECEBIMENTO CONFIRMADO e é terminal. A diferença entre esperado e recebido NÃO aparece no status, e sim nos campos de valor: `paid_amount` (recebido on-chain, na `pay_currency`), `received_amount` (valor liquidado em USD/USDT — use este para creditar o cliente final) e `amount_status` (`underpaid` | `exact` | `overpaid`). `partially_paid` é LEGADO: nenhum fluxo atual o produz e ele permanece no enum apenas por compatibilidade histórica — pode aparecer somente em depósitos antigos criados antes da mudança. Não implemente lógica nova para esse status." }, "external_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Identificador do jogador/cliente NO SEU sistema. Não cria saldo próprio na BluntPay." }, "metadata": { "type": [ "object", "null" ] }, "price_amount": { "type": "number", "description": "Valor cobrado, em USD." }, "price_currency": { "type": "string", "enum": [ "usd" ] }, "pay_amount": { "type": [ "number", "null" ], "description": "Quantidade a pagar na moeda escolhida." }, "pay_currency": { "type": "string", "example": "usdttrc20" }, "paid_amount": { "type": [ "number", "null" ], "description": "Quantidade REALMENTE recebida on-chain, na mesma `pay_currency` (ex.: TRX, BTC). Serve para auditoria/reconciliação blockchain — NÃO é um valor em USD/USDT e não deve ser usado para creditar saldo em USD/USDT." }, "received_amount": { "type": [ "number", "null" ], "description": "Valor efetivamente liquidado em USD/USDT. ESTE é o campo que integrações com saldo em USD/USDT devem usar para creditar o cliente/jogador. `null` enquanto não houver evidência autoritativa suficiente." }, "amount_status": { "type": [ "string", "null" ], "enum": [ "underpaid", "exact", "overpaid", null ], "description": "Comparação (com tolerância) entre `paid_amount` e `pay_amount`: `underpaid` entrou menos, `exact` entrou o esperado, `overpaid` entrou mais. `null` enquanto não houver recebimento." }, "pay_address": { "type": [ "string", "null" ], "description": "Endereço on-chain para o jogador depositar." }, "pay_extra_id": { "type": [ "string", "null" ], "description": "Memo/tag, quando a rede exigir." }, "network": { "type": [ "string", "null" ] }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver, descontada na liquidação." }, "net_amount": { "type": [ "number", "null" ] }, "credited_amount": { "type": [ "number", "null" ], "description": "Líquido que entrou no saldo USDT do MERCHANT na BluntPay, após as taxas. `null` enquanto não houver crédito. NÃO use este campo para creditar o cliente final — use `received_amount`." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "settled_amount": { "type": [ "number", "null" ] }, "settled_currency": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "tags": [ "Cripto" ], "summary": "Criar depósito em cripto", "description": "Escopo: charges:write. Preço em USD; liquidação sempre no saldo USDT, com a taxa aplicável à conta descontada na liquidação, quando houver. O mínimo comercial é definido por moeda/rede (USDT: 20; demais moedas: 15) e, por cima dele, vale o mínimo técnico dinâmico da rede — aplica-se o maior dos dois. Idempotência forte: external_id no corpo OU header Idempotency-Key — mesmo identificador com payload diferente retorna 409. Em falha transitória (timeout, 202, erro de rede) REUTILIZE a mesma Idempotency-Key/external_id: trocar o identificador é a única forma de gerar um depósito duplicado. Um external_id só serve a um depósito, mesmo depois de expirado — novo depósito exige novo identificador.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Opcional (proteção avançada). Se enviada, use 8 a 255 caracteres: chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header presente porém fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pay_currency" ], "properties": { "amount": { "type": "number", "example": 100, "description": "Valor em USD. Respeita o mínimo comercial da moeda/rede e o mínimo técnico dinâmico da rede." }, "pay_currency": { "type": "string", "enum": [ "usdttrc20", "usdtbsc", "btc", "eth", "ltc", "sol", "usdc", "trx", "xrp", "doge", "bnbbsc", "ton", "ada", "bch", "dai" ] }, "external_id": { "type": "string", "example": "player-deposit-1" }, "customer_id": { "type": "string", "example": "player-9182" }, "description": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "Idempotente: depósito já existente", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "ccr_8a1c0b3f9e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_charge" ] }, "status": { "type": "string", "enum": [ "processing", "waiting", "confirming", "partially_paid", "paid", "failed", "expired", "refunded" ], "description": "Status do depósito. `processing` é transitório: o endereço ainda está sendo provisionado ou recuperado — repita a MESMA Idempotency-Key/external_id até receber `waiting`. `paid` significa RECEBIMENTO CONFIRMADO e é terminal. A diferença entre esperado e recebido NÃO aparece no status, e sim nos campos de valor: `paid_amount` (recebido on-chain, na `pay_currency`), `received_amount` (valor liquidado em USD/USDT — use este para creditar o cliente final) e `amount_status` (`underpaid` | `exact` | `overpaid`). `partially_paid` é LEGADO: nenhum fluxo atual o produz e ele permanece no enum apenas por compatibilidade histórica — pode aparecer somente em depósitos antigos criados antes da mudança. Não implemente lógica nova para esse status." }, "external_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Identificador do jogador/cliente NO SEU sistema. Não cria saldo próprio na BluntPay." }, "metadata": { "type": [ "object", "null" ] }, "price_amount": { "type": "number", "description": "Valor cobrado, em USD." }, "price_currency": { "type": "string", "enum": [ "usd" ] }, "pay_amount": { "type": [ "number", "null" ], "description": "Quantidade a pagar na moeda escolhida." }, "pay_currency": { "type": "string", "example": "usdttrc20" }, "paid_amount": { "type": [ "number", "null" ], "description": "Quantidade REALMENTE recebida on-chain, na mesma `pay_currency` (ex.: TRX, BTC). Serve para auditoria/reconciliação blockchain — NÃO é um valor em USD/USDT e não deve ser usado para creditar saldo em USD/USDT." }, "received_amount": { "type": [ "number", "null" ], "description": "Valor efetivamente liquidado em USD/USDT. ESTE é o campo que integrações com saldo em USD/USDT devem usar para creditar o cliente/jogador. `null` enquanto não houver evidência autoritativa suficiente." }, "amount_status": { "type": [ "string", "null" ], "enum": [ "underpaid", "exact", "overpaid", null ], "description": "Comparação (com tolerância) entre `paid_amount` e `pay_amount`: `underpaid` entrou menos, `exact` entrou o esperado, `overpaid` entrou mais. `null` enquanto não houver recebimento." }, "pay_address": { "type": [ "string", "null" ], "description": "Endereço on-chain para o jogador depositar." }, "pay_extra_id": { "type": [ "string", "null" ], "description": "Memo/tag, quando a rede exigir." }, "network": { "type": [ "string", "null" ] }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver, descontada na liquidação." }, "net_amount": { "type": [ "number", "null" ] }, "credited_amount": { "type": [ "number", "null" ], "description": "Líquido que entrou no saldo USDT do MERCHANT na BluntPay, após as taxas. `null` enquanto não houver crédito. NÃO use este campo para creditar o cliente final — use `received_amount`." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "settled_amount": { "type": [ "number", "null" ] }, "settled_currency": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "201": { "description": "Depósito criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "ccr_8a1c0b3f9e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_charge" ] }, "status": { "type": "string", "enum": [ "processing", "waiting", "confirming", "partially_paid", "paid", "failed", "expired", "refunded" ], "description": "Status do depósito. `processing` é transitório: o endereço ainda está sendo provisionado ou recuperado — repita a MESMA Idempotency-Key/external_id até receber `waiting`. `paid` significa RECEBIMENTO CONFIRMADO e é terminal. A diferença entre esperado e recebido NÃO aparece no status, e sim nos campos de valor: `paid_amount` (recebido on-chain, na `pay_currency`), `received_amount` (valor liquidado em USD/USDT — use este para creditar o cliente final) e `amount_status` (`underpaid` | `exact` | `overpaid`). `partially_paid` é LEGADO: nenhum fluxo atual o produz e ele permanece no enum apenas por compatibilidade histórica — pode aparecer somente em depósitos antigos criados antes da mudança. Não implemente lógica nova para esse status." }, "external_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Identificador do jogador/cliente NO SEU sistema. Não cria saldo próprio na BluntPay." }, "metadata": { "type": [ "object", "null" ] }, "price_amount": { "type": "number", "description": "Valor cobrado, em USD." }, "price_currency": { "type": "string", "enum": [ "usd" ] }, "pay_amount": { "type": [ "number", "null" ], "description": "Quantidade a pagar na moeda escolhida." }, "pay_currency": { "type": "string", "example": "usdttrc20" }, "paid_amount": { "type": [ "number", "null" ], "description": "Quantidade REALMENTE recebida on-chain, na mesma `pay_currency` (ex.: TRX, BTC). Serve para auditoria/reconciliação blockchain — NÃO é um valor em USD/USDT e não deve ser usado para creditar saldo em USD/USDT." }, "received_amount": { "type": [ "number", "null" ], "description": "Valor efetivamente liquidado em USD/USDT. ESTE é o campo que integrações com saldo em USD/USDT devem usar para creditar o cliente/jogador. `null` enquanto não houver evidência autoritativa suficiente." }, "amount_status": { "type": [ "string", "null" ], "enum": [ "underpaid", "exact", "overpaid", null ], "description": "Comparação (com tolerância) entre `paid_amount` e `pay_amount`: `underpaid` entrou menos, `exact` entrou o esperado, `overpaid` entrou mais. `null` enquanto não houver recebimento." }, "pay_address": { "type": [ "string", "null" ], "description": "Endereço on-chain para o jogador depositar." }, "pay_extra_id": { "type": [ "string", "null" ], "description": "Memo/tag, quando a rede exigir." }, "network": { "type": [ "string", "null" ] }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver, descontada na liquidação." }, "net_amount": { "type": [ "number", "null" ] }, "credited_amount": { "type": [ "number", "null" ], "description": "Líquido que entrou no saldo USDT do MERCHANT na BluntPay, após as taxas. `null` enquanto não houver crédito. NÃO use este campo para creditar o cliente final — use `received_amount`." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "settled_amount": { "type": [ "number", "null" ] }, "settled_currency": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "202": { "description": "Depósito aceito e em provisionamento/recuperação (status `processing`). Nenhuma cobrança adicional será criada. Repita a MESMA Idempotency-Key até o status final.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "ccr_8a1c0b3f9e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_charge" ] }, "status": { "type": "string", "enum": [ "processing", "waiting", "confirming", "partially_paid", "paid", "failed", "expired", "refunded" ], "description": "Status do depósito. `processing` é transitório: o endereço ainda está sendo provisionado ou recuperado — repita a MESMA Idempotency-Key/external_id até receber `waiting`. `paid` significa RECEBIMENTO CONFIRMADO e é terminal. A diferença entre esperado e recebido NÃO aparece no status, e sim nos campos de valor: `paid_amount` (recebido on-chain, na `pay_currency`), `received_amount` (valor liquidado em USD/USDT — use este para creditar o cliente final) e `amount_status` (`underpaid` | `exact` | `overpaid`). `partially_paid` é LEGADO: nenhum fluxo atual o produz e ele permanece no enum apenas por compatibilidade histórica — pode aparecer somente em depósitos antigos criados antes da mudança. Não implemente lógica nova para esse status." }, "external_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Identificador do jogador/cliente NO SEU sistema. Não cria saldo próprio na BluntPay." }, "metadata": { "type": [ "object", "null" ] }, "price_amount": { "type": "number", "description": "Valor cobrado, em USD." }, "price_currency": { "type": "string", "enum": [ "usd" ] }, "pay_amount": { "type": [ "number", "null" ], "description": "Quantidade a pagar na moeda escolhida." }, "pay_currency": { "type": "string", "example": "usdttrc20" }, "paid_amount": { "type": [ "number", "null" ], "description": "Quantidade REALMENTE recebida on-chain, na mesma `pay_currency` (ex.: TRX, BTC). Serve para auditoria/reconciliação blockchain — NÃO é um valor em USD/USDT e não deve ser usado para creditar saldo em USD/USDT." }, "received_amount": { "type": [ "number", "null" ], "description": "Valor efetivamente liquidado em USD/USDT. ESTE é o campo que integrações com saldo em USD/USDT devem usar para creditar o cliente/jogador. `null` enquanto não houver evidência autoritativa suficiente." }, "amount_status": { "type": [ "string", "null" ], "enum": [ "underpaid", "exact", "overpaid", null ], "description": "Comparação (com tolerância) entre `paid_amount` e `pay_amount`: `underpaid` entrou menos, `exact` entrou o esperado, `overpaid` entrou mais. `null` enquanto não houver recebimento." }, "pay_address": { "type": [ "string", "null" ], "description": "Endereço on-chain para o jogador depositar." }, "pay_extra_id": { "type": [ "string", "null" ], "description": "Memo/tag, quando a rede exigir." }, "network": { "type": [ "string", "null" ] }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver, descontada na liquidação." }, "net_amount": { "type": [ "number", "null" ] }, "credited_amount": { "type": [ "number", "null" ], "description": "Líquido que entrou no saldo USDT do MERCHANT na BluntPay, após as taxas. `null` enquanto não houver crédito. NÃO use este campo para creditar o cliente final — use `received_amount`." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "settled_amount": { "type": [ "number", "null" ] }, "settled_currency": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "409": { "description": "idempotency_conflict" }, "422": { "description": "invalid_request, unsupported_currency, below_minimum, charge_failed" } } } }, "/crypto/charges/{id}": { "get": { "tags": [ "Cripto" ], "summary": "Consultar depósito em cripto", "description": "Escopo: charges:read. Aceita o id `ccr_...` ou `ext:`. Nenhum lojista lê depósito de outro. Os webhooks crypto.charge.* são o caminho principal de confirmação; este GET é o fallback/reconciliação e faz sync-on-read em estados não terminais (waiting, confirming), sincronizando a situação autoritativa antes de responder. Nunca assuma pagamento por leitura própria de saldo/endereço on-chain.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Depósito", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "ccr_8a1c0b3f9e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_charge" ] }, "status": { "type": "string", "enum": [ "processing", "waiting", "confirming", "partially_paid", "paid", "failed", "expired", "refunded" ], "description": "Status do depósito. `processing` é transitório: o endereço ainda está sendo provisionado ou recuperado — repita a MESMA Idempotency-Key/external_id até receber `waiting`. `paid` significa RECEBIMENTO CONFIRMADO e é terminal. A diferença entre esperado e recebido NÃO aparece no status, e sim nos campos de valor: `paid_amount` (recebido on-chain, na `pay_currency`), `received_amount` (valor liquidado em USD/USDT — use este para creditar o cliente final) e `amount_status` (`underpaid` | `exact` | `overpaid`). `partially_paid` é LEGADO: nenhum fluxo atual o produz e ele permanece no enum apenas por compatibilidade histórica — pode aparecer somente em depósitos antigos criados antes da mudança. Não implemente lógica nova para esse status." }, "external_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Identificador do jogador/cliente NO SEU sistema. Não cria saldo próprio na BluntPay." }, "metadata": { "type": [ "object", "null" ] }, "price_amount": { "type": "number", "description": "Valor cobrado, em USD." }, "price_currency": { "type": "string", "enum": [ "usd" ] }, "pay_amount": { "type": [ "number", "null" ], "description": "Quantidade a pagar na moeda escolhida." }, "pay_currency": { "type": "string", "example": "usdttrc20" }, "paid_amount": { "type": [ "number", "null" ], "description": "Quantidade REALMENTE recebida on-chain, na mesma `pay_currency` (ex.: TRX, BTC). Serve para auditoria/reconciliação blockchain — NÃO é um valor em USD/USDT e não deve ser usado para creditar saldo em USD/USDT." }, "received_amount": { "type": [ "number", "null" ], "description": "Valor efetivamente liquidado em USD/USDT. ESTE é o campo que integrações com saldo em USD/USDT devem usar para creditar o cliente/jogador. `null` enquanto não houver evidência autoritativa suficiente." }, "amount_status": { "type": [ "string", "null" ], "enum": [ "underpaid", "exact", "overpaid", null ], "description": "Comparação (com tolerância) entre `paid_amount` e `pay_amount`: `underpaid` entrou menos, `exact` entrou o esperado, `overpaid` entrou mais. `null` enquanto não houver recebimento." }, "pay_address": { "type": [ "string", "null" ], "description": "Endereço on-chain para o jogador depositar." }, "pay_extra_id": { "type": [ "string", "null" ], "description": "Memo/tag, quando a rede exigir." }, "network": { "type": [ "string", "null" ] }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver, descontada na liquidação." }, "net_amount": { "type": [ "number", "null" ] }, "credited_amount": { "type": [ "number", "null" ], "description": "Líquido que entrou no saldo USDT do MERCHANT na BluntPay, após as taxas. `null` enquanto não houver crédito. NÃO use este campo para creditar o cliente final — use `received_amount`." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "settled_amount": { "type": [ "number", "null" ] }, "settled_currency": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "not_found" } } } }, "/crypto/payouts": { "get": { "tags": [ "Cripto" ], "summary": "Listar saques em cripto", "description": "Escopo: payouts:read. Retorna os saques em cripto da conta autenticada, do mais recente para o mais antigo.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Lista de saques em cripto", "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": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cpo_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_payout" ] }, "status": { "type": "string", "enum": [ "requested", "processing", "completed", "failed" ], "description": "Saques criados pela API entram em processing imediatamente (sem aprovação manual). completed é terminal." }, "currency": { "type": "string", "enum": [ "usdtbsc", "trx", "btc", "ltc", "usdterc20" ] }, "amount": { "type": "number", "description": "Principal solicitado em USDT. A taxa de rede fica fora de `fee` e é descontada do valor entregue on-chain." }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver. Debitada além do amount." }, "conversion_fee": { "type": "number", "description": "Parcela de conversão (1%) já incluída em fee, em USDT. Informativo — nunca somar duas vezes." }, "net_amount": { "type": "number", "description": "Igual a amount — valor enviado on-chain." }, "gross_amount": { "type": "number", "description": "amount + fee — total debitado do saldo." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "origin": { "type": "string", "enum": [ "api", "panel" ] }, "external_id": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ], "description": "Hash da transação, disponível após a confirmação da rede." }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "has_more": { "type": "boolean" } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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": [ "Cripto" ], "summary": "Criar saque em cripto (trx, usdtbsc, btc, ltc, usdterc20)", "description": "Escopo: payouts:write.\n\nSaques criados pela API são automáticos quando a conta está habilitada para cash-out cripto via API e a operação está dentro das regras/limites da conta, sujeitos a saldo, mínimo, validações, idempotência e disponibilidade da rede.\n\nMoedas aceitas: `trx` (TRX · Tron), `usdtbsc` (USDT · BNB Chain BEP20), `btc` (Bitcoin), `ltc` (Litecoin) e `usdterc20` (USDT · Ethereum ERC20). Qualquer outra moeda/rede, inclusive `usdttrc20`, é recusada com `unsupported_currency`.\n\nO saldo/referência da conta permanece SEMPRE em USDT: o `amount` é o principal em USDT e é convertido integralmente para a moeda escolhida pela cotação vigente antes do envio. `fee` é o total de taxas comerciais cobradas POR FORA do saldo e `conversion_fee` é um subset informativo já incluído em `fee` — nunca somar duas vezes. A taxa de rede é variável, paga pelo destinatário (receiver-paid): fica FORA de `fee` e reduz somente o valor recebido.\n\nO endereço deve pertencer à rede da moeda escolhida; endereço de outra rede é recusado com `invalid_address` antes de qualquer débito.\n\nIdempotência é OBRIGATÓRIA: informe `external_id` no corpo ou o header `Idempotency-Key`.\nMesmo identificador com payload idêntico devolve o mesmo saque, sem novo débito;\npayload diferente devolve 409 `idempotency_conflict`. O identificador é escopado por conta.\n\nMínimo efetivo (dinâmico): max(mínimo comercial BluntPay de 20 USDT, mínimo técnico dinâmico real de saque da rede). Consulte `GET /crypto/payouts/minimum` antes de criar; o POST revalida o mínimo de qualquer forma. Abaixo disso a criação é recusada (`below_minimum` / `below_network_minimum`).\nSaques criados pela API são automáticos quando a conta está habilitada e a operação está dentro das regras/limites da conta, sujeitos a saldo, mínimo, validações, idempotência e disponibilidade da rede.\nO `amount` é o principal solicitado em USDT; taxas comerciais são debitadas adicionalmente do saldo (`gross_amount = amount + fee`). A taxa de rede NÃO entra em `fee` e é descontada do valor entregue on-chain, portanto `receive_estimated` pode ser menor que o equivalente a `amount`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Opcional (proteção avançada). Se enviada, use 8 a 255 caracteres: chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header presente porém fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "address" ], "properties": { "amount": { "type": "number", "minimum": 20, "description": "Principal solicitado em USDT. Tarifas comerciais são debitadas adicionalmente do saldo; a tarifa de rede fica fora de `fee` e é descontada do valor entregue on-chain. Respeita o mínimo efetivo dinâmico (mínimo comercial ou mínimo técnico real da rede)." }, "currency": { "type": "string", "enum": [ "trx", "usdtbsc", "btc", "ltc", "usdterc20" ], "description": "Moeda/rede de saída. usdttrc20 não é aceito no saque." }, "address": { "type": "string", "minLength": 6, "maxLength": 200, "description": "Endereço de destino, válido na rede da moeda escolhida (Tron, BNB Chain, Bitcoin, Litecoin ou Ethereum/ERC20)." }, "extra_id": { "type": "string", "maxLength": 80, "description": "Memo/tag, quando a rede de destino exigir." }, "external_id": { "type": "string", "maxLength": 120, "description": "Seu identificador; obrigatório se não enviar Idempotency-Key." } } }, "example": { "amount": 100, "currency": "usdtbsc", "address": "0x55d398326f99059fF775485246999027B3197955", "external_id": "saque-jogador-9182" } } } }, "responses": { "201": { "description": "Saque criado (processing) ou saque já existente para o mesmo identificador", "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": "cpo_3f9a1c0b8e7d4a2b9c1d0e5f6a7b8c9d" }, "object": { "type": "string", "enum": [ "crypto_payout" ] }, "status": { "type": "string", "enum": [ "requested", "processing", "completed", "failed" ], "description": "Saques criados pela API entram em processing imediatamente (sem aprovação manual). completed é terminal." }, "currency": { "type": "string", "enum": [ "usdtbsc", "trx", "btc", "ltc", "usdterc20" ] }, "amount": { "type": "number", "description": "Principal solicitado em USDT. A taxa de rede fica fora de `fee` e é descontada do valor entregue on-chain." }, "fee": { "type": "number", "description": "Tarifa aplicável à conta, quando houver. Debitada além do amount." }, "conversion_fee": { "type": "number", "description": "Parcela de conversão (1%) já incluída em fee, em USDT. Informativo — nunca somar duas vezes." }, "net_amount": { "type": "number", "description": "Igual a amount — valor enviado on-chain." }, "gross_amount": { "type": "number", "description": "amount + fee — total debitado do saldo." }, "settlement_currency": { "type": "string", "enum": [ "usdt" ] }, "origin": { "type": "string", "enum": [ "api", "panel" ] }, "external_id": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ], "description": "Hash da transação, disponível após a confirmação da rede." }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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": "idempotency_conflict — mesmo external_id/Idempotency-Key com payload diferente", "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": "invalid_request, unsupported_currency, invalid_address, below_minimum, below_network_minimum, insufficient_balance, extra_id_required, currency_unavailable, crypto_disabled", "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/payouts/minimum": { "get": { "tags": [ "Cripto" ], "summary": "Mínimo vigente de saque em cripto", "description": "Escopo: payouts:read.\n\nDevolve o mínimo EFETIVO atual de saque em cripto: max(mínimo comercial BluntPay, mínimo técnico dinâmico real da rede).\nConsulta ao vivo, sem cache. Consulte este endpoint antes de criar o saque; o POST /crypto/payouts revalida o mínimo novamente no momento da criação.\nQuando o mínimo não puder ser determinado, a resposta é 503 `minimum_unavailable` — nunca um valor estimado.", "responses": { "200": { "description": "Mínimo vigente", "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": { "currency": { "type": "string", "example": "USDT" }, "network": { "type": "string", "example": "TRC20" }, "min_amount": { "type": "number", "example": 20 }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "currency": "USDT", "network": "TRC20", "min_amount": 20, "updated_at": "2026-08-18T06:55:00.000Z" } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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": "minimum_unavailable — mínimo indisponível no momento", "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/payouts/estimate": { "get": { "tags": [ "Cripto" ], "summary": "Estimativa de saque em cripto", "description": "Escopo: payouts:read.\n\nSimula um saque ANTES de criar, usando exatamente as mesmas fontes do POST /crypto/payouts (catálogo de moedas, taxas da conta, conversão, cotação real e custo de rede). Não cria saque nem reserva saldo.\n`amount` é o principal em USDT destinado ao destinatário; `fee` é o total comercial cobrado POR FORA do saldo (`total_debit = amount + fee`) e `conversion_fee` é um subset informativo de `fee`.\n`network_fee_estimated` é uma ESTIMATIVA conservadora, paga pelo destinatário: fica fora de `fee`, fora do débito e reduz apenas o valor entregue. O custo real da rede varia até a confirmação on-chain.", "parameters": [ { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "minimum": 20 }, "description": "Principal em USDT." }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "trx", "usdtbsc", "btc", "ltc", "usdterc20" ] }, "description": "Moeda/rede de saída." } ], "responses": { "200": { "description": "Estimativa calculada", "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": { "example": { "object": "crypto_payout_estimate", "currency": "usdtbsc", "network": "BNB Chain (BEP20)", "amount": 100, "fee": 3, "conversion_fee": 1, "total_debit": 103, "rate": 0.9972, "send_amount": 99.72, "network_fee_estimated": 0.04, "receive_estimated": 99.68, "receive_estimated_usdt": 99.96 } } } }, "400": { "description": "Corpo inválido ou Idempotency-Key malformada (invalid_idempotency_key)", "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: EXTERNAL_ID_CONFLICT (mesmo external_id com dados materiais diferentes — amount na cobrança; amount ou pix_key no saque), IDEMPOTENCY_CONFLICT (mesma Idempotency-Key com corpo diferente), idempotency_key_in_progress (mesma chave ainda em processamento — repita em alguns segundos com a mesma chave) ou external_id_in_progress (criação com o mesmo external_id ainda em andamento; aguarde retry_after e consulte pelo mesmo external_id, não gere outro pedido).", "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": "unsupported_currency / invalid_amount", "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": "estimate_unavailable — estimativa indisponível no momento", "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" } } } } } } } } } } } } } }, "/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": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Opcional (proteção avançada). Se enviada, use 8 a 255 caracteres: chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header presente porém fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "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": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Opcional (proteção avançada). Se enviada, use 8 a 255 caracteres: chave nova para cada operação nova e exatamente a mesma chave ao repetir a MESMA operação após timeout ou falha de rede. Reenvio com o mesmo corpo devolve a resposta original com o header idempotent-replayed: true; mesma chave com corpo diferente devolve 409 IDEMPOTENCY_CONFLICT; mesma chave ainda em processamento devolve 409 idempotency_key_in_progress. Header presente porém fora de 8-255 caracteres devolve 400 invalid_idempotency_key." } ], "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" } } } } } } } } }