{ "openapi": "3.0.0", "paths": { "/api/v1/integration/context": { "get": { "operationId": "PublicApiController_context", "summary": "Consultar contexto da integração", "description": "A credencial determina o Space. x-space-id não seleciona nem amplia acesso.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiContextDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } }, "/api/v1/integration/wallets": { "get": { "operationId": "PublicApiController_wallets", "summary": "Listar carteiras ativas", "description": "Requer balances:read. Retorna referências financeiras mínimas, sem dados bancários privados.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiWalletsDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } }, "/api/v1/integration/balances": { "get": { "operationId": "PublicApiController_balances", "summary": "Consultar saldos correntes", "description": "Requer balances:read. Inclui saldo inicial, ajustes e liquidações; exclui pendentes, compras de cartão não pagas e carteiras arquivadas. Não é projeção nem saldo bancário em tempo real.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiBalancesDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } }, "/api/v1/integration/transactions": { "get": { "operationId": "PublicApiController_transactions", "summary": "Consultar lançamentos por período", "description": "Requer transactions:read. Ordem createdAt,id crescente. Até 100 itens; período obrigatório de até 366 dias. Inclui pendentes/cancelados, ajustes, transferências e pagamentos de fatura, com flags explícitas; exclui apagados. Não somar todos os lançamentos como receita/despesa: use os relatórios. Paginação não é snapshot; alterações/exclusões durante a travessia podem modificar resultados.", "parameters": [ { "name": "startDate", "required": true, "in": "query", "description": "Data financeira inicial inclusiva. Período máximo: 366 dias.", "schema": { "format": "date", "example": "2026-01-01", "type": "string" } }, { "name": "endDate", "required": true, "in": "query", "description": "Data financeira final inclusiva.", "schema": { "format": "date", "example": "2026-01-31", "type": "string" } }, { "name": "walletId", "required": false, "in": "query", "description": "Carteira do Space. Inclui transferências de entrada e saída dessa carteira.", "schema": { "format": "uuid", "type": "string" } }, { "name": "categoryId", "required": false, "in": "query", "description": "Categoria do Space ou categoria compartilhada do seu reseller.", "schema": { "format": "uuid", "type": "string" } }, { "name": "costCenterId", "required": false, "in": "query", "description": "Centro(s) de custo por UUID separado por vírgula ou UNCLASSIFIED. Em composições, deve corresponder à mesma parte da categoria e equipamento.", "schema": { "type": "string" } }, { "name": "assetId", "required": false, "in": "query", "description": "Equipamento do Space atribuído à mesma parte da categoria e centro.", "schema": { "format": "uuid", "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "INCOME", "EXPENSE", "TRANSFER" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "PENDING", "COMPLETED", "CANCELLED" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } }, { "name": "cursor", "required": false, "in": "query", "description": "nextCursor da página anterior, mantendo todos os filtros e limite. Validade: 24 horas. Não representa snapshot nem sincronização incremental.", "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiTransactionsDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } }, "/api/v1/integration/reports/summary": { "get": { "operationId": "PublicApiController_summary", "summary": "Consultar resumo financeiro realizado", "description": "Resumo do fluxo de caixa; requer reports:read e CASHFLOW_REPORT. Segue regras do relatório do produto, incluindo abertura, ajustes e transferências externas da carteira selecionada. Moeda suportada: BRL.", "parameters": [ { "name": "startDate", "required": true, "in": "query", "description": "Data financeira inicial inclusiva. Período máximo: 366 dias.", "schema": { "format": "date", "example": "2026-01-01", "type": "string" } }, { "name": "endDate", "required": true, "in": "query", "description": "Data financeira final inclusiva.", "schema": { "format": "date", "example": "2026-01-31", "type": "string" } }, { "name": "walletId", "required": false, "in": "query", "description": "Carteira do Space. Inclui transferências de entrada e saída dessa carteira.", "schema": { "format": "uuid", "type": "string" } }, { "name": "categoryId", "required": false, "in": "query", "description": "Categoria do Space ou categoria compartilhada do seu reseller.", "schema": { "format": "uuid", "type": "string" } }, { "name": "costCenterId", "required": false, "in": "query", "description": "Centro(s) de custo por UUID separado por vírgula ou UNCLASSIFIED. Em composições, deve corresponder à mesma parte da categoria e equipamento.", "schema": { "type": "string" } }, { "name": "assetId", "required": false, "in": "query", "description": "Equipamento do Space atribuído à mesma parte da categoria e centro.", "schema": { "format": "uuid", "type": "string" } }, { "name": "groupBy", "required": false, "in": "query", "schema": { "default": "month", "enum": [ "day", "week", "month" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiFinancialSummaryDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } }, "/api/v1/integration/reports/cashflow": { "get": { "operationId": "PublicApiController_cashflow", "summary": "Consultar fluxo de caixa realizado", "description": "Requer reports:read e CASHFLOW_REPORT. Período máximo 366 dias. Mesmo cálculo do relatório do produto, com valores decimais exatos. groupBy: day, week ou month. Não inclui projeções de pendentes.", "parameters": [ { "name": "startDate", "required": true, "in": "query", "description": "Data financeira inicial inclusiva. Período máximo: 366 dias.", "schema": { "format": "date", "example": "2026-01-01", "type": "string" } }, { "name": "endDate", "required": true, "in": "query", "description": "Data financeira final inclusiva.", "schema": { "format": "date", "example": "2026-01-31", "type": "string" } }, { "name": "walletId", "required": false, "in": "query", "description": "Carteira do Space. Inclui transferências de entrada e saída dessa carteira.", "schema": { "format": "uuid", "type": "string" } }, { "name": "categoryId", "required": false, "in": "query", "description": "Categoria do Space ou categoria compartilhada do seu reseller.", "schema": { "format": "uuid", "type": "string" } }, { "name": "costCenterId", "required": false, "in": "query", "description": "Centro(s) de custo por UUID separado por vírgula ou UNCLASSIFIED. Em composições, deve corresponder à mesma parte da categoria e equipamento.", "schema": { "type": "string" } }, { "name": "assetId", "required": false, "in": "query", "description": "Equipamento do Space atribuído à mesma parte da categoria e centro.", "schema": { "format": "uuid", "type": "string" } }, { "name": "groupBy", "required": false, "in": "query", "schema": { "default": "month", "enum": [ "day", "week", "month" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCashflowDto" } } } }, "400": { "description": "Parâmetros inválidos ou moeda não suportada", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "description": "Credencial inválida, expirada, revogada ou de outro ambiente", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "403": { "description": "Permissão ou acesso ao recurso indisponível", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "description": "Filtro ou recurso fora do Space", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "429": { "description": "Limite excedido; respeite Retry-After", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos até uma nova tentativa." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "RATE_LIMITED" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } }, "503": { "description": "Indisponibilidade temporária", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Identificador para suporte, sem incluir dados ou segredo." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } } } } } }, "tags": [ "Integrations" ], "security": [ { "integration-api-key": [] } ] } } }, "info": { "title": "RuralZap — API de integrações", "description": "Consultas financeiras por Space. Envie a chave em Authorization: Bearer. Ela determina o Space; não envie x-space-id. Valores monetários são strings decimais com quatro casas. Guia: /developers. Limites: 60 consultas/minuto por integração e 120 por Space; relatórios: 10 e 20/minuto. Trate HTTP 429 respeitando Retry-After. Todas as respostas financeiras usam Cache-Control: no-store.", "version": "1.0.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.finance.meyje.com.br" } ], "components": { "securitySchemes": { "integration-api-key": { "scheme": "bearer", "bearerFormat": "API key", "type": "http", "description": "Chave rzapi_test_… ou rzapi_live_… exibida uma vez nas configurações. Nunca use JWT da sessão, chave MCP ou uma chave na URL." } }, "schemas": { "PublicApiContextDto": { "type": "object", "properties": { "integrationId": { "type": "string", "format": "uuid" }, "spaceId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "balances:read", "transactions:read", "reports:read" ] } }, "capabilities": { "description": "Rotas disponíveis na interseção dos escopos e direitos atuais.", "type": "array", "items": { "type": "string" } } }, "required": [ "integrationId", "spaceId", "scopes", "capabilities" ] }, "PublicApiWalletDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Conta principal" }, "type": { "type": "string", "description": "Tipo de carteira do domínio.", "example": "CHECKING" }, "currency": { "type": "string", "example": "BRL", "description": "Moeda do recurso; valores de moedas distintas não são somados." }, "includeInNetWorth": { "type": "boolean", "description": "Indica inclusão da carteira no patrimônio do produto." } }, "required": [ "id", "name", "type", "currency", "includeInNetWorth" ] }, "PublicApiWalletsDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiWalletDto" } } }, "required": [ "data" ] }, "PublicApiWalletBalanceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Conta principal" }, "type": { "type": "string", "description": "Tipo de carteira do domínio.", "example": "CHECKING" }, "currency": { "type": "string", "example": "BRL", "description": "Moeda do recurso; valores de moedas distintas não são somados." }, "includeInNetWorth": { "type": "boolean", "description": "Indica inclusão da carteira no patrimônio do produto." }, "balance": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Saldo corrente persistido pelo domínio: inclui saldo inicial, ajustes e liquidações; exclui pendentes, canceladas e compras de cartão ainda não pagas." } }, "required": [ "id", "name", "type", "currency", "includeInNetWorth", "balance" ] }, "PublicApiCurrencyBalanceDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "BRL" }, "balance": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." } }, "required": [ "currency", "balance" ] }, "PublicApiBalancesDto": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "data": { "description": "Carteiras ativas; não inclui carteiras arquivadas nem limite disponível de cartão.", "type": "array", "items": { "$ref": "#/components/schemas/PublicApiWalletBalanceDto" } }, "totals": { "description": "Soma dos saldos das carteiras retornadas, por moeda, inclusive carteiras fora do patrimônio.", "type": "array", "items": { "$ref": "#/components/schemas/PublicApiCurrencyBalanceDto" } } }, "required": [ "generatedAt", "data", "totals" ] }, "PublicApiCompositionLineDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "number", "minimum": 0 }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$", "example": "90.0000", "description": "Valor exato da parte no principal contratado." }, "categoryId": { "type": "string", "format": "uuid", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "costCenterId": { "type": "string", "format": "uuid", "nullable": true }, "costCenterName": { "type": "string", "nullable": true }, "equipmentState": { "type": "string", "enum": [ "NONE", "PENDING", "LINKED" ] }, "assetId": { "type": "string", "format": "uuid", "nullable": true }, "assetCode": { "type": "string", "nullable": true }, "assetName": { "type": "string", "nullable": true } }, "required": [ "id", "position", "amount", "categoryId", "categoryName", "costCenterId", "costCenterName", "equipmentState", "assetId", "assetCode", "assetName" ] }, "PublicApiTransactionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true, "example": "#105", "description": "Referência humana; use id como identificador estável." }, "type": { "type": "string", "enum": [ "INCOME", "EXPENSE", "TRANSFER" ] }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED" ] }, "amount": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Principal original integral do lançamento, preservado mesmo em recortes analíticos." }, "reportAmount": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Principal considerado pelas partes que atendem simultaneamente aos filtros. Não representa caixa pago." }, "compositionVersion": { "type": "number", "minimum": 0, "description": "Zero identifica classificação legada; versão positiva usa exclusivamente compositionLines." }, "compositionLines": { "description": "Composição completa do lançamento para auditoria; não somente as partes filtradas.", "type": "array", "items": { "$ref": "#/components/schemas/PublicApiCompositionLineDto" } }, "currency": { "type": "string", "example": "BRL" }, "description": { "type": "string", "nullable": true }, "date": { "type": "string", "format": "date", "example": "2026-01-15" }, "competenceDate": { "type": "string", "format": "date", "nullable": true }, "walletId": { "type": "string", "format": "uuid", "nullable": true }, "categoryId": { "type": "string", "format": "uuid", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "cardId": { "type": "string", "format": "uuid", "nullable": true }, "transferSourceWalletId": { "type": "string", "format": "uuid", "nullable": true }, "transferDestinationWalletId": { "type": "string", "format": "uuid", "nullable": true }, "isAdjustment": { "type": "boolean" }, "isInvoicePayment": { "type": "boolean" }, "ignored": { "type": "boolean", "description": "Lançamento desconsiderado dos indicadores, ainda visível e podendo afetar saldo." }, "settlementManaged": { "type": "boolean", "description": "Indica liquidações parciais geridas pelo domínio." }, "settledPrincipal": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "settledCashAmount": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "remainingAmount": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "settlementStatus": { "type": "string", "enum": [ "PAID", "PARTIAL", "UNPAID" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Atualização técnica; não equivale a feed de mudanças." } }, "required": [ "id", "reference", "type", "status", "amount", "reportAmount", "compositionVersion", "compositionLines", "currency", "description", "date", "competenceDate", "walletId", "categoryId", "categoryName", "cardId", "transferSourceWalletId", "transferDestinationWalletId", "isAdjustment", "isInvoicePayment", "ignored", "settlementManaged", "settledPrincipal", "settledCashAmount", "remainingAmount", "settlementStatus", "createdAt", "updatedAt" ] }, "PublicApiPageMetaDto": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ] }, "PublicApiTransactionsDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiTransactionDto" } }, "meta": { "$ref": "#/components/schemas/PublicApiPageMetaDto" } }, "required": [ "data", "meta" ] }, "PublicApiReportMetaDto": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "timezone": { "type": "string", "example": "America/Sao_Paulo", "description": "Referência de negócio. Datas financeiras são date-only e não sofrem conversão de fuso." }, "walletId": { "type": "string", "format": "uuid", "nullable": true }, "categoryId": { "type": "string", "format": "uuid", "nullable": true }, "costCenterId": { "type": "string", "nullable": true }, "assetId": { "type": "string", "format": "uuid", "nullable": true }, "mode": { "type": "string", "enum": [ "cash", "slice" ], "description": "cash é a visão completa das carteiras; slice é recorte gerencial e não equivale ao saldo bancário integral." }, "groupBy": { "type": "string", "enum": [ "day", "week", "month" ] } }, "required": [ "generatedAt", "startDate", "endDate", "timezone", "walletId", "categoryId", "costCenterId", "assetId", "mode", "groupBy" ] }, "PublicApiCashflowSummaryDto": { "type": "object", "properties": { "openingBalance": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "totalInflows": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "totalOutflows": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "netCashflow": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "totalAdjustments": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "closingBalance": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." } }, "required": [ "openingBalance", "totalInflows", "totalOutflows", "netCashflow", "totalAdjustments", "closingBalance" ] }, "PublicApiFinancialSummaryDto": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PublicApiReportMetaDto" }, "currency": { "type": "string", "example": "BRL", "description": "Relatórios suportam BRL; uma combinação de moedas não é convertida nem somada." }, "summary": { "description": "Resumo do fluxo de caixa realizado. Requer o recurso CASHFLOW_REPORT.", "allOf": [ { "$ref": "#/components/schemas/PublicApiCashflowSummaryDto" } ] } }, "required": [ "meta", "currency", "summary" ] }, "PublicApiCashflowPeriodDto": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-01", "description": "Chave canônica do período; períodos sem movimentos podem estar ausentes." }, "inflows": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "outflows": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "netFlow": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "adjustments": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." }, "runningBalance": { "type": "string", "example": "1234.5678", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Valor decimal exato com quatro casas; não converter para float." } }, "required": [ "period", "inflows", "outflows", "netFlow", "adjustments", "runningBalance" ] }, "PublicApiCashflowDto": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PublicApiReportMetaDto" }, "currency": { "type": "string", "example": "BRL", "description": "Relatórios suportam BRL; uma combinação de moedas não é convertida nem somada." }, "summary": { "description": "Resumo do fluxo de caixa realizado. Requer o recurso CASHFLOW_REPORT.", "allOf": [ { "$ref": "#/components/schemas/PublicApiCashflowSummaryDto" } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiCashflowPeriodDto" } } }, "required": [ "meta", "currency", "summary", "data" ] } } } }