{"openapi":"3.1.0","info":{"title":"BukioPay Transactions API","version":"1.0.0","description":"API pública para criar, listar, consultar e cancelar cobranças Pix. Valores monetários são expressos em reais."},"servers":[{"url":"https://api.bukiopay.com/api/v1","description":"Produção"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Transactions","description":"Cobranças e transações Pix"}],"paths":{"/transactions":{"post":{"tags":["Transactions"],"summary":"Criar cobrança Pix","description":"Cria uma cobrança PIX_IN. Requer o escopo transaction.create. O valor mínimo é R$ 1,00.","operationId":"createPixTransaction","x-required-scope":"transaction.create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransactionRequest"},"example":{"type":"PIX_IN","amount":100,"has_products":false,"description":"Pedido 123","customer":{"name":"Cliente Exemplo","email":"cliente@example.com"},"include_qr_image":true}}}},"responses":{"200":{"description":"Cobrança criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransactionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"501":{"description":"Tipo de transação ainda não implementado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Falha ou resultado incerto no gateway de pagamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Unavailable"}}},"get":{"tags":["Transactions"],"summary":"Listar cobranças Pix","description":"Lista cobranças da loja autenticada. Requer o escopo transaction.verify.","operationId":"listTransactions","x-required-scope":"transaction.verify","parameters":[{"name":"type","in":"query","schema":{"type":"string","default":"PIX_IN"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/TransactionStatus"}},{"name":"has_products","in":"query","schema":{"type":"boolean"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"dateFrom","in":"query","description":"Início inclusivo em ISO 8601.","schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","description":"Fim exclusivo em ISO 8601.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Lista paginada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTransactionsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/transactions/{id}":{"parameters":[{"$ref":"#/components/parameters/TransactionId"}],"get":{"tags":["Transactions"],"summary":"Consultar cobrança Pix","description":"Retorna uma cobrança da loja autenticada. Requer transaction.verify.","operationId":"getTransaction","x-required-scope":"transaction.verify","responses":{"200":{"description":"Cobrança encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTransactionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}},"delete":{"tags":["Transactions"],"summary":"Cancelar cobrança Pix","description":"Marca internamente uma cobrança não paga como cancelada. Não cancela uma cobrança já concluída. Requer transaction.create.","operationId":"cancelTransaction","x-required-scope":"transaction.create","responses":{"200":{"description":"Cobrança cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelTransactionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"webhooks":{"paymentPaid":{"post":{"summary":"Pagamento Pix confirmado","description":"Enviado para a webhook URL configurada na API key. Valide X-Webhook-Signature usando o corpo JSON bruto.","parameters":[{"name":"X-Webhook-Event","in":"header","required":true,"schema":{"type":"string","const":"payment.paid"}},{"name":"X-Webhook-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Webhook-Signature","in":"header","required":true,"description":"t=<unix-seconds>,v1=<hmac-sha256-hex>","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPaidWebhook"}}}},"responses":{"200":{"description":"Webhook processado pelo integrador"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key sk_live_...","description":"API key criada no painel BukioPay."}},"parameters":{"TransactionId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"TransactionStatus":{"type":"string","enum":["PENDING","COMPLETED","CANCELLED","FAILED"]},"CustomerInput":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"Customer":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"document":{"type":["string","null"]}}},"Payment":{"type":["object","null"],"properties":{"copyPaste":{"type":["string","null"],"description":"Código Pix copia e cola EMV."},"qrCodeBase64":{"type":["string","null"],"description":"PNG do QR Code em base64 puro."},"qrcodeUrl":{"type":["string","null"],"description":"URL HTTP(S) ou data URL da imagem do QR Code."}}},"CreateTransactionRequest":{"type":"object","required":["type","amount"],"properties":{"type":{"type":"string","const":"PIX_IN"},"amount":{"type":"number","minimum":1,"description":"Valor em reais."},"has_products":{"type":"boolean","default":false},"description":{"type":"string"},"customer":{"$ref":"#/components/schemas/CustomerInput"},"include_qr_image":{"type":"boolean","default":true}}},"Transaction":{"type":"object","required":["id","type","status","amount","currency"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","const":"PIX_IN"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"amount":{"type":"number"},"feeAmount":{"type":"number"},"netAmount":{"type":"number"},"has_products":{"type":"boolean"},"hasProducts":{"type":"boolean","description":"Usado em webhooks."},"coverFee":{"type":"boolean"},"currency":{"type":"string","const":"BRL"},"description":{"type":["string","null"]},"customer":{"$ref":"#/components/schemas/Customer"},"payment":{"$ref":"#/components/schemas/Payment"},"externalReference":{"type":["string","null"]},"gateway":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"}}},"CreateTransactionResponse":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Transaction"},"requestId":{"type":"string"}}},"GetTransactionResponse":{"type":"object","required":["success","data","requestId"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Transaction"},"requestId":{"type":"string"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}},"ListTransactionsData":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ListTransactionsResponse":{"type":"object","required":["success","data","requestId"],"properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/ListTransactionsData"},"requestId":{"type":"string"}}},"CancelTransactionResponse":{"type":"object","properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"CANCELLED"}}},"requestId":{"type":"string"}}},"PaymentPaidWebhook":{"type":"object","required":["event","data","requestId","createdAt"],"properties":{"event":{"type":"string","const":"payment.paid"},"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"PIX_IN"},"status":{"type":"string","const":"paid"},"amount":{"type":"number"},"currency":{"type":"string","const":"BRL"},"hasProducts":{"type":"boolean"},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"document":{"type":["string","null"]}}},"externalReference":{"type":["string","null"]},"referenceId":{"type":["string","null"]},"paidAt":{"type":"string","format":"date-time"}}},"requestId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{},"retryable":{"type":"boolean"},"requestId":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API key ausente ou inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Loja não autorizada ou escopo ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Transação não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Limite de requisições excedido","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Serviço temporariamente indisponível","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}