{ "openapi": "3.1.0", "info": { "version": "1.5.0", "title": "Saq Pix API", "description": "REST API for Pix operations on the Saq platform, deposits, withdrawals, internal transfers, infractions, reports, and callback inspection. All amounts are in BRL (reais) unless explicitly noted. Authentication uses a Bearer token issued during onboarding.\n\n## SDKs oficiais\n\n- Node.js: `npm install saq-pix`\n- Python: `pip install saq-pix`\n- Go: `go get __STRIP_SDK_REF__/go`\n- PHP: `composer require saq/pix`\n\nRepo: https://__STRIP_SDK_REF__\n" }, "servers": [ { "url": "https://api.saq.processamento.com/v1", "description": "Produção" } ], "tags": [ { "name": "Pix Operations", "description": "Create and manage Pix charges (deposits)" }, { "name": "Withdrawals", "description": "Send money via Pix (cash out) and DICT key/QR-code consultation" }, { "name": "Internal Transfer", "description": "Transfer funds between Saq accounts (free, instant)" }, { "name": "Account", "description": "Account profile, balance, and auto-withdraw configuration" }, { "name": "Reports", "description": "Transaction history, reports, bank statements, and pending deposits" }, { "name": "Callbacks", "description": "Webhook callback inspection and re-trigger" }, { "name": "Infractions", "description": "Manage Pix infractions (disputes, fraud reports) and submit defenses" } ], "paths": { "/pix": { "post": { "summary": "Create Charge (Pix deposit)", "description": "Create a new Pix **deposit** (charge). Returns QR Code and transaction details.", "operationId": "post_pix", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Amount in BRL. Must be >= 1.", "example": 10.9, "minimum": 1 }, "callbackUrl": { "type": "string", "description": "URL to receive `transaction updated` webhooks.", "example": "https://webhook.cool/" }, "generatedName": { "type": "string", "description": "Payer full name. Letters and spaces only.", "example": "John Doe" }, "generatedEmail": { "type": "string", "description": "Payer email (optional).", "example": "john.doe@example.com" }, "generatedDocument": { "type": "string", "description": "Payer CPF (11 digits) or CNPJ (14 digits), no punctuation.", "example": "12345678901" }, "expiresIn": { "type": "number", "description": "Seconds until the QR Code expires. Default: 600.", "example": 600, "maximum": 172000 }, "clientReference": { "type": "string", "description": "External reference (order, invoice, etc.).", "example": "order_12345", "maxLength": 64 }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta virtual (até 50 caracteres) para correlacionar lojas, filiais, marketplaces. Volta no callback." } } } } } }, "responses": { "200": { "description": "Charge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "created": { "summary": "Created (PENDING)", "value": { "id": "SAQ20250817215911F49RDOBJ", "status": "PENDING", "amount": 10, "type": "DEPOSIT", "callbackUrl": "https://webhook.cool/", "qrCodeText": "00020126870014br.gov.bcb.pix2565qrcode.saq.com.br/dynamic/d7790b91-3979-4ad5-9d96-ee941e5a42765204000053039865802BR5908SAQPLUS6009SAO PAULO62070503***63047EE4", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAAC...", "qrCodeUrl": "https://pix.saq.com.br/v1/pix/qr-code/SAQ20250817215911F49RDOBJ", "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.115, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": null, "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": "513579", "endToEndId": null, "createdAt": "2025-08-17T21:59:11.579Z", "updatedAt": "2025-08-17T21:59:11.579Z", "paidAt": null, "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] }, "get": { "summary": "Retrieve Charge", "description": "Get the latest status and details for a Pix **deposit (charge)**. Provide **one** of `id`, `clientReference`, or `endToEndId`. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro.", "operationId": "get_pix", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "query", "name": "id", "required": false, "description": "Transaction ID.", "schema": { "type": "string" }, "example": "SAQ20250817215911F49RDOBJ" }, { "in": "query", "name": "clientReference", "required": false, "description": "External reference provided when creating the charge.", "schema": { "type": "string" } }, { "in": "query", "name": "endToEndId", "required": false, "description": "Pix end-to-end ID.", "schema": { "type": "string" } }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta virtual (até 50 caracteres) usada na criação. Aceito como chave de busca alternativa." } ], "responses": { "200": { "description": "Current transaction state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "pending": { "summary": "Pending payment", "value": { "id": "SAQ20250817215911F49RDOBJ", "status": "PENDING", "amount": 10, "type": "DEPOSIT", "callbackUrl": "https://webhook.cool/", "qrCodeText": "00020126870014br.gov.bcb.pix2565qrcode.saq.com.br/dynamic/d7790b91-3979-4ad5-9d96-ee941e5a42765204000053039865802BR5908SAQPLUS6009SAO PAULO62070503***63047EE4", "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAAC...", "qrCodeUrl": "https://pix.saq.com.br/v1/pix/qr-code/SAQ20250817215911F49RDOBJ", "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.115, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": null, "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": "513579", "endToEndId": null, "createdAt": "2025-08-17T21:59:11.579Z", "updatedAt": "2025-08-17T21:59:11.579Z", "paidAt": null, "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Completed payment", "value": { "id": "SAQ20250817215911F49RDOBJ", "status": "COMPLETED", "amount": 10, "type": "DEPOSIT", "callbackUrl": "https://webhook.cool/", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": "John Doe", "generatedDocument": "12345678901", "generatedEmail": "john.doe@example.com", "serviceFeeCharged": 0.115, "payerName": "John Doe", "payerDocument": "12345678901", "payerInstitutionIspb": "12345678", "payerInstitutionName": "Banco X", "payerAccountNumber": null, "receiverName": "Saq Pagamentos Ltda", "receiverDocument": "12.345.678/0001-00", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "SAQ IP LTDA.", "receiverAccountNumber": "513579", "endToEndId": "E123456782025081422403B13DMS72H9", "createdAt": "2025-08-17T21:59:11.579Z", "updatedAt": "2025-08-17T22:01:30.123Z", "paidAt": "2025-08-17T22:01:30.123Z", "withdrawPixKey": null, "withdrawPixType": null, "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/pix/key": { "get": { "summary": "Dict Pix Key Lookup", "description": "Query the DICT (Diretório de Identificadores de Contas Transacionais) to retrieve information about a Pix key before sending a payment. Returns the key owner's details and associated financial institution.", "operationId": "get_pix_key", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "query", "name": "pixKey", "required": true, "description": "The Pix key to lookup (CPF, CNPJ, email, phone, or EVP).", "schema": { "type": "string", "maxLength": 77, "minLength": 1 }, "example": "example@saq.com.br" } ], "responses": { "200": { "description": "Pix key information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixKeyInfo" }, "examples": { "pj": { "summary": "Legal Entity (PJ)", "value": { "pixKey": "5c8999e2-6b29-468b-b4e9-04d4872b1bc4", "document": "**.345.678/****-**", "name": "EMPRESA EXEMPLO LTDA", "branch": "****", "accountNumber": "*******", "personType": "PJ", "accountType": "CACC", "institutionIspb": "12345678", "institutionCode": "001", "institutionName": "BANCO EXEMPLO S.A." } }, "pf": { "summary": "Individual (PF)", "value": { "pixKey": "12345678901", "document": "***.456.789-**", "name": "João da Silva", "branch": "****", "accountNumber": "********", "personType": "PF", "accountType": "TRAN", "institutionIspb": "87654321", "institutionCode": "260", "institutionName": "BANCO FICTICIO S.A." } } } } } }, "400": { "description": "Invalid Pix key format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_PIX_KEY" }, "message": { "type": "string", "example": "The provided Pix key has an invalid format." } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Pix key not found in DICT", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PIX_KEY_NOT_FOUND" }, "message": { "type": "string", "example": "The specified Pix key was not found in DICT." } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/pix/qrcode/read": { "post": { "summary": "Read QR Code", "description": "Decode and extract information from a Pix QR Code (EMV format) before making a payment. Returns the parsed data including receiver details, amount (if present), and other QR Code metadata. No momento a Saq só suporta QR Code dinâmico. QR estático ainda não é processado.", "operationId": "post_pix_qrcode_read", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emv" ], "properties": { "emv": { "type": "string", "description": "The EMV payload string from the Pix QR Code.", "example": "00020101021226770014br.gov.bcb.pix2555api.saq/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916SAQ 6007SAOPAULO6217051320260118278956304EC55" } } } } } }, "responses": { "200": { "description": "QR Code decoded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QRCodeReadResponse" }, "examples": { "dynamic": { "summary": "Dynamic QR Code", "value": { "qrCodeType": "DYNAMIC", "name": "LOJA EXEMPLO LTDA", "document": "12345678000199", "amount": 10, "originalAmount": 10, "txid": "c5886b83f0254d0dbfc3900f72d5a8d1", "additionalInfo": null, "expiresIn": 1799, "createdAt": "2026-02-03T22:59:36.138" } }, "static": { "summary": "Static QR Code", "value": { "qrCodeType": "STATIC", "name": "MARIA SANTOS", "document": "98765432100", "amount": 1, "originalAmount": 1, "txid": "QRTEST20251103083119867", "additionalInfo": null, "expiresIn": 0, "createdAt": null } } } } } }, "400": { "description": "Invalid QR Code format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "INVALID_QR_CODE" }, "message": { "type": "string", "example": "The provided EMV payload is invalid or malformed." } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] } }, "/proof/{id}": { "get": { "summary": "Get Transaction Receipt", "description": "Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`.", "operationId": "get_proof", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "id", "required": true, "description": "Transaction ID.", "schema": { "type": "string" }, "example": "SAQ2025081418333632CYKN8M" }, { "in": "query", "name": "type", "required": false, "description": "Return format.", "schema": { "type": "string", "enum": [ "pdf", "base64" ], "default": "pdf" }, "example": "pdf" } ], "responses": { "200": { "description": "Base64 if `type=base64`, otherwise binary PDF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "base64": { "type": "string" } } }, "examples": { "base64": { "summary": "As Base64", "value": { "base64": "JVBERi0xLjQKJ..." } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/withdraw": { "post": { "summary": "Create Withdrawal (Pix key)", "description": "Send a Pix **cash out** to the specified Pix key.", "operationId": "post_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pixKey", "pixType" ], "properties": { "amount": { "type": "number", "description": "Amount in BRL. Must be >= 1.", "example": 2, "minimum": 0.01 }, "pixKey": { "type": "string", "description": "Destination Pix key.", "example": "teste@teste.com" }, "pixType": { "type": "string", "description": "Pix key type.", "enum": [ "cpf", "cnpj", "phone", "email", "evp" ], "example": "email" }, "callbackUrl": { "type": "string", "description": "Webhook URL for status updates.", "example": "https://webhook.cool/" }, "clientReference": { "type": "string", "description": "External reference for this withdrawal.", "example": "withdraw_98765", "maxLength": 64 }, "description": { "type": "string", "description": "Optional description.", "example": "Weekly payout" }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta virtual (até 50 caracteres) para correlacionar lojas, filiais, marketplaces. Volta no callback." } } } } } }, "responses": { "200": { "description": "Withdrawal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "created": { "summary": "Created (PENDING)", "value": { "id": "SAQ2025081721512946OOLK75", "status": "PENDING", "amount": 2, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "513579", "serviceFeeCharged": 1, "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-08-17T21:51:29.748Z", "updatedAt": "2025-08-17T21:51:29.748Z", "paidAt": null, "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Completed", "value": { "id": "SAQ2025081721512946OOLK75", "status": "COMPLETED", "amount": 2, "type": "WITHDRAW", "callbackUrl": "https://webhook.cool/", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": "Saq Pagamentos Ltda", "payerDocument": "12.345.678/0001-00", "payerInstitutionIspb": "23066240", "payerInstitutionName": "SAQ IP LTDA.", "payerAccountNumber": "513579", "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "receiverInstitutionIspb": "87654321", "receiverInstitutionName": "Banco Y", "receiverAccountNumber": null, "endToEndId": "E2306624020251217134500X98765432", "createdAt": "2025-08-17T21:51:29.748Z", "updatedAt": "2025-08-17T21:52:15.123Z", "paidAt": "2025-08-17T21:52:15.123Z", "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] }, "get": { "summary": "Retrieve Withdrawal", "description": "Get the latest status and details for a **withdrawal**. You can provide any **one** of the following parameters: `id`, `clientReference`, or `endToEndId`. All three are optional and you can use any one of them to retrieve the withdrawal. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro.", "operationId": "get_withdraw", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "query", "name": "id", "required": false, "description": "Transaction ID.", "schema": { "type": "string" }, "example": "SAQ2025081721512946OOLK75" }, { "in": "query", "name": "clientReference", "required": false, "description": "External reference provided when creating the withdrawal.", "schema": { "type": "string" } }, { "in": "query", "name": "endToEndId", "required": false, "description": "Pix end-to-end ID.", "schema": { "type": "string" } }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta virtual (até 50 caracteres) usada na criação. Aceito como chave de busca alternativa." } ], "responses": { "200": { "description": "Current withdrawal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "pending": { "summary": "Pending withdrawal", "value": { "id": "SAQ2025081721512946OOLK75", "status": "PENDING", "amount": 2, "type": "WITHDRAW", "callbackUrl": "https://webhook.cool/", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "513579", "serviceFeeCharged": 1, "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-08-17T21:51:29.748Z", "updatedAt": "2025-08-17T21:51:29.748Z", "paidAt": null, "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "completed": { "summary": "Completed withdrawal", "value": { "id": "SAQ2025081721512946OOLK75", "status": "COMPLETED", "amount": 2, "type": "WITHDRAW", "callbackUrl": "https://webhook.cool/", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": "Saq Pagamentos Ltda", "payerDocument": "12.345.678/0001-00", "payerInstitutionIspb": "23066240", "payerInstitutionName": "SAQ IP LTDA.", "payerAccountNumber": "513579", "withdrawPixKey": "teste@teste.com", "withdrawPixType": "email", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "receiverInstitutionIspb": "87654321", "receiverInstitutionName": "Banco Y", "receiverAccountNumber": null, "endToEndId": "E2306624020251217134500X98765432", "createdAt": "2025-08-17T21:51:29.748Z", "updatedAt": "2025-08-17T21:52:15.123Z", "paidAt": "2025-08-17T21:52:15.123Z", "clientReference": "withdraw_98765", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/withdraw/qrcode": { "post": { "summary": "Create Withdrawal using QR Code", "description": "Cash out using a **Pix QR Code** (static/dynamic). If `amount` is not provided, the QR Code's embedded value will be used. No momento a Saq só suporta QR Code dinâmico. QR estático ainda não é processado.", "operationId": "post_withdraw_qrcode", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "qrCode" ], "properties": { "qrCode": { "type": "string", "description": "Pix QR Code payload (EMV format).", "example": "00020101021226770014br.gov.bcb.pix2555api.saq/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916SAQ 6007SAOPAULO6217051320260118278956304EC55" }, "amount": { "type": "number", "description": "Amount in BRL. Optional - if not provided, uses the QR Code's embedded value.", "example": 20, "minimum": 0.1 }, "callbackUrl": { "type": "string", "description": "Webhook URL for status updates.", "example": "https://webhook.cool/" }, "description": { "type": "string", "description": "Optional description for the payment.", "example": "Pagamento via QR Code" }, "clientReference": { "type": "string", "description": "External reference for this withdrawal.", "example": "order-123" }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta virtual (até 50 caracteres) para correlacionar lojas, filiais, marketplaces. Volta no callback." } } } } } }, "responses": { "200": { "description": "Withdrawal created from QR Code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "with_amount": { "summary": "Created with custom amount", "value": { "id": "SAQ202511061998787515D0PH2Y", "status": "PENDING", "amount": 20, "type": "WITHDRAW", "callbackUrl": "https://bright-lightning-66.webhook.cool", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "513579", "withdrawPixKey": "88888888888", "withdrawPixType": "cpf", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-11-06T19:08:55.848Z", "updatedAt": "2025-11-06T19:08:55.848Z", "paidAt": null, "clientReference": "order-123", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } }, "without_amount": { "summary": "Created using QR Code value", "value": { "id": "SAQ202511061998787515D0PH2Z", "status": "PENDING", "amount": 150, "type": "WITHDRAW", "callbackUrl": "https://bright-lightning-66.webhook.cool", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 1, "payerName": null, "payerDocument": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "payerAccountNumber": "513579", "withdrawPixKey": "example@saq.com.br", "withdrawPixType": "email", "receiverName": null, "receiverDocument": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "receiverAccountNumber": null, "endToEndId": null, "createdAt": "2025-11-06T19:10:00.000Z", "updatedAt": "2025-11-06T19:10:00.000Z", "paidAt": null, "clientReference": "order-12323456", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Invalid QR Code or missing amount for static QR Code without value", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "AMOUNT_REQUIRED" }, "message": { "type": "string", "example": "Amount is required for QR Codes without embedded value." } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] } }, "/withdraw/proof/{id}": { "get": { "summary": "Get Withdrawal Receipt", "description": "Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`.", "operationId": "get_withdraw_proof", "tags": [ "Withdrawals" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "id", "required": true, "description": "Transaction ID.", "schema": { "type": "string" }, "example": "SAQ2025081721512946OOLK75" }, { "in": "query", "name": "type", "required": false, "description": "Return format.", "schema": { "type": "string", "enum": [ "pdf", "base64" ], "default": "pdf" }, "example": "pdf" } ], "responses": { "200": { "description": "Base64 if `type=base64`, otherwise binary PDF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "base64": { "type": "string" } } }, "examples": { "base64": { "summary": "As Base64", "value": { "base64": "JVBERi0xLjQKJ..." } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user": { "get": { "summary": "Account Info", "description": "Account profile, permissions, limits and fee rules.", "operationId": "get_user", "tags": [ "Account" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Account data", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountNumber": { "type": "string", "nullable": true, "description": "Public account identifier (6 digits, unique). Used as destination for internal transfers." }, "name": { "type": "string" }, "role": { "type": "string" }, "balanceAvailable": { "type": "number" }, "balanceBlocked": { "type": "number" }, "status": { "type": "string" }, "allowWithdraw": { "type": "boolean" }, "allowDeposit": { "type": "boolean" }, "allowInfraction": { "type": "boolean" }, "cashInTicketMin": { "type": "number" }, "cashInTicketMax": { "type": "number" }, "cashOutTicketMin": { "type": "number" }, "cashOutTicketMax": { "type": "number" }, "AutoWithdraw": { "type": "object", "nullable": true }, "ServiceFee": { "type": "object", "properties": { "cashInMinimum": { "type": "number" }, "cashInFixed": { "type": "number" }, "cashInPercent": { "type": "number" }, "cashOutMinimum": { "type": "number" }, "cashOutFixed": { "type": "number" }, "cashOutPercent": { "type": "number" } } }, "DailyWithdrawLimit": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int32" }, "used": { "type": "number" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastReset": { "type": "string", "format": "date-time" } } } } }, "examples": { "ok": { "summary": "Account information", "value": { "accountNumber": "513579", "name": "SAQ", "role": "USER", "balanceAvailable": 231.46, "balanceBlocked": 0, "status": "ACTIVE", "allowWithdraw": true, "allowDeposit": true, "allowInfraction": true, "cashInTicketMin": 1, "cashInTicketMax": 50000, "cashOutTicketMin": 1, "cashOutTicketMax": 100000, "AutoWithdraw": null, "ServiceFee": { "cashInMinimum": 0, "cashInFixed": 0, "cashInPercent": 0, "cashOutMinimum": 0, "cashOutFixed": 0, "cashOutPercent": 0 }, "DailyWithdrawLimit": { "limit": 100000000, "used": 40000, "updatedAt": "2025-10-21T21:16:47.759Z", "lastReset": "2025-10-21T21:16:47.759Z" } } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." } ] } }, "/user/balance": { "get": { "summary": "Account Balance", "description": "Available and blocked balances.", "operationId": "get_user_balance", "tags": [ "Account" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceAvailable": { "type": "number" }, "balanceBlocked": { "type": "number" } } }, "examples": { "ok": { "summary": "Current balance", "value": { "balanceAvailable": 231.46, "balanceBlocked": 0 } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." } ] } }, "/user/transactions": { "get": { "summary": "List Transactions", "description": "Paginated list of account transactions with filters.", "operationId": "get_user_transactions", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "query", "name": "dateFrom", "required": false, "description": "Start date (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-08-01" }, { "in": "query", "name": "dateTo", "required": false, "description": "End date (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-08-17" }, { "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000).", "schema": { "type": "number", "default": 10 }, "example": 10 }, { "in": "query", "name": "page", "required": false, "description": "Page number (default 1).", "schema": { "type": "number", "default": 1 }, "example": 1 }, { "in": "query", "name": "id", "required": false, "description": "Transaction ID.", "schema": { "type": "string" }, "example": "SAQ2025081418333632CYKN8M" }, { "in": "query", "name": "status", "required": false, "description": "Status da transação. Aceita CSV: PENDING,COMPLETED,etc.", "schema": { "type": "string", "example": "COMPLETED,PENDING" }, "example": "COMPLETED" }, { "in": "query", "name": "type", "required": false, "description": "Tipo da transação. Aceita CSV: DEPOSIT,WITHDRAW,COMMISSION.", "schema": { "type": "string", "example": "DEPOSIT,WITHDRAW" }, "example": "DEPOSIT" }, { "in": "query", "name": "amount", "required": false, "description": "Amount filter.", "schema": { "type": "number" }, "example": 15000 }, { "in": "query", "name": "document", "required": false, "description": "CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números sem formatação.", "schema": { "type": "string", "pattern": "^[0-9]{11,14}$" }, "example": "12345678901" }, { "in": "query", "name": "name", "required": false, "description": "Name filter.", "schema": { "type": "string" }, "example": "Alice" }, { "in": "query", "name": "endToEndId", "required": false, "description": "Pix end-to-end ID.", "schema": { "type": "string" }, "example": "E00360305202508141833bcf1f37b487" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" }, "description": "Field to sort by" }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction" }, { "name": "clientReference", "in": "query", "schema": { "type": "string" }, "description": "Filter by external reference" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta virtual (até 50 caracteres) usada na criação. Aceito como chave de busca alternativa." } ], "responses": { "200": { "description": "Transaction page", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "pages": { "type": "integer", "format": "int32" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "examples": { "two": { "summary": "Two deposits", "value": { "total": 104, "pages": 2, "transactions": [ { "id": "SAQ202511061998787515D0PH2Y", "amount": 10, "status": "PENDING", "type": "DEPOSIT", "callbackUrl": "https://webhook.site/9cdd5879-5767-4e95-bf57-1ac29e0ad3d7", "qrCodeText": "00020126860014br.gov.bcb.pix2564qrcode.saq.com.br/pix/84f95c33-3c86-4708-87f1-0e09b96b35795204000053039865802BR5908PAYZPLUS6009SAO PAULO62070503***63048227", "qrCodeBase64": null, "qrCodeUrl": "https://pix.saq.com.br/v1/pix/qr-code/SAQ202511061998787515D0PH2Y", "serviceFeeCharged": 0.115, "payerDocument": null, "payerName": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "receiverDocument": null, "receiverName": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "generatedDocument": "00000000191", "generatedName": "THIAGO SILVA", "generatedEmail": null, "endToEndId": null, "withdrawPixKey": null, "withdrawPixType": null, "paidAt": null, "createdAt": "2025-11-06T22:06:19.598Z", "updatedAt": "2025-11-06T22:06:19.598Z", "clientReference": "order_12345", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null }, { "id": "SAQ202511061998787515D0PH2Y", "amount": 5.5, "status": "ERROR", "type": "WITHDRAW", "callbackUrl": "https://webhook.site/9cdd5879-5767-4e95-bf57-1ac29e0ad3d7", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "serviceFeeCharged": 1, "payerDocument": null, "payerName": null, "payerInstitutionIspb": null, "payerInstitutionName": null, "receiverDocument": null, "receiverName": null, "receiverInstitutionIspb": null, "receiverInstitutionName": null, "generatedDocument": null, "generatedName": null, "generatedEmail": null, "endToEndId": null, "withdrawPixKey": "88888888888", "withdrawPixType": "cpf", "paidAt": null, "createdAt": "2025-11-06T19:08:55.848Z", "updatedAt": "2025-11-06T19:09:13.602Z", "clientReference": null, "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": "PIX_KEY_NOT_FOUND" } ] } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/callbacks": { "get": { "summary": "List Callbacks", "description": "Returns a paginated list of webhook callback logs for the user's transactions.", "operationId": "get_user_callbacks", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "status" ], "default": "createdAt" } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Filter by callback ID" }, { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "Filter by callback URL" }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "HTTP status code" }, { "name": "transactionId", "in": "query", "schema": { "type": "string" } }, { "name": "hasError", "in": "query", "schema": { "type": "boolean" }, "description": "Filter callbacks that errored" }, { "name": "createdAtFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdAtTo", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "List of callback logs with pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackListResponse" }, "examples": { "list": { "summary": "Callback log page", "value": { "pagination": { "page": 1, "limit": 10, "hasNextPage": true }, "callbacks": [ { "id": "cmh211yjm03ohs601kf7672du", "url": "https://great-lock-79.webhook.cool", "status": 200, "transactionId": "SAQ2025102213082667EDC8079C", "createdAt": "2025-10-22T13:26:53.219Z", "responseTime": 124, "body": { "id": "SAQ2025102213082667EDC8079C", "type": "DEPOSIT", "status": "REFUNDED" }, "responseBody": "OK", "responseHeaders": { "content-type": "text/plain; charset=UTF-8" } } ] } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/callbacks/{id}": { "get": { "summary": "Get Callback", "description": "Returns the details of a specific callback log.", "operationId": "get_user_callback_by_id", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique callback ID" } ], "responses": { "200": { "description": "Callback details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackDetail" }, "examples": { "detail": { "summary": "Single callback log", "value": { "id": "cmh211yjm03ohs601kf7672du", "url": "https://great-lock-79.webhook.cool", "status": 200, "transactionId": "SAQ2025102213082667EDC8079C", "createdAt": "2025-10-22T13:26:53.219Z", "responseTime": 124, "body": { "id": "SAQ2025102213082667EDC8079C", "type": "DEPOSIT", "status": "REFUNDED" }, "responseBody": "OK", "responseHeaders": { "content-type": "text/plain; charset=UTF-8" } } } } } } }, "404": { "description": "Callback not found or does not belong to the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/infractions": { "get": { "summary": "List Infractions", "description": "List all infractions for the authenticated user with pagination and filters.", "operationId": "get_infractions", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated InfractionStatus (WAITING_PSP,CLOSED,OPEN,CANCELLED,ACKNOWLEDGED,DEFENDED,ANSWERED,WAITING_ADJUSTMENTS)" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated InfractionType (REFUND_REQUEST,FRAUD,REFUND_CANCELLED)" }, { "name": "endToEndId", "in": "query", "schema": { "type": "string" } }, { "name": "transactionId", "in": "query", "schema": { "type": "string" } }, { "name": "amountMin", "in": "query", "schema": { "type": "number" } }, { "name": "amountMax", "in": "query", "schema": { "type": "number" } }, { "name": "analysisResult", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated AnalysisResult" }, { "name": "reportedBy", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated ReportedType (DEBITED_PARTICIPANT,CREDITED_PARTICIPANT)" }, { "name": "participantDocument", "in": "query", "schema": { "type": "string" } }, { "name": "participantName", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of infractions with pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionListResponse" }, "examples": { "success": { "summary": "List with infractions", "value": { "infractions": [ { "id": "infraction_id", "protocol": "PROTOCOL123", "status": "OPEN", "type": "FRAUD", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Transação não autorizada", "analysisResult": null, "analysisDetails": null, "reportedAt": "2024-01-15T10:30:00Z", "expiresAt": "2024-02-15T10:30:00Z", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z", "transaction": { "id": "transaction_id", "amount": 100.5, "payerName": "João Silva", "payerDocument": "12345678901", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "endToEndId": "E12345678202401151030001" }, "defenseHistory": [] } ], "pagination": { "page": 1, "limit": 20, "totalItems": 45, "totalPages": 3 } } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/infractions/{id}": { "get": { "summary": "Get Infraction", "description": "Get a specific infraction by ID.", "operationId": "get_infractions_by_id", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Infraction ID" } ], "responses": { "200": { "description": "Infraction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfractionDetail" }, "examples": { "success": { "summary": "Infraction details", "value": { "id": "infraction_123", "protocol": "PROTOCOL123", "status": "OPEN", "type": "FRAUD", "reportedBy": "DEBITED_PARTICIPANT", "reportDetails": "Transação não autorizada", "analysisResult": null, "analysisDetails": null, "reportedAt": "2024-01-15T10:30:00Z", "expiresAt": "2024-02-15T10:30:00Z", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z", "transaction": { "id": "transaction_id", "amount": 100.5, "payerName": "João Silva", "payerDocument": "12345678901", "receiverName": "Maria Santos", "receiverDocument": "12345678901", "endToEndId": "E12345678202401151030001" }, "defenseHistory": [] } } } } } }, "404": { "description": "Infraction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/infractions/{id}/defenses": { "post": { "summary": "Create Defense", "description": "Create a defense for a specific infraction.", "operationId": "post_infractions_defense", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Infraction ID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "defense" ], "properties": { "defense": { "type": "string", "maxLength": 1000, "description": "Defense text (max: 1000 characters)" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Evidence files (max: 10MB total)" } } } } } }, "responses": { "201": { "description": "Defense created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Defense" }, "examples": { "success": { "summary": "Defense created successfully", "value": { "id": "defense_id", "defense": "Esta transação foi devidamente autorizada pelo cliente através do app mobile.", "status": "PENDING", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-16T14:20:00Z", "files": [ { "name": "evidencia1.pdf", "mimeType": "application/pdf", "size": 245760, "url": "https://storage.googleapis.com/bucket/signed-url-1" } ] } } } } } }, "400": { "description": "Invalid file or provider does not support defense", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Infraction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "422": { "description": "Infraction not open for defense", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 422, "error": "Unprocessable Entity", "message": "Insufficient balance for this operation", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } }, "get": { "summary": "List Defenses", "description": "List all defenses for a specific infraction. **Requires support privileges**.", "operationId": "get_infractions_defenses", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Infraction ID" } ], "responses": { "200": { "description": "List of defenses", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Defense" } }, "examples": { "success": { "summary": "List of defenses", "value": [ { "id": "defense_id_1", "defense": "Primeira defesa enviada", "status": "DEFENDED", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-17T09:15:00Z", "files": [] } ] } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/infractions/{infractionId}/defenses/{defenseId}": { "get": { "summary": "Get Defense", "description": "Get a specific defense for an infraction. **Requires support privileges**.", "operationId": "get_infractions_defense_by_id", "tags": [ "Infractions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "in": "path", "name": "infractionId", "required": true, "schema": { "type": "string" }, "description": "Infraction ID" }, { "in": "path", "name": "defenseId", "required": true, "schema": { "type": "string" }, "description": "Defense ID" } ], "responses": { "200": { "description": "Defense details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Defense" }, "examples": { "success": { "summary": "Defense details", "value": { "id": "defense_id", "defense": "Esta transação foi devidamente autorizada.", "status": "DEFENDED", "infractionId": "infraction_123", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-17T09:15:00Z", "files": [ { "name": "evidencia1.pdf", "size": 245760, "mimeType": "application/pdf", "url": "https://storage.googleapis.com/bucket/signed-url-1" } ] } } } } } }, "404": { "description": "Defense not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/internal-transfer": { "post": { "summary": "Create internal transfer", "description": "Send funds to another Saq account using its 6-digit accountNumber. Settles instantly within Saq.", "operationId": "post_internal_transfer", "tags": [ "Internal Transfer" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payerAccountNumber", "receiverAccountNumber", "amount" ], "properties": { "payerAccountNumber": { "type": "string", "pattern": "^\\d{6}$", "description": "Payer account number (6 digits). Must match the authenticated user's accountNumber.", "example": "513579" }, "receiverAccountNumber": { "type": "string", "pattern": "^\\d{6}$", "description": "Destination account number (6 digits).", "example": "987654" }, "amount": { "type": "number", "minimum": 0.01, "description": "Transfer amount in BRL.", "example": 100.5 }, "description": { "type": "string", "maxLength": 500, "description": "Optional transfer description.", "example": "Pagamento referente a fatura #1234" }, "callbackUrl": { "type": "string", "format": "uri", "description": "URL to receive transaction-update webhooks.", "example": "https://webhook.cool/" }, "clientReference": { "type": "string", "maxLength": 64, "description": "External reference for idempotency / reconciliation.", "example": "transfer_abc_123" }, "virtualAccount": { "type": "string", "maxLength": 50, "description": "Subconta virtual (até 50 caracteres) para correlacionar lojas, filiais, marketplaces. Volta no callback." } } } } } }, "responses": { "200": { "description": "Transfer completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "completed": { "summary": "Transfer completed (debit side, payer view)", "value": { "id": "SAQ20260506T142500ABC123", "status": "COMPLETED", "amount": 100.5, "type": "WITHDRAW", "callbackUrl": null, "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 0, "payerName": "Joao Silva", "payerDocument": "12345678901", "payerInstitutionIspb": "23066240", "payerInstitutionName": "SAQ IP LTDA.", "payerAccountNumber": "513579", "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Maria Santos", "receiverDocument": "98765432109", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "SAQ IP LTDA.", "receiverAccountNumber": "987654", "endToEndId": null, "clientReference": "transfer_abc_123", "createdAt": "2026-05-06T14:25:00.000Z", "updatedAt": "2026-05-06T14:25:00.123Z", "paidAt": "2026-05-06T14:25:00.123Z", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Invalid payload (e.g. payerAccountNumber does not belong to the requester)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "403": { "description": "allowInternalTransfer disabled or token missing WITHDRAW permission", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 403, "error": "Forbidden", "message": "Token does not have permission for this operation", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Receiver account not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "422": { "description": "Insufficient balance / amount below ticket minimum", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 422, "error": "Unprocessable Entity", "message": "Insufficient balance for this operation", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] }, "get": { "summary": "Get internal transfer", "description": "Retrieve an internal transfer by id or clientReference Use apenas um destes parâmetros: id, clientReference. Combinar mais de um retorna erro.", "operationId": "get_internal_transfer", "tags": [ "Internal Transfer" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Transaction ID" }, { "name": "clientReference", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "External reference" }, { "name": "virtualAccount", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 50 }, "description": "Subconta virtual (até 50 caracteres) usada na criação. Aceito como chave de busca alternativa." } ], "responses": { "200": { "description": "Transfer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "found": { "summary": "Lookup by clientReference", "value": { "id": "SAQ20260506T142500ABC123", "status": "COMPLETED", "amount": 100.5, "type": "WITHDRAW", "callbackUrl": null, "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 0, "payerName": "Joao Silva", "payerDocument": "12345678901", "payerInstitutionIspb": "23066240", "payerInstitutionName": "SAQ IP LTDA.", "payerAccountNumber": "513579", "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Maria Santos", "receiverDocument": "98765432109", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "SAQ IP LTDA.", "receiverAccountNumber": "987654", "endToEndId": null, "clientReference": "transfer_abc_123", "createdAt": "2026-05-06T14:25:00.000Z", "updatedAt": "2026-05-06T14:25:00.123Z", "paidAt": "2026-05-06T14:25:00.123Z", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null } } } } } }, "400": { "description": "Provide either `id` or `clientReference`", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Transfer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/transactions/{id}": { "get": { "summary": "List transaction details", "description": "Retrieve a single transaction with its callback log and linked infractions.", "operationId": "get_user_transaction_by_id", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "infractions": { "type": "array", "description": "Histórico completo de infrações desta transação.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "callbackLogs": { "type": "array", "description": "Webhook delivery attempts for this transaction (most recent first)", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "integer", "description": "HTTP status code returned by the receiver" }, "responseTime": { "type": "number", "description": "Round-trip time in ms" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } ] } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/report": { "post": { "summary": "Generate transactions report", "description": "Queue an asynchronous job that generates a CSV report of transactions for the given period and filters.", "operationId": "post_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dateFrom", "dateTo" ], "properties": { "dateFrom": { "type": "string", "format": "date-time" }, "dateTo": { "type": "string", "format": "date-time" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] } }, "type": { "type": "array", "items": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAW", "COMMISSION" ] } } } } } } }, "responses": { "201": { "description": "Report job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportJob" } } } }, "422": { "description": "No transactions match the filter / concurrency limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 422, "error": "Unprocessable Entity", "message": "Insufficient balance for this operation", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] }, "get": { "summary": "List report jobs", "operationId": "list_user_reports", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "EXPIRED" ] } } ], "responses": { "200": { "description": "Page of report jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "pages": { "type": "integer" }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ReportJob" } } } }, "examples": { "list": { "value": { "total": 9, "pages": 3, "reports": [ { "id": "5224fd4e-0abb-4498-a79b-9398ea6712ad", "status": "COMPLETED", "createdAt": "2026-05-06T16:39:52.944Z", "updatedAt": "2026-05-06T16:39:53.500Z", "expiresAt": "2026-05-13T16:39:52.996Z" } ] } } } } } }, "400": { "description": "Bad Request, payload or query string failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "401": { "description": "Unauthorized, missing or invalid Bearer token, or token lacks the required permission for this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 401, "error": "Unauthorized", "message": "Missing or invalid Bearer token", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "description": "List report jobs created by the authenticated user." } }, "/user/report/{id}": { "get": { "summary": "List report job status", "operationId": "get_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportJob" }, "examples": { "completed": { "value": { "id": "5224fd4e-0abb-4498-a79b-9398ea6712ad", "status": "COMPLETED", "createdAt": "2026-05-06T16:39:52.944Z", "updatedAt": "2026-05-06T16:39:53.500Z", "expiresAt": "2026-05-13T16:39:52.996Z" } } } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "description": "List report jobs created by the authenticated user." } }, "/user/report/{id}/download": { "post": { "summary": "Download report", "description": "Returns a short-lived signed URL to download the CSV file.", "operationId": "download_user_report", "tags": [ "Reports" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signed download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Short-lived signed URL to download the CSV (5 min validity)" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the signed URL expires" } } }, "examples": { "ok": { "value": { "url": "https://storage.googleapis.com/relatorios-transacoes/relatorio-transacoes-06-05-2026_06-05-2026_5224fd4e-...csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=300&...", "expiresAt": "2026-05-06T16:48:34.889Z" } } } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "410": { "description": "Report file expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 410, "error": "Gone", "message": "Report file expired and is no longer available", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "422": { "description": "Report not ready (still processing)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 422, "error": "Unprocessable Entity", "message": "Insufficient balance for this operation", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } }, "/user/callbacks/resend": { "post": { "summary": "Re-send callbacks (bulk)", "description": "Resend callbacks in bulk for transactions matching the given filters.", "operationId": "resend_user_callbacks", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "createdAtFrom", "createdAtTo" ], "properties": { "createdAtFrom": { "type": "string", "format": "date-time", "description": "Period start (REQUIRED). Cannot be more than 30 days in the past." }, "createdAtTo": { "type": "string", "format": "date-time", "description": "Period end (REQUIRED). Period span cannot exceed 7 days." }, "transactionIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict to specific transaction IDs" }, "transactionTypes": { "type": "array", "items": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAW" ] }, "description": "Filter by transaction type" }, "transactionStatus": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] }, "description": "Filter by transaction status" }, "transactionEndToEndIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict to specific Pix end-to-end IDs" } } }, "examples": { "by_period": { "summary": "Resend everything paid in the last day", "value": { "createdAtFrom": "2026-05-05T00:00:00Z", "createdAtTo": "2026-05-06T00:00:00Z" } }, "filtered": { "summary": "Only completed deposits in a 7-day window", "value": { "createdAtFrom": "2026-04-29T00:00:00Z", "createdAtTo": "2026-05-06T00:00:00Z", "transactionTypes": [ "DEPOSIT" ], "transactionStatus": [ "COMPLETED" ] } } } } } }, "responses": { "200": { "description": "Resend dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "total": { "type": "integer", "description": "Number of callbacks dispatched" } } }, "examples": { "ok": { "value": { "message": "Callbacks reenviados com sucesso", "total": 42 } } } } } }, "404": { "description": "No matching transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "429": { "description": "Rate limit exceeded (5/min)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 429, "error": "Too Many Requests", "message": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "parameters": [] } }, "/user/callbacks/resend/{transactionId}": { "post": { "summary": "Re-send callback (single)", "operationId": "resend_user_callback_single", "tags": [ "Callbacks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resend dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "ok": { "value": { "message": "Callback reenviado com sucesso" } } } } } }, "404": { "description": "Transaction not found or has no callbackUrl configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "429": { "description": "Rate limit exceeded (5/min)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 429, "error": "Too Many Requests", "message": "Limite de reenvios atingido. Tente novamente em 1 minuto.", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } }, "description": "Resend the callback of a single transaction." } }, "/pix/qr-code/{transactionId}": { "get": { "summary": "Render Pix QR code (PNG)", "description": "Render the Pix QR Code of a deposit as a binary PNG image", "operationId": "get_pix_qrcode", "tags": [ "Pix Operations" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ], "default": "application/json" }, "description": "Obrigatório em toda chamada Saq." }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "QR code image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Transaction is not a DEPOSIT or has no QR code", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 400, "error": "Bad Request", "message": "querystring/dateFrom Invalid input: expected string, received undefined", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "examples": { "error": { "value": { "statusCode": 404, "error": "Not Found", "message": "Resource not found", "requestId": "cmou00000abcdef01s6ghij1k2lm" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Transaction": { "type": "object", "properties": { "id": { "type": "string", "nullable": false }, "status": { "type": "string", "nullable": false, "description": "PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR" }, "amount": { "type": "number", "nullable": false }, "type": { "type": "string", "nullable": false, "description": "DEPOSIT or WITHDRAW" }, "callbackUrl": { "type": "string", "nullable": true }, "qrCodeText": { "type": "string", "nullable": true }, "qrCodeBase64": { "type": "string", "nullable": true }, "qrCodeUrl": { "type": "string", "nullable": true }, "generatedName": { "type": "string", "nullable": true }, "generatedDocument": { "type": "string", "nullable": true }, "generatedEmail": { "type": "string", "nullable": true }, "payerName": { "type": "string", "nullable": true }, "payerDocument": { "type": "string", "nullable": true }, "payerInstitutionIspb": { "type": "string", "nullable": true }, "payerInstitutionName": { "type": "string", "nullable": true }, "payerAccountNumber": { "type": "string", "nullable": true, "description": "Payer's Saq account number (6 digits). Present only on internal-transfer transactions." }, "serviceFeeCharged": { "type": "number", "nullable": true }, "withdrawPixKey": { "type": "string", "nullable": true }, "withdrawPixType": { "type": "string", "nullable": true }, "receiverName": { "type": "string", "nullable": true }, "receiverDocument": { "type": "string", "nullable": true }, "receiverInstitutionIspb": { "type": "string", "nullable": true }, "receiverInstitutionName": { "type": "string", "nullable": true }, "receiverAccountNumber": { "type": "string", "nullable": true, "description": "Receiver's Saq account number (6 digits). Present only on internal-transfer transactions." }, "endToEndId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": false }, "updatedAt": { "type": "string", "nullable": false }, "paidAt": { "type": "string", "nullable": true }, "clientReference": { "type": "string", "nullable": true }, "refundEndToEndId": { "type": "string", "nullable": true, "description": "End-to-end ID of the refund transaction" }, "refundAmount": { "type": "string", "nullable": true, "description": "Amount refunded" }, "refundStatus": { "type": "string", "nullable": true, "description": "Status of the refund (PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR)" }, "refundReason": { "type": "string", "nullable": true, "description": "Reason for the refund" }, "refundDescription": { "type": "string", "nullable": true, "description": "Description of the refund" }, "refundedAt": { "type": "string", "nullable": true, "description": "Date and time when the refund was processed" }, "cancellationReason": { "type": "string", "nullable": true, "description": "Reason for cancellation (if cancelled)" }, "infraction": { "type": "object", "nullable": true, "description": "Infraction details if the transaction has been disputed", "properties": { "id": { "type": "string" }, "protocol": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING_PSP", "CLOSED", "OPEN", "CANCELLED", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_ADJUSTMENTS" ] }, "type": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ] }, "reportDetails": { "type": "string" }, "reportedBy": { "type": "string", "enum": [ "DEBITED_PARTICIPANT", "CREDITED_PARTICIPANT" ] }, "analysisResult": { "type": "string", "nullable": true }, "analysisDetails": { "type": "string", "nullable": true }, "reportedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "virtualAccount": { "type": "string", "nullable": true, "maxLength": 50, "description": "Subconta virtual informada na criação." } }, "description": "Unified transaction representation used by all endpoints." }, "PixKeyInfo": { "type": "object", "description": "Information about a Pix key from DICT lookup.", "properties": { "pixKey": { "type": "string", "description": "The Pix key that was looked up." }, "document": { "type": "string", "description": "CPF or CNPJ of the owner (partially masked for privacy)." }, "name": { "type": "string", "description": "Name of the Pix key owner." }, "branch": { "type": "string", "description": "Bank branch number (masked)." }, "accountNumber": { "type": "string", "description": "Account number (masked)." }, "personType": { "type": "string", "description": "Type of person.", "enum": [ "PF", "PJ" ] }, "accountType": { "type": "string", "description": "Type of account (CACC = Current Account, TRAN = Transactional Account, SVGS = Savings).", "enum": [ "CACC", "TRAN", "SVGS" ] }, "institutionIspb": { "type": "string", "description": "ISPB code of the financial institution." }, "institutionCode": { "type": "string", "description": "COMPE code of the financial institution." }, "institutionName": { "type": "string", "description": "Name of the financial institution." } } }, "QRCodeReadResponse": { "type": "object", "description": "Decoded information from a Pix QR Code.", "properties": { "qrCodeType": { "type": "string", "description": "Type of QR Code.", "enum": [ "STATIC", "DYNAMIC" ] }, "name": { "type": "string", "description": "Name of the payment receiver." }, "document": { "type": "string", "description": "CPF or CNPJ of the receiver." }, "amount": { "type": "number", "nullable": true, "description": "Amount to be paid (may differ from originalAmount for dynamic QR Codes)." }, "originalAmount": { "type": "number", "nullable": true, "description": "Original amount embedded in the QR Code." }, "txid": { "type": "string", "nullable": true, "description": "Transaction identifier." }, "additionalInfo": { "type": "string", "nullable": true, "description": "Additional information or description." }, "expiresIn": { "type": "number", "nullable": true, "description": "Seconds until QR Code expires (0 for static QR Codes)." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Creation date of the QR Code (for dynamic QR Codes)." } } }, "InfractionDetail": { "type": "object", "properties": { "id": { "type": "string" }, "protocol": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING_PSP", "CLOSED", "OPEN", "CANCELLED", "ACKNOWLEDGED", "DEFENDED", "ANSWERED", "WAITING_ADJUSTMENTS" ] }, "type": { "type": "string", "enum": [ "REFUND_REQUEST", "FRAUD", "REFUND_CANCELLED" ] }, "reportedBy": { "type": "string", "enum": [ "DEBITED_PARTICIPANT", "CREDITED_PARTICIPANT" ] }, "reportDetails": { "type": "string" }, "analysisResult": { "type": "string", "enum": [ "AGREED", "DISAGREED" ], "nullable": true }, "analysisDetails": { "type": "string", "nullable": true }, "reportedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "transaction": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "payerName": { "type": "string" }, "payerDocument": { "type": "string" }, "receiverName": { "type": "string" }, "receiverDocument": { "type": "string" }, "endToEndId": { "type": "string" } } }, "defenseHistory": { "type": "array", "items": { "$ref": "#/components/schemas/Defense" } } } }, "Defense": { "type": "object", "properties": { "id": { "type": "string" }, "defense": { "type": "string", "description": "Defense text" }, "status": { "type": "string", "enum": [ "PENDING", "DEFENDED" ], "description": "Defense status" }, "infractionId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "format": "int32" }, "url": { "type": "string", "description": "Signed URL for download (expires in 9 minutes)" } } } } } }, "InfractionListResponse": { "type": "object", "properties": { "infractions": { "type": "array", "items": { "$ref": "#/components/schemas/InfractionDetail" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "totalItems": { "type": "integer", "format": "int32" }, "totalPages": { "type": "integer", "format": "int32" } } } } }, "CallbackDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique callback ID" }, "url": { "type": "string", "description": "Webhook URL that received the callback" }, "status": { "type": "number", "description": "HTTP response status code" }, "transactionId": { "type": "string", "description": "Related transaction ID", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the callback log was created" }, "body": { "type": "object", "description": "Request body sent (parsed JSON)" }, "responseBody": { "type": "string", "description": "Response body received (string)" }, "responseHeaders": { "type": "object", "description": "Response headers (parsed JSON)" }, "responseTime": { "type": "number", "description": "Webhook round-trip time in milliseconds" } } }, "CallbackListResponse": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page", "format": "int32" }, "limit": { "type": "integer", "description": "Items per page", "format": "int32" }, "hasNextPage": { "type": "boolean", "description": "Indicates if there is a next page" } } }, "callbacks": { "type": "array", "items": { "$ref": "#/components/schemas/CallbackDetail" }, "description": "Array of callback logs" } } }, "ReportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "EXPIRED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the file expires from storage (typically 7 days after creation)" } } } } }, "externalDocs": { "description": "Documentação completa", "url": "https://docs.saq.processamento.com/docs/pix-processamento" } }