{ "openapi": "3.0.3", "info": { "title": "API QRCode", "version": "2.0.0", "description": "Visão Geral da API QRCode\n\nCrie cobranças Pix com QR Code dinâmico (txid), mostre o pixCopiaECola ao pagador, confirme o pagamento e receba o dinheiro na conta." }, "servers": [ { "url": "https://bank.granseuk.com/api/v2" } ], "tags": [ { "name": "Autenticação" }, { "name": "Cobranças Pix" } ], "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": [] } }, "/cob/{txid}": { "put": { "tags": [ "Cobranças Pix" ], "summary": "Criar cobrança imediata com txid", "description": "Cria uma cobrança Pix (QR dinâmico) com o txid que você escolhe: 26 a 35 letras e números. Repetir o PUT com o mesmo txid devolve a mesma cobrança. Cada banco define um valor mínimo por cobrança (abaixo dele: 400 below_limit, com o mínimo na mensagem).", "operationId": "cobPut", "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "26 a 35 letras e números.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "object", "properties": { "original": { "type": "string", "description": "Valor em reais, texto com ponto (\"49.90\")." } } }, "calendario": { "type": "object", "properties": { "expiracao": { "type": "integer", "description": "Validade em segundos, de 60 a 2592000. Padrão 86400." } } }, "solicitacaoPagador": { "type": "string", "description": "Texto mostrado ao pagador, até 140 caracteres." } } }, "example": { "calendario": { "expiracao": 3600 }, "devedor": { "cpf": "12345678909", "nome": "Fulano de Tal" }, "valor": { "original": "49.90" }, "solicitacaoPagador": "Pedido 1042" } } } }, "responses": { "201": { "description": "Criada", "content": { "application/json": { "example": { "txid": "ABC123def456GHI789jkl012MNO345", "id": "0b6c2a0e-91a1-4e0e-8b73-8a0b6d3f1d22", "revisao": 0, "status": "ATIVA", "calendario": { "criacao": "2026-10-20T14:05:00.000Z", "expiracao": 3600 }, "devedor": { "nome": "Fulano de Tal", "cpf": "12345678909" }, "valor": { "original": "49.90", "modalidadeAlteracao": 0 }, "chave": null, "loc": null, "location": null, "solicitacaoPagador": "Pedido 1042", "infoAdicionais": [], "pixCopiaECola": "00020126…6304ABCD" } } } } }, "security": [ { "OAuth2": [ "cob.write" ] } ] }, "get": { "tags": [ "Cobranças Pix" ], "summary": "Consultar cobrança imediata", "description": "O estado da cobrança. Quando paga, status é CONCLUIDA e a lista pix traz o endToEndId. Ao receber, confirme sempre por esta consulta; não confie só em um aviso externo.\n\nstatus: ATIVA (aguardando), CONCLUIDA (paga), REMOVIDA_PELO_USUARIO_RECEBEDOR (cancelada), REMOVIDA_PELO_PSP (expirada).", "operationId": "cobGet", "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "O txid da cobrança.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "txid": "ABC123def456GHI789jkl012MNO345", "status": "CONCLUIDA", "valor": { "original": "49.90" }, "pix": [ { "endToEndId": "E3187249520261020184600abcdEFGH12345", "valor": "49.90", "horario": "2026-10-20T14:07:41.000Z" } ] } } } }, "404": { "description": "Cobrança não encontrada", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Cobranca nao encontrada", "instance": "/api/v2/cob/{txid}", "statusCode": 404, "error": "not_found", "message": "Cobranca nao encontrada" } } } } }, "security": [ { "OAuth2": [ "cob.read" ] } ] } }, "/cob": { "post": { "tags": [ "Cobranças Pix" ], "summary": "Criar cobrança imediata (txid gerado)", "description": "Igual ao PUT, mas o banco gera o txid e devolve na resposta.", "operationId": "cobPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "object", "properties": { "original": { "type": "string", "description": "Valor em reais, texto com ponto (\"49.90\")." } } }, "calendario": { "type": "object", "properties": { "expiracao": { "type": "integer", "description": "Validade em segundos, de 60 a 2592000. Padrão 86400." } } } } }, "example": { "calendario": { "expiracao": 3600 }, "valor": { "original": "49.90" }, "solicitacaoPagador": "Pedido 1042" } } } }, "responses": { "201": { "description": "Criada", "content": { "application/json": { "example": { "txid": "5f2c9d8e7a6b4c3d2e1f0a9b8c7d6e5f", "id": "0b6c2a0e-91a1-4e0e-8b73-8a0b6d3f1d22", "revisao": 0, "status": "ATIVA", "calendario": { "criacao": "2026-10-20T14:05:00.000Z", "expiracao": 3600 }, "devedor": { "nome": "Fulano de Tal", "cpf": "12345678909" }, "valor": { "original": "49.90", "modalidadeAlteracao": 0 }, "chave": null, "loc": null, "location": null, "solicitacaoPagador": "Pedido 1042", "infoAdicionais": [], "pixCopiaECola": "00020126…6304ABCD" } } } } }, "security": [ { "OAuth2": [ "cob.write" ] } ] } } }, "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": { "cob.write": "Permissão da chave: pix:write", "cob.read": "Permissão da chave: pix:read" } } } } } }, "security": [ { "OAuth2": [] } ] }