{ "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://SEU-BANCO/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": { "externalReference": { "type": "string", "description": "Referência do seu pedido, até 120 caracteres, devolvida no webhook. Se omitida ou vazia, usa o txid. Não altera a idempotência pelo txid." }, "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", "externalReference": "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": { "externalReference": { "type": "string", "description": "Referência do seu pedido, até 120 caracteres, devolvida no webhook. Se omitida ou vazia, usa o txid. Não altera a idempotência pelo txid." }, "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", "externalReference": "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" ] } ] }, "get": { "tags": [ "Cobranças Pix" ], "summary": "Consultar lista de cobranças imediatas", "description": "As cobranças criadas pela API em um período, da mais recente para a mais antiga, no mesmo formato da consulta por txid. O período é obrigatório e pode ter até 93 dias.\n\nA cobrança não pode ser alterada nem cancelada depois de criada (PATCH /cob/{txid} responde 501): ela vence sozinha em calendario.expiracao. Para cobrar de novo, crie outra com um novo txid.", "operationId": "cobList", "parameters": [ { "name": "inicio", "in": "query", "required": true, "description": "Início do período (ISO 8601, ex.: 2026-10-01T00:00:00Z).", "schema": { "type": "string", "format": "date-time" } }, { "name": "fim", "in": "query", "required": true, "description": "Fim do período (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "description": "ATIVA | CONCLUIDA | REMOVIDA_PELO_USUARIO_RECEBEDOR | REMOVIDA_PELO_PSP", "schema": { "type": "string" } }, { "name": "paginacao.paginaAtual", "in": "query", "required": false, "description": "Página, começando em 0. Padrão 0.", "schema": { "type": "integer" } }, { "name": "paginacao.itensPorPagina", "in": "query", "required": false, "description": "Itens por página, até 1000. Padrão 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "parametros": { "inicio": "2026-10-01T00:00:00.000Z", "fim": "2026-10-21T00:00:00.000Z", "paginacao": { "paginaAtual": 0, "itensPorPagina": 100, "quantidadeDePaginas": 1, "quantidadeTotalDeItens": 1 } }, "cobs": [ { "txid": "ABC123def456GHI789jkl012MNO345", "id": "0b6c2a0e-91a1-4e0e-8b73-8a0b6d3f1d22", "revisao": 0, "status": "CONCLUIDA", "calendario": { "criacao": "2026-10-20T14:05:00.000Z", "expiracao": 3600 }, "valor": { "original": "49.90", "modalidadeAlteracao": 0 }, "solicitacaoPagador": "Pedido 1042", "pixCopiaECola": "00020126…6304ABCD", "pix": [ { "endToEndId": "E3187249520261020184600abcdEFGH12345", "valor": "49.90", "horario": "2026-10-20T14:07:41.000Z" } ] } ] } } } }, "400": { "description": "Período inválido", "content": { "application/json": { "example": { "type": "onz-0002", "title": "Invalid params", "status": 400, "detail": "Informe inicio e fim (data e hora ISO 8601, ex.: 2026-10-01T00:00:00Z), com fim depois de inicio", "instance": "/api/v2/cob", "statusCode": 400, "error": "invalid_request", "message": "Informe inicio e fim (data e hora ISO 8601, ex.: 2026-10-01T00:00:00Z), com fim depois de inicio" } } } } }, "security": [ { "OAuth2": [ "cob.read" ] } ] } }, "/pix/{endToEndId}": { "get": { "tags": [ "Cobranças Pix" ], "summary": "Consultar Pix recebido", "description": "Um Pix que entrou na conta, pelo endToEndId: o valor, o horário, o txid (quando pagou uma cobrança sua) e as devoluções (a lista fica vazia enquanto o Pix não foi devolvido).", "operationId": "pixRecebido", "parameters": [ { "name": "endToEndId", "in": "path", "required": true, "description": "O endToEndId do Pix recebido.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "endToEndId": "E3187249520261020184600abcdEFGH12345", "txid": "ABC123def456GHI789jkl012MNO345", "valor": "49.90", "chave": null, "horario": "2026-10-20T14:07:41.000Z", "infoPagador": "Pedido 1042", "devolucoes": [] } } } }, "404": { "description": "Pix não encontrado", "content": { "application/json": { "example": { "type": "onz-0009", "title": "Pix not found", "status": 404, "detail": "Pix nao encontrado", "instance": "/api/v2/pix/{endToEndId}", "statusCode": 404, "error": "not_found", "message": "Pix nao encontrado" } } } } }, "security": [ { "OAuth2": [ "pix.read" ] } ] } }, "/pix": { "get": { "tags": [ "Cobranças Pix" ], "summary": "Consultar Pix recebidos", "description": "Os Pix recebidos em um período (de cobranças e pagos direto na chave), do mais recente para o mais antigo. O período é obrigatório e pode ter até 93 dias.", "operationId": "pixRecebidos", "parameters": [ { "name": "inicio", "in": "query", "required": true, "description": "Início do período (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "fim", "in": "query", "required": true, "description": "Fim do período (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "txid", "in": "query", "required": false, "description": "Só os Pix que pagaram esta cobrança.", "schema": { "type": "string" } }, { "name": "txIdPresente", "in": "query", "required": false, "description": "true: só os que pagaram uma cobrança; false: só os pagos direto na chave.", "schema": { "type": "boolean" } }, { "name": "paginacao.paginaAtual", "in": "query", "required": false, "description": "Página, começando em 0. Padrão 0.", "schema": { "type": "integer" } }, { "name": "paginacao.itensPorPagina", "in": "query", "required": false, "description": "Itens por página, até 1000. Padrão 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "parametros": { "inicio": "2026-10-01T00:00:00.000Z", "fim": "2026-10-21T00:00:00.000Z", "paginacao": { "paginaAtual": 0, "itensPorPagina": 100, "quantidadeDePaginas": 1, "quantidadeTotalDeItens": 1 } }, "pix": [ { "endToEndId": "E3187249520261020184600abcdEFGH12345", "txid": "ABC123def456GHI789jkl012MNO345", "valor": "49.90", "chave": null, "horario": "2026-10-20T14:07:41.000Z", "infoPagador": "Pedido 1042", "devolucoes": [] } ] } } } } }, "security": [ { "OAuth2": [ "pix.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://SEU-BANCO/api/v2/oauth/token", "scopes": { "cob.write": "Permissão da chave: pix:write", "cob.read": "Permissão da chave: pix:read", "pix.read": "Permissão da chave: pix:read" } } } } } }, "security": [ { "OAuth2": [] } ] }