{"openapi":"3.1.0","info":{"title":"HubPix API","version":"1.0.0","description":"API para receber (PIX In), pagar (PIX Out) e sacar em USDT (BSC/BEP20), com webhooks assinados gerenciáveis pela própria API. Documentação completa: https://hubpixtech.com/docs. Valores são sempre strings decimais em reais (\"100.00\"). Saques exigem X-Secret-Key e o IP de origem na whitelist de saque."},"servers":[{"url":"https://hubpixtech.com/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Conta"},{"name":"PIX In"},{"name":"PIX Out"},{"name":"USDT"},{"name":"Extrato"},{"name":"Webhooks"},{"name":"Segurança"}],"paths":{"/balance":{"get":{"tags":["Conta"],"operationId":"getBalance","summary":"Saldo disponível e reservado","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Balance"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/account":{"get":{"tags":["Conta"],"operationId":"getAccount","summary":"Dados da conta, taxas, limites e recursos habilitados","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Account"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/pix/charges":{"post":{"tags":["PIX In"],"operationId":"createCharge","summary":"Cria cobrança PIX (QR copia e cola)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCharge"}}}},"responses":{"200":{"description":"Repetição idempotente","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"201":{"description":"Criada","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["PIX In"],"operationId":"listCharges","summary":"Lista cobranças (ou busca por externalRef)","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"externalRef","in":"query","schema":{"type":"string"},"description":"Sem `page`, devolve a transação única com esse externalRef"},{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO 8601 ou AAAA-MM-DD (horário de Brasília)"},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/pix/charges/{id}":{"get":{"tags":["PIX In"],"operationId":"getCharge","summary":"Consulta cobrança","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/pix/withdrawals":{"post":{"tags":["PIX Out"],"operationId":"createPixWithdrawal","summary":"Envia PIX (saque) — uma única tentativa","security":[{"ApiKey":[],"SecretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePixWithdrawal"}}}},"responses":{"200":{"description":"Repetição idempotente","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"201":{"description":"Criado","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["PIX Out"],"operationId":"listPixWithdrawals","summary":"Lista saques PIX","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"externalRef","in":"query","schema":{"type":"string"},"description":"Sem `page`, devolve a transação única com esse externalRef"},{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO 8601 ou AAAA-MM-DD (horário de Brasília)"},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/pix/withdrawals/{id}":{"get":{"tags":["PIX Out"],"operationId":"getPixWithdrawal","summary":"Consulta saque PIX","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/usdt/quote":{"get":{"tags":["USDT"],"operationId":"quoteUsdt","summary":"Cotação de saque em USDT (BSC/BEP20)","parameters":[{"name":"amountUsdt","in":"query","schema":{"type":"string","example":"100.00"},"description":"Quanto você quer receber em USDT"},{"name":"amountBrl","in":"query","schema":{"type":"string","example":"550.00"},"description":"Quanto quer gastar em reais (alternativa a amountUsdt)"},{"name":"network","in":"query","schema":{"type":"string","enum":["BEP20"],"default":"BEP20"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/UsdtQuote"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/usdt/withdrawals":{"post":{"tags":["USDT"],"operationId":"createUsdtWithdrawal","summary":"Saque em USDT na BSC (BEP20)","security":[{"ApiKey":[],"SecretKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUsdtWithdrawal"}}}},"responses":{"200":{"description":"Repetição idempotente","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"201":{"description":"Criado","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["USDT"],"operationId":"listUsdtWithdrawals","summary":"Lista saques USDT","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"externalRef","in":"query","schema":{"type":"string"},"description":"Sem `page`, devolve a transação única com esse externalRef"},{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO 8601 ou AAAA-MM-DD (horário de Brasília)"},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/usdt/withdrawals/{id}":{"get":{"tags":["USDT"],"operationId":"getUsdtWithdrawal","summary":"Consulta saque USDT","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/transactions":{"get":{"tags":["Extrato"],"operationId":"listTransactions","summary":"Extrato (todas as transações)","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["PIX_IN","PIX_OUT","USDT_OUT"]}},{"name":"search","in":"query","schema":{"type":"string"},"description":"id, externalRef, endToEndId ou chave PIX"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"externalRef","in":"query","schema":{"type":"string"},"description":"Sem `page`, devolve a transação única com esse externalRef"},{"name":"from","in":"query","schema":{"type":"string"},"description":"ISO 8601 ou AAAA-MM-DD (horário de Brasília)"},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/transactions/{id}":{"get":{"tags":["Extrato"],"operationId":"getTransaction","summary":"Consulta qualquer transação","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/events":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEvents","summary":"Eventos disponíveis","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"type":"string"}}}}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhooks","summary":"Lista URLs de webhook","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Webhooks"],"operationId":"createWebhook","summary":"Cadastra URL (o secret volta só nesta resposta)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhook"}}}},"responses":{"201":{"description":"Criado","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"operationId":"getWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Webhooks"],"operationId":"updateWebhook","summary":"Altera url, events, description ou active","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhook"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Webhooks"],"operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"operationId":"rotateWebhookSecret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"operationId":"testWebhook","summary":"Envia webhook.test agora","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/DeliveryResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"operationId":"listWebhookDeliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/deliveries/{deliveryId}/redeliver":{"post":{"tags":["Webhooks"],"operationId":"redeliverWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/DeliveryResult"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api-keys":{"get":{"tags":["Segurança"],"operationId":"listApiKeys","summary":"Lista as chaves da conta (criação só pelo painel, com 2FA)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api-keys/{id}":{"delete":{"tags":["Segurança"],"operationId":"revokeApiKey","summary":"Revoga uma chave (exige X-Secret-Key de um IP da whitelist de saque)","security":[{"ApiKey":[],"SecretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/ApiKey"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/ip-allowlist":{"get":{"tags":["Segurança"],"operationId":"getIpAllowlist","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/IpAllowlist"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"put":{"tags":["Segurança"],"operationId":"setIpAllowlist","summary":"Substitui as whitelists (exige X-Secret-Key de um IP já autorizado para saque)","security":[{"ApiKey":[],"SecretKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetIpAllowlist"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/IpAllowlist"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"webhooks":{"transactionEvent":{"post":{"summary":"Evento enviado para as suas URLs cadastradas","parameters":[{"name":"X-HubPix-Event","in":"header","schema":{"type":"string"}},{"name":"X-HubPix-Delivery","in":"header","schema":{"type":"string"},"description":"Id único do evento (igual ao id do corpo) — use para deduplicar"},{"name":"X-HubPix-Signature","in":"header","schema":{"type":"string","example":"t=1791000000,v1=6a1c..."},"description":"v1 = HMAC_SHA256(secret, t + \".\" + corpoBruto)"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Responda 2xx em até 10 s"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"hpx_pk_..."},"SecretKey":{"type":"apiKey","in":"header","name":"X-Secret-Key","description":"hpx_sk_... — só saques e ações sensíveis"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":100},"description":"Repetir a chamada com a mesma chave não duplica a operação"}},"responses":{"Error":{"description":"Erro","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}},"schemas":{"Balance":{"type":"object","properties":{"balance":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"1520.40","description":"Valor em reais, string decimal com ponto"},"heldBalance":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"250.00","description":"Valor em reais, string decimal com ponto"}}},"Account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PENDING","BLOCKED"]},"balance":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"heldBalance":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"fees":{"type":"object","properties":{"pixIn":{"type":"object","properties":{"percent":{"type":"string"},"fixed":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"0.00","description":"Valor em reais, string decimal com ponto"},"minimum":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"0.00","description":"Valor em reais, string decimal com ponto"}}},"pixOut":{"type":"object","properties":{"percent":{"type":"string"},"fixed":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"0.00","description":"Valor em reais, string decimal com ponto"}}},"usdt":{"type":"object","properties":{"spreadPercent":{"type":"string"}}}}},"limits":{"type":"object","properties":{"pixInMin":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"10.00","description":"Valor em reais, string decimal com ponto"},"pixInMax":{"type":["string","null"]},"pixOutMin":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"1.00","description":"Valor em reais, string decimal com ponto"},"pixOutMax":{"type":["string","null"]}}},"features":{"type":"object","properties":{"pixIn":{"type":"boolean"},"pixOut":{"type":"boolean"},"usdtOut":{"type":"boolean"},"usdtNetworks":{"type":"array","items":{"type":"string"}}}},"requestIp":{"type":"string"}}},"CreateCharge":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"externalRef":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":140},"expiresIn":{"type":"integer","minimum":60,"maximum":1800,"default":1800}}},"CreatePixWithdrawal":{"type":"object","required":["amount"],"description":"Informe pixKey + pixKeyType OU brCode","properties":{"amount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"250.00","description":"Valor em reais, string decimal com ponto"},"pixKey":{"type":"string"},"pixKeyType":{"type":"string","enum":["CPF","CNPJ","EMAIL","PHONE","EVP"]},"brCode":{"type":"string","description":"PIX copia e cola do recebedor"},"externalRef":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":140}}},"CreateUsdtWithdrawal":{"type":"object","required":["address"],"description":"Informe amountUsdt OU amountBrl","properties":{"network":{"type":"string","enum":["BEP20"],"default":"BEP20"},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountUsdt":{"type":"string","example":"100.00"},"amountBrl":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"550.00","description":"Valor em reais, string decimal com ponto"},"externalRef":{"type":"string"},"description":{"type":"string"}}},"UsdtQuote":{"type":"object","properties":{"network":{"type":"string"},"rate":{"type":"string","example":"5.4210"},"amountUsdt":{"type":"string"},"networkFeeUsdt":{"type":"string"},"amountBrl":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"feeBrl":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"totalBrl":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"validForSeconds":{"type":"integer"},"networks":{"type":"array","items":{"type":"string"}}}},"Transaction":{"type":"object","description":"Campos variam por tipo (PIX_IN / PIX_OUT / USDT_OUT)","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["PIX_IN","PIX_OUT","USDT_OUT"]},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","CANCELLED","FAILED","PROCESSING","COMPLETED","UNDER_REVIEW","REQUESTED"]},"amount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"fee":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"7.00","description":"Valor em reais, string decimal com ponto"},"netAmount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"93.00","description":"Valor em reais, string decimal com ponto"},"totalAmount":{"type":"string","pattern":"^\\d{1,12}(\\.\\d{1,2})?$","example":"100.00","description":"Valor em reais, string decimal com ponto"},"externalRef":{"type":["string","null"]},"description":{"type":["string","null"]},"qrCode":{"type":["string","null"],"description":"PIX copia e cola (só enquanto PENDING)"},"expiresAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"endToEndId":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"document":{"type":["string","null"]},"institution":{"type":["string","null"]}}},"pixKey":{"type":["string","null"]},"pixKeyType":{"type":["string","null"]},"brCode":{"type":"string"},"usdt":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"},"amount":{"type":"string"},"rate":{"type":"string"},"txHash":{"type":["string","null"]}}},"completedAt":{"type":["string","null"],"format":"date-time"},"failureReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateWebhook":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS público"},"events":{"type":"array","items":{"type":"string"},"default":["*"]},"description":{"type":"string","maxLength":140},"active":{"type":"boolean","default":true}}},"UpdateWebhook":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"active":{"type":"boolean"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","example":"whsec_..."}}}]},"Delivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"event":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"]},"attempts":{"type":"integer"},"lastHttpStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"nextAttemptAt":{"type":["string","null"]},"deliveredAt":{"type":["string","null"]},"createdAt":{"type":"string"}}},"DeliveryResult":{"type":"object","properties":{"delivered":{"type":"boolean"},"httpStatus":{"type":["integer","null"]},"error":{"type":["string","null"]},"attempts":{"type":"integer"}}},"WebhookPayload":{"type":"object","properties":{"id":{"type":"string","example":"evt_5c1a9e0b7f3d2a4e6b8c0d1f"},"event":{"type":"string","example":"pix_in.paid"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"transaction":{"$ref":"#/components/schemas/Transaction"}}}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"apiKeyHint":{"type":"string"},"active":{"type":"boolean"},"current":{"type":"boolean"},"lastUsedAt":{"type":["string","null"]},"lastUsedIp":{"type":["string","null"]},"revokedAt":{"type":["string","null"]},"createdAt":{"type":"string"}}},"IpAllowlist":{"type":"object","properties":{"api":{"type":"array","items":{"type":"string"},"description":"Vazia = qualquer IP pode usar a API"},"withdraw":{"type":"array","items":{"type":"string"},"description":"IPs autorizados a sacar"},"withdrawRequired":{"type":"boolean"},"requestIp":{"type":"string"}}},"SetIpAllowlist":{"type":"object","properties":{"api":{"type":"array","items":{"type":"string"}},"withdraw":{"type":"array","items":{"type":"string"}}}}}}}