{ "openapi": "3.1.0", "info": { "title": "RenkoPay Gateway, API Externa", "version": "1.0.0", "description": "API externa para emissão de PIX, boleto, consulta de transações e regras de split. Autentique com client_id e client_secret em /api/v1/auth/token e use Authorization: Bearer nos endpoints protegidos." }, "servers": [ { "url": "https://gateway.seudominio.com.br", "description": "Produção" }, { "url": "http://127.0.0.1:8000", "description": "Desenvolvimento local" } ], "tags": [ { "name": "Autenticação" }, { "name": "PIX" }, { "name": "Boleto" }, { "name": "Transações" }, { "name": "Split PIX" }, { "name": "Webhooks" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pgw token" } }, "schemas": { "AuthTokenRequest": { "type": "object", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "client_secret": { "type": "string", "minLength": 20 } } }, "AuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in": { "type": "number", "example": 1800 } } }, "Customer": { "type": "object", "required": [ "name", "document" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "document": { "type": "string", "maxLength": 20 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "PixChargeRequest": { "type": "object", "required": [ "amount", "customer" ], "properties": { "external_id": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 0.01 }, "description": { "type": "string" }, "expires_in": { "type": "integer", "minimum": 60, "maximum": 86400 }, "split_rule_id": { "type": "string", "format": "uuid" }, "customer": { "$ref": "#/components/schemas/Customer" }, "metadata": { "type": "object", "additionalProperties": true } } }, "BoletoChargeRequest": { "type": "object", "required": [ "amount", "due_date", "customer" ], "properties": { "external_id": { "type": "string" }, "amount": { "type": "number", "minimum": 0.01 }, "due_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "customer": { "$ref": "#/components/schemas/Customer" }, "metadata": { "type": "object", "additionalProperties": true } } }, "PixSplitDestination": { "type": "object", "required": [ "label", "destination_type", "percentage" ], "properties": { "label": { "type": "string" }, "destination_type": { "type": "string", "enum": [ "PIX_KEY", "BANK_ACCOUNT", "DTVM_ACCOUNT" ] }, "percentage": { "type": "number", "minimum": 0.0001, "maximum": 100 }, "pix_key_type": { "type": "string" }, "pix_key": { "type": "string" }, "dtvm_account_id": { "type": "string" }, "ispb": { "type": "string" }, "bank_code": { "type": "string" }, "branch": { "type": "string" }, "account_number": { "type": "string" }, "account_digit": { "type": "string" }, "account_type": { "type": "string" }, "document": { "type": "string" }, "name": { "type": "string" } } }, "PixSplitRuleRequest": { "type": "object", "required": [ "name", "apply_mode", "destinations" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "apply_mode": { "type": "string", "enum": [ "MANUAL", "ALL_PIX" ] }, "priority": { "type": "integer", "default": 100 }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/PixSplitDestination" } } } }, "PaymentTransaction": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "method": { "type": "string", "enum": [ "PIX", "BOLETO" ] }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "example": "BRL" }, "customer": { "$ref": "#/components/schemas/Customer" }, "pix": { "type": "object" }, "boleto": { "type": "object" }, "split": { "type": "object" }, "provider": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object" } } } } }, "paths": { "/api/health": { "get": { "tags": [ "Autenticação" ], "summary": "Health check", "responses": { "200": { "description": "API online" } } } }, "/api/v1/auth/token": { "post": { "tags": [ "Autenticação" ], "summary": "Gerar bearer token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenRequest" } } } }, "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "401": { "description": "Credenciais inválidas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/charges": { "post": { "tags": [ "PIX" ], "summary": "Emitir cobrança PIX", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixChargeRequest" } } } }, "responses": { "201": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "401": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Endpoint DTVM não configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha no provedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/charges/{id}": { "get": { "tags": [ "PIX" ], "summary": "Consultar cobrança PIX", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/boletos": { "post": { "tags": [ "Boleto" ], "summary": "Emitir boleto", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoChargeRequest" } } } }, "responses": { "201": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/boletos/{id}": { "get": { "tags": [ "Boleto" ], "summary": "Consultar boleto", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions": { "get": { "tags": [ "Transações" ], "summary": "Listar transações", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "PIX", "BOLETO" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Lista paginada" } } } }, "/api/v1/transactions/{id}": { "get": { "tags": [ "Transações" ], "summary": "Detalhar transação", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/split-rules": { "get": { "tags": [ "Split PIX" ], "summary": "Listar regras de split", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista paginada" } } }, "post": { "tags": [ "Split PIX" ], "summary": "Criar regra de split", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixSplitRuleRequest" } } } }, "responses": { "201": { "description": "Regra criada" }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/split-rules/{id}": { "delete": { "tags": [ "Split PIX" ], "summary": "Excluir regra de split", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Regra excluída" }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/dtvm/pix/{id}": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook DTVM para PIX", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recebido" } } } }, "/api/v1/webhooks/dtvm/boleto/{id}": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook DTVM para boleto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recebido" } } } } } }