{ "openapi": "3.1.0", "info": { "title": "Valloria-Nexus Core API - Externa", "version": "1.0.0" }, "paths": { "/v1/auth/token": { "post": { "tags": [ "external" ], "summary": "Issue Nexus Access Token", "description": "Emite um access token JWT da Nexus para integracoes machine-to-machine. O cliente envia apenas credenciais da aplicacao (`client_id` e `client_secret`) e nao escolhe scopes livremente: os scopes emitidos sao sempre os provisionados server-side para aquele client_id. Nao ha refresh token; ao expirar, o cliente deve solicitar um novo access token repetindo o fluxo `client_credentials`. A rota aceita `Authorization: Basic base64(client_id:client_secret)` ou body com `client_id`/`client_secret`.", "operationId": "issue_nexus_access_token_v1_auth_token_post", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string", "description": "Campo ignorado pela Nexus. Os scopes emitidos sao sempre os provisionados para o client_id." } }, "type": "object", "required": [ "grant_type" ] }, "example": { "grant_type": "client_credentials", "client_id": "client-tenant-a", "client_secret": "secret-tenant-a" } }, "application/json": { "schema": { "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string", "description": "Campo ignorado pela Nexus. Os scopes emitidos sao sempre os provisionados para o client_id." } }, "type": "object", "required": [ "grant_type", "client_id", "client_secret" ] }, "example": { "grant_type": "client_credentials", "client_id": "client-tenant-a", "client_secret": "secret-tenant-a" } } }, "required": true }, "responses": { "200": { "description": "Access token emitido pela Nexus.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "unsupported_grant_type", "message": "only client_credentials is supported", "trace_id": "f6fb2e8e-0e2c-42d8-a7af-2d6362911b02" } } } }, "401": { "description": "Invalid client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "invalid_client", "message": "client credentials are invalid", "trace_id": "5a1c1de2-4166-4c49-b07e-89f3d06a6989" } } } }, "403": { "description": "Client disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "client_disabled", "message": "client is disabled", "trace_id": "8986d478-7f49-406f-9860-b0e094f4fdbf" } } } }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" }, "413": { "$ref": "#/components/responses/PayloadTooLarge413" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType415" } }, "security": [], "x-required-scopes": [] } }, "/v1/banks/{bank_code}/preflight": { "get": { "tags": [ "external" ], "summary": "Bank Preflight", "operationId": "bank_preflight_v1_banks__bank_code__preflight_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "path", "required": true, "schema": { "type": "string", "title": "Bank Code" } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "default": "sandbox", "title": "Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Bank Preflight V1 Banks Bank Code Preflight Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." } }, "/v1/statements/schedules": { "get": { "tags": [ "external" ], "summary": "List Statement Schedules", "operationId": "list_statement_schedules_v1_statements_schedules_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "security": [ { "HTTPBearer": [] } ], "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." }, "post": { "tags": [ "external" ], "summary": "Create Statement Schedule", "description": "Cria um agendamento de extrato/saldo. Use `account_id` como identificador preferencial. Quando esse `account_id` ja estiver previamente conhecido para o tenant, o backend pode resolver `bank_code` internamente; caso contrario, informe `bank_code` na primeira criacao para registrar o alvo bancario. Quando webhook_secret estiver configurado, o envio inclui assinatura HMAC em X-Webhook-Signature. webhook_url passa por validacao anti-SSRF.\n\nRequired scopes: statements.write.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "create_statement_schedule_v1_statements_schedules_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Schedule criado", "headers": { "Location": { "description": "URI do recurso criado", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleMutationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" }, "413": { "$ref": "#/components/responses/PayloadTooLarge413" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType415" } }, "security": [ { "HTTPBearer": [] } ], "x-required-scopes": [ "statements.write" ] } }, "/v1/statements/schedules/{schedule_id}": { "get": { "tags": [ "external" ], "summary": "Get Statement Schedule", "operationId": "get_statement_schedule_v1_statements_schedules__schedule_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." }, "put": { "tags": [ "external" ], "summary": "Update Statement Schedule", "description": "Atualiza um agendamento existente. A atualizacao preserva a regra de identificacao explicita da conta alvo. Quando `account_id` ja estiver conhecido para o tenant, `bank_code` pode ser resolvido internamente; caso contrario, informe `bank_code` na requisicao. Quando webhook_secret estiver configurado, o envio inclui assinatura HMAC em X-Webhook-Signature. webhook_url passa por validacao anti-SSRF.\n\nRequired scopes: statements.write.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "update_statement_schedule_v1_statements_schedules__schedule_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleMutationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" }, "413": { "$ref": "#/components/responses/PayloadTooLarge413" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType415" } }, "x-required-scopes": [ "statements.write" ] } }, "/v1/statements/schedules/{schedule_id}/next": { "get": { "tags": [ "external" ], "summary": "Get Statement Schedule Next", "operationId": "get_statement_schedule_next_v1_statements_schedules__schedule_id__next_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Statement Schedule Next V1 Statements Schedules Schedule Id Next Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." } }, "/v1/statements/schedules/{schedule_id}/toggle": { "post": { "tags": [ "external" ], "summary": "Toggle Statement Schedule", "description": "Desabilita ou confirma o estado atual de um agendamento. Quando enabled=false, o schedule entra em disabled_pending_purge por 4 horas, permanece consultavel e nao volta a ser elegivel para execucao. Schedules nessa janela nao podem ser reativados; crie um novo schedule apos expurgo.\n\nRequired scopes: statements.write.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "toggle_statement_schedule_v1_statements_schedules__schedule_id__toggle_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleToggleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementScheduleMutationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" }, "413": { "$ref": "#/components/responses/PayloadTooLarge413" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType415" } }, "x-required-scopes": [ "statements.write" ] } }, "/v1/statements/schedules/run": { "post": { "tags": [ "external" ], "summary": "Run Statement Schedules", "description": "Dispara manualmente uma execucao operacional dos schedules ativos do tenant autenticado. Esta rota nao consulta contas ad hoc e nao substitui query/balances; ela apenas aciona os schedules cadastrados do proprio tenant. Schedules desativados ou pendentes de expurgo sao ignorados. A execucao e sincrona curta e retorna um resumo operacional.\n\nRequired scopes: statements.run.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "run_statement_schedules_v1_statements_schedules_run_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementManualRunResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "security": [ { "HTTPBearer": [] } ], "x-required-scopes": [ "statements.run" ] } }, "/v1/statements/runs": { "get": { "tags": [ "external" ], "summary": "List Statement Runs", "operationId": "list_statement_runs_v1_statements_runs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filtro por codigo do banco.", "title": "Bank Code" }, "description": "Filtro por codigo do banco." }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date From", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date To", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "branch_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agencia/branch da conta, quando aplicavel.", "title": "Branch Code" }, "description": "Agencia/branch da conta, quando aplicavel." }, { "name": "account_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numero da conta, quando aplicavel.", "title": "Account Number" }, "description": "Numero da conta, quando aplicavel." }, { "name": "investment_account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Investment Account" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Statement Runs V1 Statements Runs Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." } }, "/v1/statements/runs/{run_id}": { "get": { "tags": [ "external" ], "summary": "Get Statement Run", "operationId": "get_statement_run_v1_statements_runs__run_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Statement Run V1 Statements Runs Run Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." } }, "/v1/statements/runs/{run_id}/download": { "get": { "tags": [ "external" ], "summary": "Download Statement Run", "operationId": "download_statement_run_v1_statements_runs__run_id__download_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "minLength": 36, "maxLength": 36 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ], "description": "Required scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant." } }, "/v1/statements/query": { "get": { "tags": [ "external" ], "summary": "Query Statements", "description": "Consulta extratos consolidados por banco/conta sobre dados ja persistidos. Use `account_id` como identificador canonico sempre que existir; quando ele for suficiente para identificar a conta dentro do tenant, `bank_code` pode ser omitido. Quando nao houver `account_id`, envie a combinacao minima suportada pelo dominio, como `branch_code+account_number`, junto com `bank_code`. A rota nao chama provider nem banco em tempo real; ela retorna apenas o que ja foi coletado pelos schedules do tenant. A consulta exige sempre um alvo explicito de conta.\n\nRequired scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "query_statements_v1_statements_query_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filtro por codigo do banco.", "title": "Bank Code" }, "description": "Filtro por codigo do banco." }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "default": "sandbox", "title": "Environment" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date From", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date To", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "branch_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agencia/branch da conta, quando aplicavel.", "title": "Branch Code" }, "description": "Agencia/branch da conta, quando aplicavel." }, { "name": "account_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numero da conta, quando aplicavel.", "title": "Account Number" }, "description": "Numero da conta, quando aplicavel." }, { "name": "investment_account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Investment Account" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Query Statements V1 Statements Query Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ] } }, "/v1/statements/balances": { "get": { "tags": [ "external" ], "summary": "Query Statement Balances", "description": "Consulta saldos consolidados por banco/conta sobre dados ja persistidos. Use `account_id` como identificador canonico sempre que existir; quando ele for suficiente para identificar a conta dentro do tenant, `bank_code` pode ser omitido. Quando nao houver `account_id`, envie a combinacao minima suportada pelo dominio, como `branch_code+account_number`, junto com `bank_code`. A rota nao chama provider nem banco em tempo real; ela retorna apenas o que ja foi coletado pelos schedules do tenant. A consulta exige sempre um alvo explicito de conta.\n\nRequired scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "query_statement_balances_v1_statements_balances_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filtro por codigo do banco.", "title": "Bank Code" }, "description": "Filtro por codigo do banco." }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "default": "sandbox", "title": "Environment" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date From", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date To", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "branch_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agencia/branch da conta, quando aplicavel.", "title": "Branch Code" }, "description": "Agencia/branch da conta, quando aplicavel." }, { "name": "account_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numero da conta, quando aplicavel.", "title": "Account Number" }, "description": "Numero da conta, quando aplicavel." }, { "name": "investment_account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Investment Account" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Query Statement Balances V1 Statements Balances Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ] } }, "/v1/statements/availability": { "get": { "tags": [ "external" ], "summary": "Statement Availability", "description": "Consulta a disponibilidade de retornos ja persistidos para um range de datas. A rota nao chama provider nem banco; ela apenas informa quais datas do periodo solicitado ja possuem runs concluidos e payload pronto para consumo em `query`, `balances` ou `overview`.\n\nRequired scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "statement_availability_v1_statements_availability_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filtro por codigo do banco.", "title": "Bank Code" }, "description": "Filtro por codigo do banco." }, { "name": "date_from", "in": "query", "required": true, "schema": { "type": "string", "description": "Data inicial obrigatoria no formato YYYY-MM-DD.", "title": "Date From", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Data inicial obrigatoria no formato YYYY-MM-DD." }, { "name": "date_to", "in": "query", "required": true, "schema": { "type": "string", "description": "Data final obrigatoria no formato YYYY-MM-DD.", "title": "Date To", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Data final obrigatoria no formato YYYY-MM-DD." }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "branch_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agencia/branch da conta, quando aplicavel.", "title": "Branch Code" }, "description": "Agencia/branch da conta, quando aplicavel." }, { "name": "account_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numero da conta, quando aplicavel.", "title": "Account Number" }, "description": "Numero da conta, quando aplicavel." }, { "name": "investment_account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Investment Account" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementAvailabilityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ] } }, "/v1/statements/overview": { "get": { "tags": [ "external" ], "summary": "Statement Overview", "description": "Consulta consolidada de saldo + extrato em uma unica chamada. A rota existe por conveniencia e reducao de round-trips, enquanto `query` e `balances` permanecem disponiveis para consumidores que precisem de granularidade. Quando `account_id` for canonico e suficiente no tenant, `bank_code` pode ser omitido para leitura de dados ja persistidos. A rota nao chama provider nem banco em tempo real; ela consolida apenas saldo + extrato que ja foram persistidos pelo pipeline de schedules.\n\nRequired scopes: statements.read.\n\nAuthentication: Bearer JWT required. Tenant isolation is derived from the token claims; client-supplied tenant_id is ignored. Common auth failures: 401 for missing/invalid token or tenant claim, 403 for insufficient scope or blocked tenant.", "operationId": "statement_overview_v1_statements_overview_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "bank_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Codigo do banco alvo.", "title": "Bank Code" }, "description": "Codigo do banco alvo." }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "default": "sandbox", "title": "Environment" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date From", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ], "title": "Date To", "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "branch_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agencia/branch da conta, quando aplicavel.", "title": "Branch Code" }, "description": "Agencia/branch da conta, quando aplicavel." }, { "name": "account_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numero da conta, quando aplicavel.", "title": "Account Number" }, "description": "Numero da conta, quando aplicavel." }, { "name": "investment_account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Investment Account" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementOverviewResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized401" }, "403": { "$ref": "#/components/responses/Forbidden403" }, "404": { "$ref": "#/components/responses/NotFound404" }, "429": { "$ref": "#/components/responses/RateLimited429" }, "500": { "$ref": "#/components/responses/InternalError500" } }, "x-required-scopes": [ "statements.read" ] } } }, "components": { "schemas": { "AuthTokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "Bearer" }, "expires_in": { "type": "integer", "title": "Expires In" }, "scope": { "type": "string", "title": "Scope", "default": "" } }, "type": "object", "required": [ "access_token", "expires_in" ], "title": "AuthTokenResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "RevolutCallbackResponse": { "properties": { "bank_code": { "type": "string", "title": "Bank Code" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "environment": { "type": "string", "title": "Environment" }, "consent_id": { "type": "string", "title": "Consent Id" }, "consent_status": { "type": "string", "title": "Consent Status" }, "authorized_account_ids": { "items": { "type": "string" }, "type": "array", "title": "Authorized Account Ids" } }, "type": "object", "required": [ "bank_code", "tenant_id", "environment", "consent_id", "consent_status", "authorized_account_ids" ], "title": "RevolutCallbackResponse" }, "RevolutConsentRequest": { "properties": { "environment": { "type": "string", "title": "Environment", "default": "sandbox" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "permissions": { "items": { "type": "string" }, "type": "array", "title": "Permissions" }, "expiration_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiration Datetime" }, "transaction_from_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction From Datetime" }, "transaction_to_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction To Datetime" } }, "type": "object", "title": "RevolutConsentRequest" }, "RevolutConsentResponse": { "properties": { "bank_code": { "type": "string", "title": "Bank Code" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "environment": { "type": "string", "title": "Environment" }, "consent_id": { "type": "string", "title": "Consent Id" }, "state": { "type": "string", "title": "State" }, "authorization_url": { "type": "string", "title": "Authorization Url" }, "interaction_id": { "type": "string", "title": "Interaction Id" }, "permissions": { "items": { "type": "string" }, "type": "array", "title": "Permissions" }, "expected_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Account Id" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "bank_code", "tenant_id", "environment", "consent_id", "state", "authorization_url", "interaction_id", "permissions" ], "title": "RevolutConsentResponse" }, "StatementAvailabilityDateResponse": { "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date", "title": "Date" }, "available_routes": { "items": { "type": "string" }, "type": "array", "title": "Available Routes" }, "statement_events_count": { "type": "integer", "title": "Statement Events Count", "default": 0 }, "balance_items_count": { "type": "integer", "title": "Balance Items Count", "default": 0 }, "latest_run": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Latest Run" } }, "type": "object", "required": [ "date", "available_routes" ], "title": "StatementAvailabilityDateResponse" }, "StatementAvailabilityResponse": { "properties": { "bank_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Code" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "requested_range": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Requested Range" }, "available_dates": { "items": { "$ref": "#/components/schemas/StatementAvailabilityDateResponse" }, "type": "array", "title": "Available Dates" } }, "type": "object", "required": [ "requested_range" ], "title": "StatementAvailabilityResponse" }, "StatementManualRunResponse": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id" }, "triggered_at": { "type": "string", "title": "Triggered At" }, "request_id": { "type": "string", "title": "Request Id" }, "eligible_schedules": { "type": "integer", "title": "Eligible Schedules" }, "dispatched_runs": { "type": "integer", "title": "Dispatched Runs" }, "ignored_schedules": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Ignored Schedules" }, "runs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Runs" } }, "type": "object", "required": [ "tenant_id", "triggered_at", "request_id", "eligible_schedules", "dispatched_runs" ], "title": "StatementManualRunResponse" }, "StatementOverviewResponse": { "properties": { "bank_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Code" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "account": { "additionalProperties": true, "type": "object", "title": "Account" }, "balances": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Balances" }, "statements": { "additionalProperties": true, "type": "object", "title": "Statements" }, "run_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Run Context" }, "raw_available": { "type": "boolean", "title": "Raw Available" } }, "type": "object", "required": [ "account", "statements", "raw_available" ], "title": "StatementOverviewResponse" }, "StatementScheduleListResponse": { "properties": { "schedules": { "items": { "$ref": "#/components/schemas/StatementScheduleResponse" }, "type": "array", "title": "Schedules" } }, "type": "object", "required": [ "schedules" ], "title": "StatementScheduleListResponse" }, "StatementScheduleMutationResponse": { "properties": { "schedule_id": { "type": "string", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Schedule Id" }, "enabled": { "type": "boolean", "title": "Enabled" }, "status": { "type": "string", "title": "Status", "default": "active" }, "purge_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purge After" } }, "type": "object", "required": [ "schedule_id", "enabled" ], "title": "StatementScheduleMutationResponse" }, "StatementScheduleRequest": { "properties": { "bank_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Code", "description": "Codigo do banco alvo. Pode ser omitido quando `account_id` ja estiver previamente registrado para o tenant e o backend conseguir resolver o provider com seguranca. Para primeiro cadastro ou quando houver ambiguidade, informe `bank_code`." }, "environment": { "type": "string", "title": "Environment", "default": "sandbox" }, "bank_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Id" }, "branch_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch Code" }, "account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Number" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id", "description": "Identificador canonico da conta, quando suportado. Se nao houver account_id, enviar a combinacao minima exigida pelo dominio/provider, como branch_code+account_number." }, "account_type": { "type": "string", "title": "Account Type", "default": "current_account" }, "run_times": { "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "type": "array", "title": "Run Times" }, "timezone": { "type": "string", "title": "Timezone", "default": "America/Sao_Paulo" }, "retention_days": { "type": "integer", "title": "Retention Days", "default": 90 }, "webhook_enabled": { "type": "boolean", "title": "Webhook Enabled", "default": false }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "URL do webhook. O backend valida anti-SSRF: bloqueio de localhost/IP privado." }, "webhook_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Token", "description": "Token opcional enviado no Authorization do webhook." }, "webhook_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Secret", "description": "Segredo opcional para assinatura HMAC SHA-256 (header X-Webhook-Signature)." }, "enabled": { "type": "boolean", "title": "Enabled", "default": true } }, "type": "object", "required": [ "run_times" ], "title": "StatementScheduleRequest", "description": "Payload de criacao/atualizacao de agendamento.", "examples": [ { "account_id": "acc-1", "bank_code": "ITAU", "enabled": true, "environment": "sandbox", "retention_days": 30, "run_times": [ "10:00", "18:00" ], "timezone": "America/Sao_Paulo", "webhook_enabled": false } ] }, "StatementScheduleResponse": { "properties": { "schedule_id": { "type": "string", "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Schedule Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "bank_code": { "type": "string", "title": "Bank Code" }, "environment": { "type": "string", "title": "Environment" }, "account_type": { "type": "string", "title": "Account Type" }, "run_times": { "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "type": "array", "title": "Run Times" }, "timezone": { "type": "string", "title": "Timezone" }, "retention_days": { "type": "integer", "title": "Retention Days" }, "page_size": { "type": "integer", "title": "Page Size" }, "bank_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bank Id" }, "branch_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch Code" }, "account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Number" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "balance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance Id" }, "statement_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Type" }, "filter_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filter By" }, "webhook_enabled": { "type": "boolean", "title": "Webhook Enabled", "default": false }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url" }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "status": { "type": "string", "title": "Status", "default": "active" }, "disabled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disabled At" }, "purge_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purge After" }, "last_run_keys": { "items": { "type": "string" }, "type": "array", "title": "Last Run Keys" }, "created_at": { "type": "string", "title": "Created At", "default": "" }, "updated_at": { "type": "string", "title": "Updated At", "default": "" } }, "type": "object", "required": [ "schedule_id", "tenant_id", "bank_code", "environment", "account_type", "run_times", "timezone", "retention_days", "page_size" ], "title": "StatementScheduleResponse" }, "StatementScheduleToggleRequest": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" } }, "type": "object", "required": [ "enabled" ], "title": "StatementScheduleToggleRequest", "description": "Payload para habilitar/desabilitar um agendamento existente." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "trace_id": { "type": "string" } } } }, "securitySchemes": { "HTTPBearer": { "type": "http", "description": "Bearer JWT obrigatorio. Requisitos minimos: claim exp obrigatoria, claim de tenant obrigatoria (ex.: tenant_id) e escopos exigidos por operacao.", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Unauthorized401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "unauthorized", "message": "Missing bearer token", "trace_id": "0d6bc6f7-9e28-4eb3-8e31-b6f5ccfb5c82" } } } }, "Forbidden403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "forbidden", "message": "Insufficient scope", "trace_id": "2ddb42f3-5715-4cc9-a87b-aebd0d73fcf5" } } } }, "NotFound404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Seconds until next allowed request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PayloadTooLarge413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedMediaType415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "servers": [ { "url": "{baseUrl}", "description": "Base URL da API Valloria Nexus", "variables": { "baseUrl": { "default": "http://localhost:8000", "description": "Endereco base do deployment (gateway/ingress)." } } } ], "x-valloria-audience": "externa" }