{ "openapi": "3.0.3", "info": { "title": "API Contas", "version": "2.0.0", "description": "Visão Geral da API Contas\n\nConsulte o saldo e o extrato, envie Pix por chave, acompanhe cada pagamento até a confirmação, tire o comprovante, transfira entre contas do banco." }, "servers": [ { "url": "https://bank.granseuk.com/api/v2" } ], "tags": [ { "name": "Autenticação" }, { "name": "Conta" }, { "name": "Pix" }, { "name": "Transferência entre contas" } ], "paths": { "/oauth/token": { "post": { "tags": [ "Autenticação" ], "summary": "Obter token de acesso", "description": "Troca o clientId e o clientSecret por um token de acesso (OAuth 2.0, client credentials). O token vale 1 hora; use-o em Authorization: Bearer nas demais rotas. Aceita JSON, formulário (client_id, client_secret, grant_type) ou Authorization: Basic base64(clientId:clientSecret).\n\nexpiresAt é o instante de expiração em segundos Unix.\n\nO token deixa de valer na hora em que a chave é revogada.", "operationId": "oauthToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Os 14 primeiros caracteres da sua chave de API (ex.: sk_live_AbCdEf) ou o id da chave." }, "clientSecret": { "type": "string", "description": "A chave de API completa (sk_live_…)." }, "grantType": { "type": "string", "description": "Sempre client_credentials." }, "scope": { "type": "string", "description": "Ignorado: o token carrega todas as permissões da chave." } }, "required": [ "clientId", "clientSecret", "grantType" ] }, "example": { "clientId": "sk_live_AbCdEf", "clientSecret": "sk_live_AbCdEf…chave-completa", "grantType": "client_credentials" } } } }, "responses": { "201": { "description": "Token emitido", "content": { "application/json": { "example": { "tokenType": "Bearer", "expiresAt": 1792529169, "refreshExpiresIn": 0, "notBeforePolicy": 0, "accessToken": "v2t_Zk3q…", "scope": "account.read transactions.read pix.read cob.read cob.write pix.write" } } } }, "401": { "description": "clientId ou clientSecret inválidos, ou chave revogada/expirada", "content": { "application/json": { "example": { "type": "onz-0001", "title": "Invalid credentials", "status": 401, "detail": "clientId ou clientSecret invalidos, ou chave revogada/expirada", "instance": "/api/v2/oauth/token", "statusCode": 401, "error": "invalid_client", "message": "clientId ou clientSecret invalidos, ou chave revogada/expirada" } } } } }, "security": [] } }, "/accounts/balances": { "get": { "tags": [ "Conta" ], "summary": "Consultar saldo da conta", "description": "Saldo em reais. available é o que pode ser gasto agora; blocked, o que está retido (por uma análise do banco, por exemplo).", "operationId": "balances", "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "eventDate": "2026-10-20T14:00:00.000Z", "balanceAmount": { "currency": "BRL", "available": 1234.56, "blocked": 0, "overdraft": 0 } } ] } } } } }, "security": [ { "OAuth2": [ "account.read" ] } ] } }, "/accounts/transactions": { "get": { "tags": [ "Conta" ], "summary": "Consultar transações da conta", "description": "O extrato da conta, mais recente primeiro. As datas são inclusivas (fuso de São Paulo).\n\ncreditDebitType: CREDIT é entrada, DEBIT é saída. transactionAmount.available e amount trazem o mesmo valor.", "operationId": "transactions", "parameters": [ { "name": "event_date_start", "in": "query", "required": false, "description": "Data inicial (ISO 8601; só o dia é usado).", "schema": { "type": "string", "format": "date-time" } }, { "name": "event_date_end", "in": "query", "required": false, "description": "Data final (ISO 8601; só o dia é usado).", "schema": { "type": "string", "format": "date-time" } }, { "name": "page_offset", "in": "query", "required": false, "description": "Posição inicial (itens a pular). Padrão 0.", "schema": { "type": "integer" } }, { "name": "page_limit", "in": "query", "required": false, "description": "Itens por página, até 100. Padrão 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "meta": { "total": 1, "limit": 25, "offset": 0 }, "data": [ { "eventDate": "2026-10-20T14:03:14.000Z", "id": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "status": "LIQUIDATED", "endToEndId": "E3187249520261020184600abcdEFGH12345", "txId": null, "creditDebitType": "DEBIT", "transactionType": "PIX", "transactionAmount": { "currency": "BRL", "available": 25.5, "amount": 25.5 }, "fee": 0.5, "description": "Repasse pedido 1042", "counterparty": { "name": "Fulano de Tal" } } ] } } } } }, "security": [ { "OAuth2": [ "transactions.read" ] } ] } }, "/accounts/keys": { "get": { "tags": [ "Conta" ], "summary": "Listar chaves Pix da conta", "description": "As chaves Pix que o banco gerou para a sua conta. Quem paga uma chave escolhe o valor no aplicativo do banco dele. As chaves são criadas pelo painel do banco; por esta API só se lê.", "operationId": "keys", "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": [ { "key": "9d2c41a7-6f0e-4b53-8a21-3c5e7b9f0d14", "keyType": "EVP", "branch": null, "accountNumber": null, "accountType": null, "name": "Sua Empresa LTDA", "tradeName": null, "taxIdNumber": null, "creationDate": "2026-10-20T18:45:32.244Z", "keyOwnershipDate": "2026-10-20T18:45:32.244Z", "status": "ACTIVE" } ] } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/dict": { "post": { "tags": [ "Pix" ], "summary": "Iniciar pagamento Pix por chave Pix", "description": "Envia um Pix para uma chave (CPF, CNPJ, e-mail, telefone ou EVP, a chave aleatória). O valor é debitado na hora e o pagamento é aceito para processamento (202). O desfecho (LIQUIDATED ou CANCELED) vem na consulta pelo endToEndId ou pela chave de idempotência. Se for recusado, o valor volta para a conta.\n\nendToEndId pode vir nulo no 202: ele aparece assim que o Pix segue para o banco de destino. Consulte pela chave de idempotência ou pelo transactionId.\n\nid é um número estável; para consultar use endToEndId ou transactionId.", "operationId": "pixDict", "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "description": "Identificador único do pedido (1 a 50 letras e números). Repetir a mesma chave devolve o MESMO pagamento, sem pagar duas vezes.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pixKey": { "type": "string", "description": "A chave Pix de destino." }, "pixKeyType": { "type": "string", "description": "CPF | CNPJ | EMAIL | PHONE | EVP" }, "payment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Valor em reais, até 2 casas decimais." }, "currency": { "type": "string", "description": "BRL." } } }, "description": { "type": "string", "description": "Texto do Pix, até 140 caracteres." } }, "required": [ "pixKey", "pixKeyType" ] }, "example": { "pixKey": "fulano@exemplo.com", "pixKeyType": "EMAIL", "payment": { "currency": "BRL", "amount": 25.5 }, "description": "Repasse pedido 1042" } } } }, "responses": { "202": { "description": "Aceito", "content": { "application/json": { "example": { "endToEndId": null, "eventDate": "2026-10-20T14:03:11.000Z", "id": 218394857201, "payment": { "currency": "BRL", "amount": 25.5 }, "type": "PIX", "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "status": "PROCESSING", "fee": 0.5 } } } }, "400": { "description": "Regra de negócio ou campo inválido (saldo, limite, chave inválida…). Nada foi debitado.", "content": { "application/json": { "example": { "type": "onz-0008", "title": "Invalid request", "status": 400, "detail": "Saldo insuficiente", "instance": "/api/v2/pix/payments/dict", "statusCode": 400, "error": "insufficient_funds", "message": "Saldo insuficiente" } } } } }, "security": [ { "OAuth2": [ "pix.write" ] } ] } }, "/pix/payments/{endToEndId}": { "get": { "tags": [ "Pix" ], "summary": "Consultar Pix por end-to-end-id", "description": "O pagamento completo. Aceita o endToEndId do Pix ou o transactionId devolvido ao criar. 404 se não for um pagamento da sua conta.\n\nstatus: PROCESSING, LIQUIDATED, CANCELED, REFUNDED ou WAITING_APPROVAL.", "operationId": "pixE2e", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "O endToEndId do Pix (ou o transactionId).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": { "id": 218394857201, "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "endToEndId": "E3187249520261020184600abcdEFGH12345", "pixKey": "fulano@exemplo.com", "transactionType": "PIX", "status": "LIQUIDATED", "errorCode": null, "localInstrument": null, "creditDebitType": "DEBIT", "createdAt": "2026-10-20T14:03:11.000Z", "settledAt": "2026-10-20T14:03:14.000Z", "creditorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": "Fulano de Tal" }, "debtorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": null }, "remittanceInformation": "Repasse pedido 1042", "txId": null, "payment": { "currency": "BRL", "amount": 25.5 }, "fee": 0.5, "refunds": [] } } } } }, "404": { "description": "Pagamento não encontrado nesta conta", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Pagamento nao encontrado", "instance": "/api/v2/pix/payments/{endToEndId}", "statusCode": 404, "error": "not_found", "message": "Pagamento nao encontrado" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/idempotencyKey/{idempotencyKey}": { "get": { "tags": [ "Pix" ], "summary": "Consultar Pix por chave de idempotência", "description": "O mesmo pagamento, achado pela x-idempotency-key que você mandou. Use depois de um timeout para saber se o pedido chegou.", "operationId": "pixIdem", "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "description": "A chave de idempotência do pedido.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": { "id": 218394857201, "transactionId": "7c1d0f1e-5b0a-4a52-9a43-1d6f0b7f0c11", "idempotencyKey": "pedido1042", "endToEndId": "E3187249520261020184600abcdEFGH12345", "pixKey": "fulano@exemplo.com", "transactionType": "PIX", "status": "PROCESSING", "errorCode": null, "localInstrument": null, "creditDebitType": "DEBIT", "createdAt": "2026-10-20T14:03:11.000Z", "settledAt": null, "creditorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": "Fulano de Tal" }, "debtorAccount": { "ispb": null, "issuer": null, "number": null, "accountType": null, "document": null, "name": null }, "remittanceInformation": "Repasse pedido 1042", "txId": null, "payment": { "currency": "BRL", "amount": 25.5 }, "fee": 0.5, "refunds": [] } } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/payments/receipt/{endToEndId}": { "get": { "tags": [ "Pix" ], "summary": "Obter comprovante do Pix em PDF", "description": "O comprovante do pagamento, em PDF codificado em base64 (com a marca do banco). Aceita o endToEndId ou o transactionId.", "operationId": "pixReceipt", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "O endToEndId do Pix (ou o transactionId).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": { "pdf": "JVBERi0xLjQK…" } } } } }, "404": { "description": "Pagamento não encontrado nesta conta", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Pagamento nao encontrado", "instance": "/api/v2/pix/payments/receipt/{endToEndId}", "statusCode": 404, "error": "not_found", "message": "Pagamento nao encontrado" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix/keys/{key}": { "get": { "tags": [ "Pix" ], "summary": "Consultar dados de uma chave Pix", "description": "O que o DICT diz de uma chave Pix qualquer: nome, documento (mascarado pelo próprio DICT) e banco. Use para confirmar o destinatário antes de enviar. Se a provedora do banco não consulta o DICT, responde 501 not_supported.", "operationId": "pixKeyDict", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "A chave Pix (CPF, CNPJ, e-mail, telefone ou aleatória).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "name": "Fulano de Tal", "tradeName": null, "keyType": "EMAIL", "key": "fulano@exemplo.com", "document": "***.456.789-**", "ispb": "00000000", "ispb_reduced_name": "Banco Exemplo", "endToEndId": null } } } }, "404": { "description": "Chave não encontrada", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Chave Pix nao encontrada", "instance": "/api/v2/pix/keys/{key}", "statusCode": 404, "error": "not_found", "message": "Chave Pix nao encontrada" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/internal-transfers": { "post": { "tags": [ "Transferência entre contas" ], "summary": "Criar transferência entre contas", "description": "Transfere para outra conta deste mesmo banco, na hora e sem passar pelo Pix. A conta de destino é achada pelo documento (CPF ou CNPJ) do titular, e o nome informado precisa bater com o da conta: se qualquer conferência falhar, nada é transferido. Repetir a mesma x-idempotency-key devolve a mesma transferência.\n\nNão passa pelo Pix: a transferência já nasce liquidada (LIQUIDATED) e o endToEndId vem nulo.", "operationId": "itCreate", "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "description": "Identificador único do pedido (1 a 50 letras e números).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creditorAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF ou CNPJ do titular da conta de destino." }, "name": { "type": "string", "description": "Nome do titular. Precisa bater com o da conta." }, "number": { "type": "string", "description": "Opcional: o id da conta de destino, para conferir." } } }, "payment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Valor em reais, até 2 casas decimais." } } }, "remittanceInformation": { "type": "string", "description": "Descrição, até 200 caracteres." } } }, "example": { "creditorAccount": { "document": "12345678909", "name": "Fulano de Tal", "number": "", "accountType": "TRAN" }, "payment": { "currency": "BRL", "amount": 100 }, "remittanceInformation": "Acerto do pedido 1042" } } } }, "responses": { "202": { "description": "Aceita", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "endToEndId": null, "status": "LIQUIDATED", "transactionType": "INTERNAL", "createdAt": "2026-10-20T14:20:00.000Z", "eventDate": "2026-10-20T14:20:00.000Z", "idempotencyKey": "acerto1042", "payment": { "currency": "BRL", "amount": 100 }, "creditorAccount": { "document": null, "name": "Fulano de Tal", "issuer": null, "number": "8b1e…", "accountType": "TRAN", "ispb": null }, "debtorAccount": { "document": null, "name": "Sua Empresa LTDA", "issuer": null, "number": "c24f…", "accountType": "TRAN", "ispb": null }, "remittanceInformation": "Acerto do pedido 1042", "refunds": [], "fee": 0 } } } } }, "400": { "description": "Nome diferente do titular (recipient_name_mismatch), saldo, limite… Nada foi transferido.", "content": { "application/json": { "example": { "type": "onz-0008", "title": "Invalid request", "status": 400, "detail": "O nome informado não confere com o titular da conta de destino. Nada foi transferido.", "instance": "/api/v2/internal-transfers", "statusCode": 400, "error": "recipient_name_mismatch", "message": "O nome informado não confere com o titular da conta de destino. Nada foi transferido." } } } }, "404": { "description": "Não há conta neste banco com esse documento (recipient_not_found)", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Não há conta neste banco com esse documento", "instance": "/api/v2/internal-transfers", "statusCode": 404, "error": "recipient_not_found", "message": "Não há conta neste banco com esse documento" } } } } }, "security": [ { "OAuth2": [ "internal-transfer.write" ] } ] } }, "/internal-transfers/{endToEndId}": { "get": { "tags": [ "Transferência entre contas" ], "summary": "Consultar transferência entre contas", "description": "A transferência pelo endToEndId (quando existir) ou pelo transactionId devolvido ao criar.", "operationId": "itGet", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "O endToEndId ou o transactionId.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "status": "LIQUIDATED", "transactionType": "INTERNAL", "payment": { "currency": "BRL", "amount": 100 } } } } } } }, "security": [ { "OAuth2": [ "internal-transfer.read" ] } ] } }, "/internal-transfers/idempotencyKey/{idempotencyKey}": { "get": { "tags": [ "Transferência entre contas" ], "summary": "Consultar transferência por chave de idempotência", "description": "A mesma transferência, achada pela x-idempotency-key que você mandou.", "operationId": "itIdem", "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "description": "A chave de idempotência do pedido.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "data": { "id": 218394857401, "transactionId": "3d9a1c52-7e0b-4f1a-9c3d-6a2b8e4f5d10", "status": "LIQUIDATED", "transactionType": "INTERNAL", "payment": { "currency": "BRL", "amount": 100 } } } } } } }, "security": [ { "OAuth2": [ "internal-transfer.read" ] } ] } } }, "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "Troque clientId e clientSecret por um token em POST /oauth/token e mande Authorization: Bearer .", "flows": { "clientCredentials": { "tokenUrl": "https://bank.granseuk.com/api/v2/oauth/token", "scopes": { "account.read": "Permissão da chave: balance:read", "transactions.read": "Permissão da chave: transactions:read", "pix.read": "Permissão da chave: pix:read", "pix.write": "Permissão da chave: pix:send", "internal-transfer.write": "Permissão da chave: transfers:write", "internal-transfer.read": "Permissão da chave: transactions:read" } } } } } }, "security": [ { "OAuth2": [] } ] }