{"openapi": "3.1.0", "info": {"title": "API do Dinzo", "version": "1.0.0", "description": "API pública do Dinzo. Guia e chaves de API: https://dinzo.com.br/developers"}, "servers": [{"url": "https://api.dinzo.com.br"}], "paths": {"/v1/me": {"get": {"summary": "Obter perfil do usuário", "tags": ["me"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Me"}, "example": {"id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Helena Duarte", "wage": 8500, "monthly_living_cost": 4200, "has_spouse": true, "has_children": false, "is_entrepreneur": false, "plan": {"premium_access": true, "ultra_access": false, "frequency": "MONTHLY"}, "scopes": ["read", "write"], "limits": {"rate": {"minute": {"limit": 120, "window_sec": 60}, "day": {"limit": 5000, "window_sec": 86400}}}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_me", "description": "Retorna o perfil financeiro do usuário autenticado junto com o plano vigente (acesso Premium/Ultra e periodicidade), os escopos do token e os limites de rate limit da API. Objeto único, sem envelope."}, "patch": {"summary": "Atualizar perfil do usuário", "tags": ["me"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MeProfile"}, "example": {"id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Helena Duarte", "wage": 9000, "monthly_living_cost": 4200, "has_spouse": true, "has_children": true, "is_entrepreneur": false}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"nullable": true, "anyOf": [{"maxLength": 200, "type": "string"}, {"type": "null"}]}, "wage": {"nullable": true, "anyOf": [{"type": "number"}, {"type": "null"}]}, "monthly_living_cost": {"nullable": true, "anyOf": [{"type": "number"}, {"type": "null"}]}, "has_spouse": {"nullable": true, "anyOf": [{"type": "boolean"}, {"type": "null"}]}, "has_children": {"nullable": true, "anyOf": [{"type": "boolean"}, {"type": "null"}]}, "is_entrepreneur": {"nullable": true, "anyOf": [{"type": "boolean"}, {"type": "null"}]}}}}}}, "operationId": "patch_v1_me", "description": "Atualiza campos do perfil financeiro do usuário (name, wage, `monthly_living_cost`, `has_spouse`, `has_children`, `is_entrepreneur`). Todos os campos do corpo são opcionais e anuláveis; só os enviados são alterados. Retorna o perfil atualizado (sem os blocos plan, scopes e limits). Requer escopo write."}}, "/v1/accounts": {"get": {"summary": "Listar contas", "tags": ["accounts"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Account"}}}}, "example": {"data": [{"id": "17f5dcd0-83cb-4779-b760-3912947401e8", "type": "BANK", "sub_type": "CHECKING_ACCOUNT", "title": "Nubank", "archived": false, "exclude_from_totals": false, "currency": "BRL", "balance": 4820.57, "credit": null, "pay_bill_from_account_id": null, "icon_id": "d5920881-eaa2-489f-b683-3947880fc3a0", "card_icon_id": null, "open_finance": {"connected": true, "connector_name": "Nubank"}, "card_holders": null, "created_at": "2026-01-14T13:22:41.000Z"}, {"id": "459af7c0-c917-4a18-9b3f-c6b4739b7a08", "type": "CREDIT", "sub_type": "CREDIT_CARD", "title": "Itaú Uniclass", "archived": false, "exclude_from_totals": false, "currency": "BRL", "balance": -1167.29, "credit": {"close_day": 3, "due_day": 10, "due_day_of_month": 10, "cycle_auto": true, "limit": 12000}, "pay_bill_from_account_id": "17f5dcd0-83cb-4779-b760-3912947401e8", "icon_id": "6d9c748a-c2cd-441f-a9ab-813d54ba72b8", "card_icon_id": "2b337b22-2924-4a2c-abb1-1342497ebe00", "open_finance": {"connected": true, "connector_name": "Itaú"}, "card_holders": {"3706": "me", "8747": "Stefanie"}, "created_at": "2026-02-02T09:05:11.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_accounts", "description": "Lista todas as contas e cartões de crédito do usuário autenticado, cada um com o saldo calculado (contas arquivadas retornam saldo nulo). Retorna um objeto com a lista em `data`, ordenada por data de criação."}, "post": {"summary": "Criar conta", "tags": ["accounts"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccountCreated"}, "example": {"id": "d049d327-1ec0-4bb3-ad16-6b34f21f2d7d", "type": "BANK", "sub_type": "SAVINGS_ACCOUNT", "title": "Reserva de emergência", "archived": false, "exclude_from_totals": false, "currency": "BRL", "balance": 5000, "credit": null, "pay_bill_from_account_id": null, "icon_id": "de8e90de-2194-4274-bd7c-2e79a7d95914", "card_icon_id": null, "open_finance": {"connected": false, "connector_name": null}, "card_holders": null, "created_at": "2026-08-24T18:41:03.000Z", "initial_balance_transaction_id": "4dd7c72f-8198-41b4-9be3-2e3595d5849b"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"anyOf": [{"const": "BANK", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "sub_type": {"anyOf": [{"const": "SAVINGS_ACCOUNT", "type": "string"}, {"const": "CHECKING_ACCOUNT", "type": "string"}, {"const": "CREDIT_CARD", "type": "string"}]}, "title": {"maxLength": 200, "type": "string"}, "icon_id": {"type": "string"}, "icon_name": {"type": "string"}, "card_icon_id": {"type": "string"}, "currency_code": {"maxLength": 3, "type": "string"}, "initial_balance": {"type": "number"}, "credit_limit": {"type": "number"}, "credit_close_day": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_due_day": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_due_day_of_month": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_cycle_auto": {"type": "boolean"}, "pay_bill_from_account_id": {"type": "string"}, "exclude_from_totals": {"type": "boolean"}}, "required": ["type"]}}}}, "operationId": "post_v1_accounts", "description": "Cria uma conta manual (banco ou cartão de crédito). O ícone pode ser informado por `icon_id` ou resolvido por `icon_name`. Retorna a conta criada com o saldo já calculado e o id da transação de saldo inicial, quando um saldo inicial foi informado."}}, "/v1/accounts/{id}": {"get": {"summary": "Buscar conta", "tags": ["accounts"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Account"}, "example": {"id": "459af7c0-c917-4a18-9b3f-c6b4739b7a08", "type": "CREDIT", "sub_type": "CREDIT_CARD", "title": "Itaú Uniclass", "archived": false, "exclude_from_totals": false, "currency": "BRL", "balance": -1167.29, "credit": {"close_day": 3, "due_day": 10, "due_day_of_month": 10, "cycle_auto": true, "limit": 12000}, "pay_bill_from_account_id": "17f5dcd0-83cb-4779-b760-3912947401e8", "icon_id": "6d9c748a-c2cd-441f-a9ab-813d54ba72b8", "card_icon_id": "2b337b22-2924-4a2c-abb1-1342497ebe00", "open_finance": {"connected": true, "connector_name": "Itaú"}, "card_holders": {"3706": "me", "8747": "Stefanie"}, "created_at": "2026-02-02T09:05:11.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "get_v1_accounts_id", "description": "Retorna uma conta específica do usuário pelo id, com o saldo calculado. Responde 404 quando a conta não existe ou não pertence ao usuário."}, "patch": {"summary": "Atualizar conta", "tags": ["accounts"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Account"}, "example": {"id": "459af7c0-c917-4a18-9b3f-c6b4739b7a08", "type": "CREDIT", "sub_type": "CREDIT_CARD", "title": "Itaú Uniclass Black", "archived": false, "exclude_from_totals": false, "currency": "BRL", "balance": -1167.29, "credit": {"close_day": 5, "due_day": 12, "due_day_of_month": 12, "cycle_auto": true, "limit": 18000}, "pay_bill_from_account_id": "17f5dcd0-83cb-4779-b760-3912947401e8", "icon_id": "6d9c748a-c2cd-441f-a9ab-813d54ba72b8", "card_icon_id": "2b337b22-2924-4a2c-abb1-1342497ebe00", "open_finance": {"connected": true, "connector_name": "Itaú"}, "card_holders": {"3706": "me", "8747": "Stefanie"}, "created_at": "2026-02-02T09:05:11.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"anyOf": [{"const": "BANK", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "sub_type": {"anyOf": [{"const": "SAVINGS_ACCOUNT", "type": "string"}, {"const": "CHECKING_ACCOUNT", "type": "string"}, {"const": "CREDIT_CARD", "type": "string"}]}, "title": {"maxLength": 200, "type": "string"}, "icon_id": {"type": "string"}, "icon_name": {"type": "string"}, "card_icon_id": {"type": "string"}, "currency_code": {"maxLength": 3, "type": "string"}, "credit_limit": {"nullable": true, "anyOf": [{"type": "number"}, {"type": "null"}]}, "credit_close_day": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_due_day": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_due_day_of_month": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "credit_cycle_auto": {"type": "boolean"}, "pay_bill_from_account_id": {"nullable": true, "anyOf": [{"type": "string"}, {"type": "null"}]}, "exclude_from_totals": {"type": "boolean"}, "archived": {"type": "boolean"}}}}}}, "operationId": "patch_v1_accounts_id", "description": "Atualiza os campos editáveis de uma conta (título, ícone, moeda, limite e datas de cartão, conta pagadora da fatura, arquivamento, exclusão de totais etc.) e retorna a conta atualizada com o saldo recalculado. Responde 404 quando a conta não existe."}, "delete": {"summary": "Excluir conta", "tags": ["accounts"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Exclui uma conta do usuário e as transações associadas. Não retorna corpo (204 No Content). Responde 404 quando a conta "}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_accounts_id", "description": "Exclui uma conta do usuário e as transações associadas. Não retorna corpo (204 No Content). Responde 404 quando a conta não existe."}}, "/v1/categories": {"get": {"summary": "Listar categorias", "tags": ["categories"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Category"}}}}, "example": {"data": [{"id": "3f2a9c10-8b4e-4d21-9a77-1c0e5b6f2a44", "title": "Alimentação", "parent_id": null, "icon_id": "a1b2c3d4-0000-1111-2222-333344445555", "color_hex": "#FF5722", "system": true, "archived": false, "created_at": "2026-01-15T13:42:07.000Z"}, {"id": "7c1d4e88-2f9a-4b6c-8e10-5a2b7c9d0e13", "title": "Restaurantes", "parent_id": "3f2a9c10-8b4e-4d21-9a77-1c0e5b6f2a44", "icon_id": null, "color_hex": null, "system": false, "archived": false, "created_at": "2026-03-02T09:18:55.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_categories", "description": "Retorna todas as categorias visíveis ao usuário (próprias e públicas do sistema) como uma árvore plana ligada por `parent_id`, ordenadas por título. O campo archived reflete se a categoria está arquivada para o usuário."}, "post": {"summary": "Criar categoria", "tags": ["categories"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Category"}, "example": {"id": "9b3f0a21-5d6e-4c77-a1b2-8e9f0c1d2e34", "title": "Academia", "parent_id": null, "icon_id": "b2c3d4e5-1111-2222-3333-444455556666", "color_hex": "#22C55E", "system": false, "archived": false, "created_at": "2026-08-24T12:05:33.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 100, "type": "string"}, "parent_id": {"type": "string"}, "icon_id": {"type": "string"}, "icon_name": {"type": "string"}, "color_hex": {"maxLength": 7, "type": "string"}}, "required": ["title"]}}}}, "operationId": "post_v1_categories", "description": "Cria uma categoria do usuário e retorna a categoria criada. Aceita `parent_id` para aninhar sob outra categoria e ícone por `icon_id` ou `icon_name`."}}, "/v1/categories/{id}": {"patch": {"summary": "Atualizar categoria", "tags": ["categories"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Category"}, "example": {"id": "9b3f0a21-5d6e-4c77-a1b2-8e9f0c1d2e34", "title": "Academia e Saúde", "parent_id": null, "icon_id": "b2c3d4e5-1111-2222-3333-444455556666", "color_hex": "#16A34A", "system": false, "archived": true, "created_at": "2026-08-24T12:05:33.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 100, "type": "string"}, "parent_id": {"nullable": true, "anyOf": [{"type": "string"}, {"type": "null"}]}, "icon_id": {"type": "string"}, "icon_name": {"type": "string"}, "color_hex": {"nullable": true, "anyOf": [{"maxLength": 7, "type": "string"}, {"type": "null"}]}, "archived": {"type": "boolean"}}}}}}, "operationId": "patch_v1_categories_id", "description": "Atualiza título, categoria pai, ícone ou cor, e/ou arquiva/desarquiva a categoria (campo archived). Retorna a categoria atualizada; responde 404 se o id não for visível ao usuário."}, "delete": {"summary": "Excluir categoria", "tags": ["categories"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Exclui a categoria. Categorias públicas do sistema são apenas arquivadas para o usuário; categorias próprias são removid"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_categories_id", "description": "Exclui a categoria. Categorias públicas do sistema são apenas arquivadas para o usuário; categorias próprias são removidas em cascata. Não retorna corpo (204); responde 404 se a categoria não for encontrada."}}, "/v1/tags": {"get": {"summary": "Listar tags", "tags": ["tags"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Tag"}}}}, "example": {"data": [{"id": "1a2b3c4d-5e6f-7081-9a0b-c1d2e3f40506", "title": "Reembolsável", "color_hex": "#3B82F6", "created_at": "2026-04-10T18:20:44.000Z"}, {"id": "2b3c4d5e-6f70-8192-a0b1-d2e3f4051607", "title": "Viagem", "color_hex": "#F59E0B", "created_at": "2026-05-21T07:59:12.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_tags", "description": "Retorna todas as tags do usuário ordenadas por título."}, "post": {"summary": "Criar tag", "tags": ["tags"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Tag"}, "example": {"id": "3c4d5e6f-7081-92a3-b0c1-e2f405160718", "title": "Trabalho", "color_hex": "#8B5CF6", "created_at": "2026-08-24T12:07:01.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 100, "type": "string"}, "color_hex": {"maxLength": 7, "type": "string"}}, "required": ["title", "color_hex"]}}}}, "operationId": "post_v1_tags", "description": "Cria uma tag do usuário com título e cor, e retorna a tag criada."}}, "/v1/tags/{id}": {"patch": {"summary": "Atualizar tag", "tags": ["tags"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Tag"}, "example": {"id": "3c4d5e6f-7081-92a3-b0c1-e2f405160718", "title": "Trabalho remoto", "color_hex": "#7C3AED", "created_at": "2026-08-24T12:07:01.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 100, "type": "string"}, "color_hex": {"maxLength": 7, "type": "string"}}}}}}, "operationId": "patch_v1_tags_id", "description": "Atualiza o título e/ou a cor da tag e retorna a tag atualizada. Responde 404 se a tag não for encontrada."}, "delete": {"summary": "Excluir tag", "tags": ["tags"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Exclui a tag do usuário. Não retorna corpo (204); responde 404 se a tag não for encontrada."}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_tags_id", "description": "Exclui a tag do usuário. Não retorna corpo (204); responde 404 se a tag não for encontrada."}}, "/v1/targets": {"get": {"summary": "Listar metas", "tags": ["targets"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Target"}}}}, "example": {"data": [{"id": "a0b1c2d3-e4f5-4607-8819-0a1b2c3d4e5f", "type": "INCOMING", "title": "Reserva de emergência", "amount": 10000, "current_amount": 3500.5, "track_category": false, "category_id": null, "account_id": "c2d3e4f5-0607-4819-a0b1-2c3d4e5f6071", "start_date": "2026-01-01", "end_date": "2026-12-31", "created_at": "2026-01-01T10:00:00.000Z"}, {"id": "b1c2d3e4-f506-4718-9920-1b2c3d4e5f60", "type": "OUTGOING", "title": "Limite de lazer", "amount": 800, "current_amount": 642.9, "track_category": true, "category_id": "3f2a9c10-8b4e-4d21-9a77-1c0e5b6f2a44", "account_id": null, "start_date": "2026-08-01", "end_date": null, "created_at": "2026-08-01T08:30:00.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "type", "in": "query", "required": false, "schema": {"anyOf": [{"const": "INCOMING", "type": "string"}, {"const": "OUTGOING", "type": "string"}]}}], "operationId": "get_v1_targets", "description": "Retorna as metas financeiras do usuário com o progresso ao vivo (`current_amount`), ordenadas por data de criação. Aceita o filtro opcional de query type (`INCOMING` ou `OUTGOING`)."}, "post": {"summary": "Criar meta", "tags": ["targets"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Target"}, "example": {"id": "c2d3e4f5-0607-4819-a0b1-2c3d4e5f6071", "type": "INCOMING", "title": "Viagem para o Japão", "amount": 15000, "current_amount": 0, "track_category": false, "category_id": null, "account_id": null, "start_date": "2026-08-24", "end_date": null, "created_at": "2026-08-24T12:10:18.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 200, "type": "string"}, "type": {"anyOf": [{"const": "INCOMING", "type": "string"}, {"const": "OUTGOING", "type": "string"}]}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "category_id": {"type": "string"}, "track_category": {"type": "boolean"}, "account_id": {"type": "string"}}, "required": ["title", "type", "amount"]}}}}, "operationId": "post_v1_targets", "description": "Cria uma meta financeira (`INCOMING` ou `OUTGOING`) e retorna a meta criada com o progresso calculado. Aceita `category_id`, `track_category` e `account_id` opcionais."}}, "/v1/targets/{id}": {"patch": {"summary": "Atualizar meta", "tags": ["targets"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Target"}, "example": {"id": "c2d3e4f5-0607-4819-a0b1-2c3d4e5f6071", "type": "INCOMING", "title": "Viagem para o Japão", "amount": 15000, "current_amount": 2000, "track_category": false, "category_id": null, "account_id": null, "start_date": "2026-08-24", "end_date": null, "created_at": "2026-08-24T12:10:18.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"minLength": 1, "maxLength": 200, "type": "string"}, "type": {"anyOf": [{"const": "INCOMING", "type": "string"}, {"const": "OUTGOING", "type": "string"}]}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "category_id": {"type": "string"}, "track_category": {"type": "boolean"}, "account_id": {"nullable": true, "anyOf": [{"type": "string"}, {"type": "null"}]}, "add_amount": {"exclusiveMinimum": 0, "type": "number"}, "remove_amount": {"exclusiveMinimum": 0, "type": "number"}}}}}}, "operationId": "patch_v1_targets_id", "description": "Atualiza os dados da meta (título, tipo, valor, categoria, conta) e/ou movimenta o progresso com `add_amount` ou `remove_amount`. Retorna a meta atualizada; responde 404 se a meta não for encontrada."}, "delete": {"summary": "Excluir meta", "tags": ["targets"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Exclui a meta financeira do usuário. Não retorna corpo (204); responde 404 se a meta não for encontrada."}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_targets_id", "description": "Exclui a meta financeira do usuário. Não retorna corpo (204); responde 404 se a meta não for encontrada."}}, "/v1/subscriptions": {"get": {"summary": "Listar assinaturas", "tags": ["subscriptions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Subscription"}}}, "required": ["data"]}, "example": {"data": [{"id": "9f3c2b18-6a4e-4d2f-9c1a-7e5b0d8f2a11", "merchant_name": "Netflix", "amount": 55.9, "currency": "BRL", "cadence": "MONTHLY", "charge_day": 15, "status": "CONFIRMED", "source": "AUTO", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "card_last_digits": "4821", "occurrences": 7, "first_seen_at": "2026-01-15T03:00:00.000Z", "last_seen_at": "2026-07-15T03:00:00.000Z", "created_at": "2026-01-16T09:12:44.501Z"}, {"id": "c71a0d55-9b2e-4f81-a3c6-0e8d2b5f9174", "merchant_name": "Spotify", "amount": 21.9, "currency": "BRL", "cadence": "MONTHLY", "charge_day": 3, "status": "DETECTED", "source": "AUTO", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "card_last_digits": "4821", "occurrences": 4, "first_seen_at": "2026-04-03T03:00:00.000Z", "last_seen_at": "2026-07-03T03:00:00.000Z", "created_at": "2026-04-04T06:30:10.220Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_subscriptions", "description": "Retorna todas as assinaturas do usuário (detectadas automaticamente e manuais), ordenadas por nome do estabelecimento. Assinaturas removidas não são incluídas."}, "post": {"summary": "Criar assinatura", "tags": ["subscriptions"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Subscription"}, "example": {"id": "a2d4f6b8-1c3e-4a5b-9d7f-2e0c8b6a4f11", "merchant_name": "Academia Smart Fit", "amount": 119.9, "currency": "BRL", "cadence": "MONTHLY", "charge_day": 10, "status": "CONFIRMED", "source": "MANUAL", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "card_last_digits": null, "occurrences": 0, "first_seen_at": "2026-08-24T12:00:00.000Z", "last_seen_at": "2026-08-24T12:00:00.000Z", "created_at": "2026-08-24T12:00:00.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"merchant_name": {"minLength": 1, "maxLength": 200, "type": "string"}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "charge_day": {"minimum": 1, "maximum": 31, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 31, "type": "integer"}]}, "account_id": {"type": "string"}}, "required": ["merchant_name", "amount", "charge_day"]}}}}, "operationId": "post_v1_subscriptions", "description": "Cria uma assinatura manual (cadência `MONTHLY`, status `CONFIRMED`, origem `MANUAL`). Requer o escopo de escrita. Retorna 201 com a assinatura criada; retorna 400 (`validation_error`) se `account_id` não for uma conta do usuário."}}, "/v1/subscriptions/{id}": {"patch": {"summary": "Alterar status da assinatura", "tags": ["subscriptions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Subscription"}, "example": {"id": "c71a0d55-9b2e-4f81-a3c6-0e8d2b5f9174", "merchant_name": "Spotify", "amount": 21.9, "currency": "BRL", "cadence": "MONTHLY", "charge_day": 3, "status": "CONFIRMED", "source": "AUTO", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "card_last_digits": "4821", "occurrences": 4, "first_seen_at": "2026-04-03T03:00:00.000Z", "last_seen_at": "2026-07-03T03:00:00.000Z", "created_at": "2026-04-04T06:30:10.220Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"anyOf": [{"const": "CONFIRMED", "type": "string"}, {"const": "CANCELLED", "type": "string"}, {"const": "REJECTED", "type": "string"}]}}, "required": ["status"]}}}}, "operationId": "patch_v1_subscriptions_id", "description": "Aplica uma transição de status na assinatura: `CONFIRMED` (confirmar/reativar), `CANCELLED` (cancelar) ou `REJECTED` (tirar da lista, terminal). `DETECTED` é exclusivo do detector e não pode ser definido. Retorna a assinatura atualizada; 404 (`not_found`) se não existir; 409 (`status_locked`) se a transição não for permitida a partir do status atual."}}, "/v1/icons": {"get": {"summary": "Listar ícones", "tags": ["icons"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Icon"}}}, "required": ["data"]}, "example": {"data": [{"id": "7e1ac4a8-d0b7-4e6a-ae3d-7c2f81c273d2", "title": "Alimentação", "icon_name": "utensils", "image_url": "https://cdn.dinzo.com.br/icons/alimentacao.png", "type": "CATEGORY"}, {"id": "7bc68c89-3d9c-4941-bc3f-ae8b399c9168", "title": "Conta Corrente", "icon_name": null, "image_url": "https://cdn.dinzo.com.br/icons/conta-corrente.png", "type": "ACCOUNT"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "type", "in": "query", "required": false, "schema": {"anyOf": [{"const": "ACCOUNT", "type": "string"}, {"const": "CATEGORY", "type": "string"}, {"const": "CARD", "type": "string"}]}}], "operationId": "get_v1_icons", "description": "Retorna o catálogo de ícones do Dinzo, ordenado por título, opcionalmente filtrado pela query `type` (`ACCOUNT`, `CATEGORY` ou `CARD`). Resposta cacheável por cliente por 1 dia. Envelopado em `{data:[...]}`."}}, "/v1/notifications": {"get": {"summary": "Listar notificações", "tags": ["notifications"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Notification"}}, "next_cursor": {"type": ["string", "null"], "description": "Cursor para a próxima página; null quando não há mais itens."}, "has_more": {"type": "boolean", "description": "true quando existem mais notificações além desta página."}}, "required": ["data", "next_cursor", "has_more"]}, "example": {"data": [{"id": "00d12aa7-aa3d-44ef-aa1e-f3cc4d47db7d", "type": "fatura", "title": "Fatura fechada", "message": "Sua fatura do Nubank fechou em R$ 1.245,90.", "unread": true, "app_link": "dinzo://faturas/nubank", "web_link": "https://app.dinzo.com.br/faturas/nubank", "created_at": "2026-08-23T14:02:11.000Z"}, {"id": "aed7e545-75f1-4761-9c08-7c865ab9f5a3", "type": null, "title": "Sincronização concluída", "message": "Suas contas foram atualizadas com sucesso.", "unread": false, "app_link": null, "web_link": null, "created_at": "2026-08-22T09:30:00.000Z"}], "next_cursor": "eyJjIjoxNzU2MDAwMTAwMDAwLCJpZCI6Im50Zl80YjhlMGQzMSJ9", "has_more": true}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "unread", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "cursor", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "schema": {"minimum": 1, "maximum": 100, "anyOf": [{"format": "numeric", "default": 0, "type": "string"}, {"minimum": 1, "maximum": 100, "type": "number"}]}}], "operationId": "get_v1_notifications", "description": "Retorna as notificações do usuário em ordem decrescente de criação, com paginação por cursor. Aceita os filtros de query `unread` (true/false), `cursor` (cursor de paginação) e `limit` (1 a 100, padrão 50). Responde com a lista e os campos de paginação `has_more` e `next_cursor`."}}, "/v1/notifications/read-all": {"post": {"summary": "Marcar todas como lidas", "tags": ["notifications"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Marca como lidas todas as notificações não lidas do usuário. Não retorna corpo (204 No Content)."}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "post_v1_notifications_read_all", "description": "Marca como lidas todas as notificações não lidas do usuário. Não retorna corpo (204 No Content)."}}, "/v1/notifications/{id}/read": {"post": {"summary": "Marcar notificação como lida", "tags": ["notifications"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Marca uma notificação específica como lida. Retorna 404 quando a notificação não existe (ou já foi removida). Não retorn"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "post_v1_notifications_id_read", "description": "Marca uma notificação específica como lida. Retorna 404 quando a notificação não existe (ou já foi removida). Não retorna corpo (204 No Content)."}}, "/v1/notifications/{id}": {"delete": {"summary": "Remover notificação", "tags": ["notifications"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Remove (soft delete) uma notificação do usuário. Retorna 404 quando a notificação não existe ou já foi removida. Não ret"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_notifications_id", "description": "Remove (soft delete) uma notificação do usuário. Retorna 404 quando a notificação não existe ou já foi removida. Não retorna corpo (204 No Content)."}}, "/v1/investments": {"get": {"summary": "Listar investimentos", "tags": ["investments"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Investment"}}}, "required": ["data"]}, "example": {"data": [{"id": "ad902523-ece3-4c28-9937-b732c4f74e5c", "asset_key": "FIXED_INCOME:BRSTNCLF1R25", "name": "Tesouro Selic 2029", "type": "FIXED_INCOME", "sub_type": "TREASURY", "balance": 18452.37, "quantity": 1.23, "value": 15002.11, "code": null, "isin": "BRSTNCLF1R25", "issuer": "Tesouro Nacional", "currency": "BRL", "due_date": "2029-03-01", "purchase_date": "2024-06-12", "rate": 100, "rate_type": "SELIC", "fixed_annual_rate": null, "last_twelve_months_rate": 10.75, "indexer_additional_info": "SELIC", "tax_exempt": false, "status": "ACTIVE", "updated_at": "2026-08-23T06:12:44.000Z"}, {"id": "99cca56c-2d44-4e90-8dea-2373554f13e8", "asset_key": "EQUITY:BRITSAACNPR8", "name": "ITSA4", "type": "EQUITY", "sub_type": "STOCK", "balance": 4210.5, "quantity": 420, "value": 10.03, "code": "ITSA4", "isin": "BRITSAACNPR8", "issuer": "Itaúsa", "currency": "BRL", "due_date": null, "purchase_date": null, "rate": null, "rate_type": null, "fixed_annual_rate": null, "last_twelve_months_rate": null, "indexer_additional_info": null, "tax_exempt": null, "status": "ACTIVE", "updated_at": "2026-08-23T06:12:44.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_investments", "description": "Retorna todas as posições de investimento Open Finance do usuário (contas com item Pluggy ativo), ordenadas por saldo decrescente. Envelope `{data:[...]}` sem paginação."}}, "/v1/investments/summary": {"get": {"summary": "Resumo de investimentos", "tags": ["investments"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"has_investments": {"type": "boolean"}, "total_invested": {"type": "number"}, "count": {"type": "integer"}, "holdings": {"type": "array", "items": {"$ref": "#/components/schemas/InvestmentSummaryHolding"}}, "by_type": {"type": "array", "items": {"$ref": "#/components/schemas/InvestmentByTypeEntry"}}, "as_of": {"type": ["string", "null"], "description": "Timestamp ISO 8601 da posição mais recente que alimentou o resumo (última sincronização); null se não houver posições."}}, "required": ["has_investments", "total_invested", "count", "holdings", "by_type", "as_of"]}, "example": {"has_investments": true, "total_invested": 22662.87, "count": 2, "holdings": [{"name": "Tesouro Selic 2029", "type": "FIXED_INCOME", "balance": 18452.37, "code": null, "issuer": "Tesouro Nacional", "currency": "BRL"}, {"name": "ITSA4", "type": "EQUITY", "balance": 4210.5, "code": "ITSA4", "issuer": "Itaúsa", "currency": "BRL"}], "by_type": [{"type": "FIXED_INCOME", "total": 18452.37}, {"type": "EQUITY", "total": 4210.5}], "as_of": "2026-08-23T06:12:44.000Z"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_investments_summary", "description": "Resumo agregado das posições Open Finance: total investido, contagem, destaques por posição e totais por tipo. Objeto simples (sem envelope). Sem posições, retorna `has_investments:false` com listas vazias e `as_of:null`."}}, "/v1/investments/income": {"get": {"summary": "Proventos de investimentos", "tags": ["investments"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"available": {"type": "boolean", "description": "false quando a integração de dados de mercado (brapi) está desabilitada; nesse caso `data` vem vazio."}, "data": {"type": "array", "items": {"type": "object", "properties": {"asset_key": {"type": "string"}, "ticker": {"type": "string"}, "asset_name": {"type": "string"}, "type": {"type": "string", "enum": ["DIVIDENDO", "JCP", "RENDIMENTO"]}, "value_per_share": {"type": ["number", "null"]}, "ex_date": {"type": ["string", "null"], "description": "Data-ex ISO 8601, ou null."}, "payment_date": {"type": ["string", "null"], "description": "Data de pagamento ISO 8601, ou null."}, "announced_at": {"type": ["string", "null"], "description": "Data de aprovação/anúncio ISO 8601, ou null."}}, "required": ["asset_key", "ticker", "asset_name", "type", "value_per_share", "ex_date", "payment_date", "announced_at"]}}}, "required": ["available", "data"]}, "example": {"available": true, "data": [{"asset_key": "EQUITY:BRITSAACNPR8", "ticker": "ITSA4", "asset_name": "ITSA4", "type": "JCP", "value_per_share": 0.148, "ex_date": "2026-08-15T00:00:00.000Z", "payment_date": "2026-09-01T00:00:00.000Z", "announced_at": "2026-08-05T00:00:00.000Z"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string"}}], "operationId": "get_v1_investments_income", "description": "Proventos (dividendos, `JCP`, rendimentos) dos ativos B3 detidos pelo usuário, via dados de mercado. Sem `from`/`to` retorna proventos anunciados/futuros; com janela, filtra pela data de pagamento (data-ex como fallback). `available:false` quando a fonte de mercado está indisponível."}}, "/v1/investments/snapshots": {"get": {"summary": "Histórico de saldo investido", "tags": ["investments"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object", "properties": {"date": {"type": "string", "description": "Data do snapshot (YYYY-MM-DD)."}, "total": {"type": "number", "description": "Saldo total investido em BRL nessa data."}, "by_type": {"type": "object", "description": "Saldo por tipo de ativo: mapa de tipo (string) para valor em BRL.", "additionalProperties": {"type": "number"}}}, "required": ["date", "total", "by_type"]}}}, "required": ["data"]}, "example": {"data": [{"date": "2026-08-21", "total": 22540.11, "by_type": {"FIXED_INCOME": 18400, "EQUITY": 4140.11}}, {"date": "2026-08-22", "total": 22662.87, "by_type": {"FIXED_INCOME": 18452.37, "EQUITY": 4210.5}}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "from", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "to", "in": "query", "required": false, "schema": {"type": "string"}}], "operationId": "get_v1_investments_snapshots", "description": "Série de snapshots diários do saldo total investido e sua composição por tipo, ordenada por data crescente. Parâmetros opcionais `from`/`to` (YYYY-MM-DD) recortam a janela. Envelope `{data:[...]}`."}}, "/v1/investments/{id}": {"get": {"summary": "Detalhar investimento", "tags": ["investments"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Investment"}, {"type": "object", "properties": {"transactions": {"type": "array", "items": {"$ref": "#/components/schemas/InvestmentTransaction"}}}, "required": ["transactions"]}]}, "example": {"id": "ad902523-ece3-4c28-9937-b732c4f74e5c", "asset_key": "FIXED_INCOME:BRSTNCLF1R25", "name": "Tesouro Selic 2029", "type": "FIXED_INCOME", "sub_type": "TREASURY", "balance": 18452.37, "quantity": 1.23, "value": 15002.11, "code": null, "isin": "BRSTNCLF1R25", "issuer": "Tesouro Nacional", "currency": "BRL", "due_date": "2029-03-01", "purchase_date": "2024-06-12", "rate": 100, "rate_type": "SELIC", "fixed_annual_rate": null, "last_twelve_months_rate": 10.75, "indexer_additional_info": "SELIC", "tax_exempt": false, "status": "ACTIVE", "updated_at": "2026-08-23T06:12:44.000Z", "transactions": [{"id": "ff816a5e-a17e-424a-9d16-95216247932a", "type": "BUY", "movement_type": "IN", "date": "2024-06-12", "quantity": 1.23, "value": 12200, "amount": 15002.11, "net_amount": 15002.11, "description": "Aplicação Tesouro Selic"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "get_v1_investments_id", "description": "Detalha uma posição de investimento pelo id, incluindo seus movimentos ordenados por data decrescente. Retorna 404 se a posição não pertence ao usuário ou não existe."}}, "/v1/open-finance/connections": {"get": {"summary": "Listar conexões Open Finance", "tags": ["open-finance"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/OpenFinanceConnection"}}}, "required": ["data"]}, "example": {"data": [{"id": "87f1776a-a090-420e-94c6-e118ec7e5ad6", "connector_name": "Nubank", "status": "UPDATED", "execution_status": "SUCCESS", "error_code": null, "last_synced_at": "2026-08-24T06:15:00.000Z", "next_auto_sync_at": "2026-08-25T06:15:00.000Z", "consent_expires_at": "2027-02-24T00:00:00.000Z", "products": ["ACCOUNTS", "CREDIT_CARDS", "TRANSACTIONS"], "created_at": "2026-05-10T18:44:02.000Z", "accounts": [{"id": "286ea5c8-7168-4898-884f-b68badd197d8", "title": "Nubank", "type": "checking"}, {"id": "ad881087-f356-4637-840e-d3ab4102eb4d", "title": "Cartão Nubank", "type": "credit"}]}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_open_finance_connections", "description": "Retorna as conexões Open Finance (itens Pluggy) do usuário, ordenadas por data de criação, com status de saúde mascarado e as contas vinculadas a cada conexão. Exclui deliberadamente PII verificada pelo banco. Envelopado em `{data:[...]}` sem paginação."}}, "/v1/open-finance/connections/{id}/refresh": {"post": {"summary": "Sincronizar conexão Open Finance", "tags": ["open-finance"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Dispara uma atualização (refresh) do item Pluggy correspondente à conexão. Requer que o item respalde ao menos uma conta"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "post_v1_open_finance_connections_id_refresh", "description": "Dispara uma atualização (refresh) do item Pluggy correspondente à conexão. Requer que o item respalde ao menos uma conta do usuário (404 caso contrário). Rejeições da Pluggy mapeiam para 429 `rate_limited` (limite de criação de item, com `retry_after`), 503 `sync_busy` (já sincronizando) ou 400 `validation_error`. Sucesso não retorna corpo (204 No Content)."}}, "/v1/transactions": {"get": {"summary": "Listar lançamentos", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "has_more", "next_cursor"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Transaction"}}, "has_more": {"type": "boolean"}, "next_cursor": {"type": ["string", "null"], "description": "Cursor opaco (base64url) da próxima página; null quando não há mais."}}}, "example": {"data": [{"id": "9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "projected": false, "projection": null, "date": "2026-08-19", "type": "DEBIT", "status": "POSTED", "amount": 89.9, "currency": "BRL", "description": "Mercado Pao de Acucar", "notes": null, "account_id": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d", "bill_to_account_id": null, "category_id": "c0ffee00-1111-4222-8333-444455556666", "tags": [{"id": "7a11d00d-2222-4333-8444-555566667777", "title": "Supermercado", "color_hex": "#22C55E"}], "recurrence_id": null, "recurrence_period_date": null, "installment": null, "transfer_group_id": null, "created_by_user": false, "source": "OPEN_FINANCE", "hide_from_results": false, "card_number": "4821", "holder": "Stefanie", "holder_is_me": false, "original_description": "PAO DE ACUCAR 1234 SAO PAULO BR", "receipt_url": null, "open_finance": true}], "has_more": true, "next_cursor": "eyJkIjoxNzU1NTY0ODAwMDAwLCJpZCI6IjlmMmI2YTFjLTRlM2QtNGEyYi04YzFlLTJiN2Q1ZjBhMWMzMyJ9"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "from", "in": "query", "required": true, "description": "Início da janela (YYYY-MM-DD), obrigatório.", "schema": {"description": "Início da janela (YYYY-MM-DD), obrigatório.", "type": "string"}}, {"name": "to", "in": "query", "required": true, "description": "Fim da janela (YYYY-MM-DD), obrigatório; máx. 366 dias.", "schema": {"description": "Fim da janela (YYYY-MM-DD), obrigatório; máx. 366 dias.", "type": "string"}}, {"name": "view", "in": "query", "required": false, "description": "cashflow (padrão: faturas na conta pagadora) ou ledger (linhas cruas por conta).", "schema": {"description": "cashflow (padrão: faturas na conta pagadora) ou ledger (linhas cruas por conta).", "type": "string"}}, {"name": "status", "in": "query", "required": false, "description": "`PENDING` ou `POSTED`.", "schema": {"description": "`PENDING` ou `POSTED`.", "type": "string"}}, {"name": "type", "in": "query", "required": false, "description": "`DEBIT` ou `CREDIT`.", "schema": {"description": "`DEBIT` ou `CREDIT`.", "type": "string"}}, {"name": "account_id", "in": "query", "required": false, "description": "Ids de conta separados por vírgula.", "schema": {"description": "Ids de conta separados por vírgula.", "type": "string"}}, {"name": "category_id", "in": "query", "required": false, "description": "Ids de categoria separados por vírgula.", "schema": {"description": "Ids de categoria separados por vírgula.", "type": "string"}}, {"name": "include_subcategories", "in": "query", "required": false, "description": "true (padrão) expande categorias-pai para subcategorias.", "schema": {"description": "true (padrão) expande categorias-pai para subcategorias.", "type": "string"}}, {"name": "tag_id", "in": "query", "required": false, "description": "Ids de tag separados por vírgula.", "schema": {"description": "Ids de tag separados por vírgula.", "type": "string"}}, {"name": "no_category", "in": "query", "required": false, "description": "true: só lançamentos sem categoria.", "schema": {"description": "true: só lançamentos sem categoria.", "type": "string"}}, {"name": "no_tags", "in": "query", "required": false, "description": "true: só lançamentos sem tags.", "schema": {"description": "true: só lançamentos sem tags.", "type": "string"}}, {"name": "is_recurring", "in": "query", "required": false, "description": "true: só lançamentos de recorrência.", "schema": {"description": "true: só lançamentos de recorrência.", "type": "string"}}, {"name": "is_installments", "in": "query", "required": false, "description": "true: só parcelas.", "schema": {"description": "true: só parcelas.", "type": "string"}}, {"name": "bill_id", "in": "query", "required": false, "description": "Id de fatura (mocked-bill:… ou id de fatura Open Finance): lançamentos daquele ciclo do cartão.", "schema": {"description": "Id de fatura (mocked-bill:… ou id de fatura Open Finance): lançamentos daquele ciclo do cartão.", "type": "string"}}, {"name": "sub_type", "in": "query", "required": false, "description": "Subtipos de conta separados por vírgula (`SAVINGS_ACCOUNT`, `CHECKING_ACCOUNT`, `CREDIT_CARD`).", "schema": {"description": "Subtipos de conta separados por vírgula (`SAVINGS_ACCOUNT`, `CHECKING_ACCOUNT`, `CREDIT_CARD`).", "type": "string"}}, {"name": "hidden", "in": "query", "required": false, "description": "true: só linhas ocultas; false/omitido: só visíveis.", "schema": {"description": "true: só linhas ocultas; false/omitido: só visíveis.", "type": "string"}}, {"name": "search", "in": "query", "required": false, "description": "Busca em descrição/notas/descrição original.", "schema": {"description": "Busca em descrição/notas/descrição original.", "type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "Tamanho da página (padrão 50, máx. 100).", "schema": {"description": "Tamanho da página (padrão 50, máx. 100).", "type": "string"}}, {"name": "cursor", "in": "query", "required": false, "description": "Cursor da página anterior (`next_cursor`).", "schema": {"description": "Cursor da página anterior (`next_cursor`).", "type": "string"}}], "operationId": "get_v1_transactions", "description": "Lista a visão canônica mesclada (linhas persistidas + projeções mocked-*) dentro de uma janela `from`/`to` obrigatória (YYYY-MM-DD, máx. 366 dias), com filtros por conta, categoria, tag, tipo, status, subtipo, fatura, busca textual e ocultos. Retorna a página ordenada (dia mais novo primeiro, id ascendente dentro do dia) com paginação por cursor."}, "post": {"summary": "Criar lançamento", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "Criação simples/parcelada (201) ou replay idempotente (200).", "required": ["transaction"], "properties": {"transaction": {"anyOf": [{"$ref": "#/components/schemas/Transaction"}, {"type": "null"}]}, "deduped": {"type": "boolean", "description": "true no replay idempotente de um `id` de cliente já existente."}, "warnings": {"type": "array", "items": {"$ref": "#/components/schemas/PossibleDuplicateWarning"}}, "mark_cycle_posted_ignored": {"type": "boolean", "description": "true quando `mark_cycle_posted` foi enviado no `POST` (inerte aqui; use `PATCH` na fatura projetada)."}}}, {"type": "object", "description": "Criação de recorrência (201, ou 200 quando reaproveitou regra viva).", "required": ["recurring_rule_id"], "properties": {"recurring_rule_id": {"type": "string"}, "first_occurrence_transaction_id": {"type": "string", "description": "Presente quando a primeira ocorrência foi materializada."}, "deduped": {"type": "boolean", "description": "true quando reaproveitou uma regra equivalente existente."}}}]}, "example": {"transaction": {"id": "3c9f1e77-8a2b-4c6d-9e0f-1a2b3c4d5e6f", "projected": false, "projection": null, "date": "2026-08-24", "type": "DEBIT", "status": "POSTED", "amount": 149.9, "currency": "BRL", "description": "Farmacia Sao Joao", "notes": "Remedio mensal", "account_id": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d", "bill_to_account_id": null, "category_id": null, "tags": [], "recurrence_id": null, "recurrence_period_date": null, "installment": null, "transfer_group_id": null, "created_by_user": true, "source": "API", "hide_from_results": false, "card_number": null, "holder": null, "holder_is_me": false, "original_description": null, "receipt_url": null, "open_finance": false}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"description": "Id (uuid v4) do cliente para idempotência; só criações simples.", "type": "string"}, "account_id": {"type": "string"}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "amount": {"exclusiveMinimum": 0, "description": "Sempre positivo; parcelado: valor `TOTAL` da compra.", "type": "number"}, "description": {"minLength": 1, "type": "string"}, "date": {"description": "YYYY-MM-DD (dia calendário BRT); padrão hoje.", "type": "string"}, "category_id": {"type": "string"}, "tag_ids": {"type": "array", "items": {"type": "string"}}, "notes": {"maxLength": 1000, "type": "string"}, "status": {"anyOf": [{"const": "PENDING", "type": "string"}, {"const": "POSTED", "type": "string"}]}, "hide_from_results": {"type": "boolean"}, "currency": {"maxLength": 3, "type": "string"}, "bill_to_account_id": {"description": "Pagamento de fatura: o cartão pago.", "type": "string"}, "mark_cycle_posted": {"description": "Com `bill_to_account_id`: também baixa (`POSTED`) os lançamentos do ciclo pago.", "type": "boolean"}, "installments": {"minimum": 2, "maximum": 240, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 2, "maximum": 240, "type": "integer"}]}, "recurrence": {"type": "object", "properties": {"type": {"anyOf": [{"const": "DAILY", "type": "string"}, {"const": "WEEKLY", "type": "string"}, {"const": "MONTHLY", "type": "string"}, {"const": "QUARTERLY", "type": "string"}, {"const": "SEMIANNUALLY", "type": "string"}, {"const": "ANNUALLY", "type": "string"}]}, "start_date": {"type": "string"}, "end_date": {"type": "string"}, "interval": {"minimum": 1, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "type": "integer"}]}}, "required": ["type", "start_date"]}, "dedupe": {"description": "Recorrências: reutiliza regra equivalente viva (padrão true).", "type": "boolean"}, "materialize_first": {"type": "boolean"}}, "required": ["account_id", "type", "amount", "description"]}}}}, "operationId": "post_v1_transactions", "description": "Cria um lançamento simples, uma compra parcelada (`installments`) ou uma regra de recorrência (`recurrence`). Aceita `id` (uuid) do cliente para idempotência em criações simples (replay do mesmo payload devolve a linha com `deduped: true` e status 200; payload divergente devolve 409 `id_conflict`). Criação simples/parcelada devolve o lançamento criado (201); recorrência devolve o id da regra (201, ou 200 quando reaproveita uma regra equivalente)."}}, "/v1/transactions/duplicates": {"get": {"summary": "Listar possíveis duplicatas", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["groups", "group_count", "duplicate_row_count", "period"], "properties": {"groups": {"type": "array", "items": {"$ref": "#/components/schemas/DuplicateGroup"}}, "group_count": {"type": "integer"}, "duplicate_row_count": {"type": "integer"}, "period": {"type": "object", "required": ["from", "to"], "properties": {"from": {"type": "string", "description": "YYYY-MM-DD."}, "to": {"type": "string", "description": "YYYY-MM-DD."}}}}}, "example": {"groups": [{"description": "Netflix", "amount": 44.9, "type": "DEBIT", "transactions": [{"id": "aa11bb22-cc33-4dd4-8ee5-ff6600112233", "description": "Netflix", "amount": 44.9, "type": "DEBIT", "status": "POSTED", "date": "2026-08-10", "account_id": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d", "category_id": "c0ffee00-1111-4222-8333-444455556666", "source": "OPEN_FINANCE"}, {"id": "bb22cc33-dd44-4ee5-8ff6-001122334455", "description": "Netflix", "amount": 44.9, "type": "DEBIT", "status": "POSTED", "date": "2026-08-10", "account_id": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d", "category_id": null, "source": "MANUAL"}]}], "group_count": 1, "duplicate_row_count": 2, "period": {"from": "2026-08-01", "to": "2026-08-24"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": {"description": "YYYY-MM-DD", "type": "string"}}, {"name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": {"description": "YYYY-MM-DD", "type": "string"}}], "operationId": "get_v1_transactions_duplicates", "description": "Agrupa lançamentos que parecem duplicados (mesma descrição, valor e tipo) dentro de uma janela `from`/`to` opcional (YYYY-MM-DD). Retorna os grupos com suas linhas, contagens e o período efetivamente analisado."}}, "/v1/transactions/bulk": {"post": {"summary": "Atualizar ou excluir lançamentos em massa", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "Resposta de exclusão em massa (delete: true).", "required": ["deleted_count", "skipped_open_finance"], "properties": {"deleted_count": {"type": "integer"}, "skipped_open_finance": {"type": "integer", "description": "Linhas de Open Finance não excluídas por não terem sido criadas manualmente."}}}, {"type": "object", "description": "Resposta de atualização em massa (set).", "required": ["updated_count", "skipped", "skipped_open_finance"], "properties": {"updated_count": {"type": "integer"}, "skipped": {"type": "array", "items": {"$ref": "#/components/schemas/BulkSkippedRow"}, "description": "Linhas que recusaram parte das alterações."}, "skipped_open_finance": {"type": "integer"}}}]}, "example": {"updated_count": 12, "skipped": [{"id": "cc33dd44-ee55-4ff6-8001-223344556677", "reason": "open_finance_locked", "fields": ["amount", "description"]}], "skipped_open_finance": 1}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"ids": {"maxItems": 500, "type": "array", "items": {"type": "string"}}, "filter": {"type": "object", "properties": {"from": {"type": "string"}, "to": {"type": "string"}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "category_id": {"type": "string"}, "account_id": {"type": "string"}, "search": {"type": "string"}, "no_category": {"type": "boolean"}}}, "expected_count": {"minimum": 0, "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 0, "type": "integer"}]}, "set": {"type": "object", "properties": {"category_id": {"anyOf": [{"type": "string"}, {"type": "null"}]}, "account_id": {"type": "string"}, "hide_from_results": {"type": "boolean"}, "status": {"anyOf": [{"const": "PENDING", "type": "string"}, {"const": "POSTED", "type": "string"}]}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "date": {"type": "string"}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "description": {"minLength": 1, "type": "string"}, "notes": {"anyOf": [{"maxLength": 1000, "type": "string"}, {"type": "null"}]}, "add_tag_ids": {"type": "array", "items": {"type": "string"}}, "remove_tag_ids": {"type": "array", "items": {"type": "string"}}}}, "delete": {"type": "boolean"}}}}}}, "operationId": "post_v1_transactions_bulk", "description": "Aplica uma atualização (`set`) ou exclusão (`delete: true`) a um conjunto de lançamentos, selecionados por `ids` (só ids persistidos, sem projeções mocked-*) e/ou `filter`, com `expected_count` opcional de guarda. Sujeito a rate limit próprio (10/hora). Retorna as contagens de itens afetados e ignorados."}}, "/v1/transactions/{id}": {"get": {"summary": "Buscar lançamento", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["transaction"], "properties": {"transaction": {"$ref": "#/components/schemas/Transaction"}}}, "example": {"transaction": {"id": "9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "projected": false, "projection": null, "date": "2026-08-19", "type": "DEBIT", "status": "POSTED", "amount": 89.9, "currency": "BRL", "description": "Mercado Pao de Acucar", "notes": null, "account_id": "1a2b3c4d-5e6f-4a1b-9c8d-7e6f5a4b3c2d", "bill_to_account_id": null, "category_id": "c0ffee00-1111-4222-8333-444455556666", "tags": [], "recurrence_id": null, "recurrence_period_date": null, "installment": null, "transfer_group_id": null, "created_by_user": false, "source": "OPEN_FINANCE", "hide_from_results": false, "card_number": "4821", "holder": null, "holder_is_me": true, "original_description": "PAO DE ACUCAR 1234 SAO PAULO BR", "receipt_url": "https://cdn.dinzo.app/receipts/…/1755600000000-abc.jpg", "open_finance": true}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "get_v1_transactions_id", "description": "Retorna um único lançamento por id, aceitando tanto ids persistidos (uuid) quanto handles projetados (mocked-recurrence:/mocked-installment:/mocked-bill:...). Projeções são resolvidas re-executando a visão mesclada na janela que as reproduz; 404 `not_found` (persistido) ou 404 `projection_not_found` (projeção inexistente)."}, "patch": {"summary": "Editar lançamento", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "description": "União dos resultados de edição — os campos presentes dependem do tipo de alvo (linha real, fatura, parcela projetada ou recorrência).", "properties": {"updated_transaction_id": {"type": "string", "description": "Linha real editada."}, "transaction_id": {"type": "string", "description": "Lançamento criado ao registrar pagamento de fatura (mocked-bill)."}, "materialized_transaction_id": {"type": "string", "description": "Parcela/ocorrência projetada materializada em linha real."}, "new_recurrence_id": {"type": "string", "description": "Nova regra gerada ao bifurcar a série (scope future/all)."}, "source_recurrence_id": {"type": "string", "description": "Regra de origem bifurcada."}, "scope": {"type": "string", "enum": ["this", "future", "all"]}, "deduped": {"type": "boolean", "description": "true quando adotou uma ocorrência já materializada em vez de duplicar."}, "bill_to_account_id": {"type": "string", "description": "Cartão pago (edição de fatura)."}, "bill_due_date": {"type": "string", "description": "Vencimento da fatura paga (ISO)."}, "posted_transaction_ids": {"type": "array", "items": {"type": "string"}, "description": "Lançamentos do ciclo baixados quando `mark_cycle_posted`=true."}, "materialized_transaction_ids": {"type": "array", "items": {"type": "string"}, "description": "Lançamentos do ciclo materializados quando `mark_cycle_posted`=true."}, "message": {"type": ["string", "null"], "description": "Orientação legível (ex.: só campos permitidos foram atualizados em linha não criada pelo usuário)."}}}, "example": {"updated_transaction_id": "9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "message": null}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"scope": {"description": "Obrigatório para ids mocked-recurrence:/mocked-installment:.", "anyOf": [{"const": "this", "type": "string"}, {"const": "future", "type": "string"}, {"const": "all", "type": "string"}]}, "account_id": {"type": "string"}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "category_id": {"type": "string"}, "tags": {"description": "Substitui o conjunto de tags; null limpa.", "anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "null"}]}, "date": {"type": "string"}, "original_date": {"description": "Edição de UMA ocorrência por id de regra: o dia atual da ocorrência.", "type": "string"}, "description": {"minLength": 1, "type": "string"}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "notes": {"maxLength": 1000, "type": "string"}, "status": {"anyOf": [{"const": "PENDING", "type": "string"}, {"const": "POSTED", "type": "string"}]}, "hide_from_results": {"type": "boolean"}, "currency": {"maxLength": 3, "type": "string"}, "bill_to_account_id": {"type": "string"}, "mark_cycle_posted": {"type": "boolean"}}}}}}, "operationId": "patch_v1_transactions_id", "description": "Edita um lançamento persistido ou uma projeção. Para ids projetados de recorrência/parcela `scope` é obrigatório ('this' | 'future' | 'all'). Editar um handle de fatura (mocked-bill:) registra o pagamento; editar uma parcela projetada a materializa; editar uma ocorrência de recorrência materializa/bifurca a série. O corpo de resposta varia conforme o alvo — devolve os ids afetados e mensagens de orientação."}, "delete": {"summary": "Excluir lançamento", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "description": "União dos resultados de exclusão — os campos presentes dependem do tipo de alvo.", "properties": {"deleted_transaction_id": {"type": "string", "description": "Linha real excluída (soft-delete)."}, "success": {"type": "boolean", "description": "true em exclusões de projeção e cascatas de recorrência."}, "scope": {"type": "string", "enum": ["this", "future", "all"]}, "mode": {"type": "string", "enum": ["single", "future", "all"], "description": "Modo da cascata de recorrência."}, "bill_due_date": {"type": "string", "description": "Vencimento da fatura projetada removida (ISO)."}, "hidden_series_leg_ids": {"type": "array", "items": {"type": "string"}, "description": "Parcelas ocultadas quando `hide_series`=true."}, "rule_ids_touched": {"type": "array", "items": {"type": "string"}}, "transaction_ids_deleted": {"type": "array", "items": {"type": "string"}}, "transaction_ids_unlinked": {"type": "array", "items": {"type": "string"}}, "markers_written": {"type": "integer", "description": "Quantidade de tombstones gravados (cascata de recorrência)."}, "message": {"type": "string"}}}, "example": {"deleted_transaction_id": "9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "scope", "in": "query", "required": false, "description": "this | future | all", "schema": {"description": "this | future | all", "type": "string"}}, {"name": "preserve_posted", "in": "query", "required": false, "description": "true (padrão): ocorrências `POSTED` são preservadas", "schema": {"description": "true (padrão): ocorrências `POSTED` são preservadas", "type": "string"}}, {"name": "hide_series", "in": "query", "required": false, "description": "true: oculta a série de parcelas inteira", "schema": {"description": "true: oculta a série de parcelas inteira", "type": "string"}}, {"name": "date", "in": "query", "required": false, "description": "Alvos por id de regra com scope this/future: o dia da ocorrência/corte (YYYY-MM-DD)", "schema": {"description": "Alvos por id de regra com scope this/future: o dia da ocorrência/corte (YYYY-MM-DD)", "type": "string"}}], "operationId": "delete_v1_transactions_id", "description": "Exclui um lançamento persistido ou registra um tombstone para uma projeção (fatura, parcela ou ocorrência de recorrência). Para regras/recorrências use `scope` ('this'|'future'|'all'), `preserve_posted` (padrão true) e `hide_series` (oculta a série de parcelas inteira). Retorna um corpo JSON (200, não 204) descrevendo o que foi excluído/ocultado."}}, "/v1/transfers": {"post": {"summary": "Criar transferência", "tags": ["transfers"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["transfer_sent_transaction_id", "transfer_received_transaction_id"], "properties": {"transfer_sent_transaction_id": {"type": "string", "description": "Perna de débito (conta de origem)."}, "transfer_received_transaction_id": {"type": "string", "description": "Perna de crédito (conta de destino)."}}}, "example": {"transfer_sent_transaction_id": "e1f2a3b4-c5d6-4e7f-8a90-1b2c3d4e5f60", "transfer_received_transaction_id": "f2a3b4c5-d6e7-4f80-9a1b-2c3d4e5f6071"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"from_account_id": {"type": "string"}, "to_account_id": {"type": "string"}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "date": {"type": "string"}, "description": {"minLength": 1, "type": "string"}, "notes": {"maxLength": 1000, "type": "string"}}, "required": ["from_account_id", "to_account_id", "amount", "description"]}}}}, "operationId": "post_v1_transfers", "description": "Cria uma transferência interna entre duas contas do usuário: gera as duas pernas (débito na conta de origem, crédito na de destino) já agrupadas. Corpo exige `from_account_id`, `to_account_id`, `amount` (positivo) e `description`. Retorna os ids das duas pernas (201)."}}, "/v1/transactions/{id}/mark-transfer": {"post": {"summary": "Marcar como transferência", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["transfer_group_id", "transaction_ids"], "properties": {"transfer_group_id": {"type": "string"}, "transaction_ids": {"type": "array", "items": {"type": "string"}, "description": "Ids agrupados (a linha e, quando houver, a contraparte)."}}}, "example": {"transfer_group_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70", "transaction_ids": ["9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "aa11bb22-cc33-4dd4-8ee5-ff6600112233"]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"counterpart_id": {"type": "string"}}}}}}, "operationId": "post_v1_transactions_id_mark_transfer", "description": "Marca um lançamento (e, se informado `counterpart_id`, sua contraparte) como transferência interna: gera um `transfer_group_id` novo e oculta a(s) linha(s) dos resultados. As categorias definidas pelo usuário são mantidas. 409 quando o lançamento (ou a contraparte) já pertence a uma transferência; 404 quando o alvo não existe."}}, "/v1/transactions/{id}/unmark-transfer": {"post": {"summary": "Desmarcar transferência", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["transaction_ids"], "properties": {"transaction_ids": {"type": "array", "items": {"type": "string"}, "description": "Ids das linhas cujas marcações foram desfeitas."}}}, "example": {"transaction_ids": ["9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "aa11bb22-cc33-4dd4-8ee5-ff6600112233"]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "post_v1_transactions_id_unmark_transfer", "description": "Desfaz a marcação de transferência. Pares agrupados têm ambas as pernas liberadas (a categoria \"Transferência\" volta a \"sem categoria\"; categorias escolhidas pelo usuário permanecem); linhas legadas/heurísticas (ocultas com categoria Transferência, sem par) voltam a aparecer e têm a categoria limpa. 404 quando o alvo não existe."}}, "/v1/transactions/{id}/receipt": {"put": {"summary": "Anexar comprovante", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "required": ["transaction_id", "receipt_url"], "properties": {"transaction_id": {"type": "string"}, "receipt_url": {"type": "string"}}}, "example": {"transaction_id": "9f2b6a1c-4e3d-4a2b-8c1e-2b7d5f0a1c33", "receipt_url": "https://cdn.dinzo.app/receipts/1a2b/9f2b6a1c/1755600000000-7d3c9a1e.jpg"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"file": {"default": "File", "type": "string", "format": "binary"}}, "required": ["file"]}}}}, "operationId": "put_v1_transactions_id_receipt", "description": "Envia (multipart, campo `file`) e anexa um comprovante ao lançamento, substituindo o anterior se houver. Tipos aceitos: JPEG, PNG, PDF, HEIC, WebP; máximo 10MB. 400 para tipo/tamanho inválido; 404 quando o lançamento não existe. Retorna o id do lançamento e a URL pública do comprovante."}, "delete": {"summary": "Remover comprovante", "tags": ["transactions"], "security": [{"bearerAuth": []}], "responses": {"204": {"description": "Remove o comprovante anexado ao lançamento (apaga o arquivo no storage e limpa `receipt_url`). 404 quando o lançamento n"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "delete_v1_transactions_id_receipt", "description": "Remove o comprovante anexado ao lançamento (apaga o arquivo no storage e limpa `receipt_url`). 404 quando o lançamento não existe ou não possui comprovante. Sem corpo de resposta."}}, "/v1/recurring-rules": {"get": {"summary": "Listar regras recorrentes", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"rules": {"type": "array", "items": {"$ref": "#/components/schemas/RecurringRule"}}, "projected_occurrences": {"type": "array", "description": "Presente apenas com include=occurrences.", "items": {"$ref": "#/components/schemas/RecurringOccurrence"}}, "exceptions": {"type": "array", "description": "Presente apenas com include=occurrences.", "items": {"$ref": "#/components/schemas/RecurringException"}}, "window": {"description": "Presente apenas com include=occurrences.", "$ref": "#/components/schemas/RecurrenceWindow"}}, "required": ["rules"]}, "example": {"rules": [{"id": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "bill_to_account_id": null, "type": "DEBIT", "category_id": "1f0a2c3e-4d5b-6a7c-8e9f-0b1d2c3e4f5a", "recurrence_type": "MONTHLY", "recurrence_interval": 1, "is_installments": false, "parent_id": null, "start_date": "2026-01-05", "end_date": null, "description": "Aluguel", "amount": 2400, "currency": "BRL", "notes": null, "hide_from_results": false, "tags": [{"id": "7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "title": "Casa", "color_hex": "#2E7D32"}], "created_at": "2026-01-05T10:00:00.000Z"}], "projected_occurrences": [{"id": "ace875e7-5fc1-4319-978e-b0a667ee561a", "rule_id": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "date": "2026-08-05", "type": "DEBIT", "description": "Aluguel", "amount": 2400, "currency": "BRL", "category_id": "1f0a2c3e-4d5b-6a7c-8e9f-0b1d2c3e4f5a", "installment": null, "status": "PENDING"}], "exceptions": [{"rule_id": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "date": "2026-07-05"}], "window": {"from": "2026-07-01", "to": "2026-11-01"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "include", "in": "query", "required": false, "description": "occurrences: inclui ocorrências projetadas + exceções.", "schema": {"description": "occurrences: inclui ocorrências projetadas + exceções.", "type": "string"}}, {"name": "from", "in": "query", "required": false, "description": "Início da janela de ocorrências (YYYY-MM-DD).", "schema": {"description": "Início da janela de ocorrências (YYYY-MM-DD).", "type": "string"}}, {"name": "to", "in": "query", "required": false, "description": "Fim da janela de ocorrências (YYYY-MM-DD).", "schema": {"description": "Fim da janela de ocorrências (YYYY-MM-DD).", "type": "string"}}], "operationId": "get_v1_recurring_rules", "description": "Lista as regras de recorrência do usuário, ordenadas por criação (mais recentes primeiro). Com include=occurrences, acrescenta as ocorrências projetadas na janela, as exceções (ocorrências suprimidas) e a janela usada. A janela padrão vai do mês BRT atual −1 até +3 (semiaberta); from/to (YYYY-MM-DD) a sobrescrevem — with to informado a janela passa a ser inclusiva no fim. from/to inválidos retornam 400 (`validation_error`)."}, "post": {"summary": "Criar regra recorrente", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"recurring_rule_id": {"type": "string", "description": "Id da regra criada ou reaproveitada."}, "first_occurrence_transaction_id": {"type": "string", "description": "Presente quando a 1ª ocorrência foi materializada (`materialize_first`)."}, "deduped": {"type": "boolean", "enum": [true], "description": "Presente (true) apenas quando uma regra equivalente foi reaproveitada (resposta 200)."}}, "required": ["recurring_rule_id"]}, "example": {"recurring_rule_id": "b8d4f2a6-1e3c-4b5a-9d7f-2c0e8b6a4f13", "first_occurrence_transaction_id": "d1c3b5a7-9e8f-4a2b-8c6d-0f1e2a3b4c5d"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"account_id": {"type": "string"}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "description": {"minLength": 1, "type": "string"}, "recurrence": {"type": "object", "properties": {"type": {"anyOf": [{"const": "DAILY", "type": "string"}, {"const": "WEEKLY", "type": "string"}, {"const": "MONTHLY", "type": "string"}, {"const": "QUARTERLY", "type": "string"}, {"const": "SEMIANNUALLY", "type": "string"}, {"const": "ANNUALLY", "type": "string"}]}, "start_date": {"description": "YYYY-MM-DD", "type": "string"}, "end_date": {"type": "string"}, "interval": {"minimum": 1, "description": "A cada N períodos (padrão 1).", "anyOf": [{"format": "integer", "default": 0, "type": "string"}, {"minimum": 1, "description": "A cada N períodos (padrão 1).", "type": "integer"}]}}, "required": ["type", "start_date"]}, "category_id": {"type": "string"}, "tag_ids": {"type": "array", "items": {"type": "string"}}, "notes": {"maxLength": 1000, "type": "string"}, "hide_from_results": {"type": "boolean"}, "currency": {"maxLength": 3, "type": "string"}, "bill_to_account_id": {"type": "string"}, "dedupe": {"description": "Reutiliza regra equivalente viva (padrão true).", "type": "boolean"}, "materialize_first": {"description": "Materializa a 1ª ocorrência mesmo com início futuro.", "type": "boolean"}}, "required": ["account_id", "type", "amount", "description", "recurrence"]}}}}, "operationId": "post_v1_recurring_rules", "description": "Cria uma regra de recorrência através do mesmo núcleo usado pelas ferramentas de IA. Requer o escopo de escrita. Retorna 201 com o id da regra; com dedupe (padrão) e uma regra equivalente já existente, reaproveita-a e retorna 200 com deduped:true. Com `materialize_first`, também materializa a 1ª ocorrência e retorna seu id. Erros de domínio (conta/categoria/tag inexistente etc.) retornam problem+json (400/404/409)."}}, "/v1/recurring-rules/{id}": {"get": {"summary": "Buscar regra recorrente", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"rule": {"$ref": "#/components/schemas/RecurringRule"}}, "required": ["rule"]}, "example": {"rule": {"id": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "bill_to_account_id": null, "type": "DEBIT", "category_id": "1f0a2c3e-4d5b-6a7c-8e9f-0b1d2c3e4f5a", "recurrence_type": "MONTHLY", "recurrence_interval": 1, "is_installments": false, "parent_id": null, "start_date": "2026-01-05", "end_date": null, "description": "Aluguel", "amount": 2400, "currency": "BRL", "notes": "Reajuste anual em janeiro.", "hide_from_results": false, "tags": [{"id": "7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "title": "Casa", "color_hex": "#2E7D32"}], "created_at": "2026-01-05T10:00:00.000Z"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "get_v1_recurring_rules_id", "description": "Retorna uma regra de recorrência específica do usuário, com suas etiquetas. Retorna 404 (`not_found`) se a regra não existir ou não pertencer ao usuário."}, "patch": {"summary": "Editar regra recorrente", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"rule_id_before": {"type": "string", "description": "Id da versão de origem da regra."}, "rule_id_after": {"type": "string", "description": "Id da versão resultante (difere de `rule_id_before` em scope=future)."}, "materialized_transaction_id": {"type": "string", "description": "Presente quando a edição materializou um lançamento."}, "scope": {"type": "string", "enum": ["future", "all"], "description": "Escopo aplicado (padrão \"all\")."}}, "required": ["rule_id_before", "rule_id_after", "scope"]}, "example": {"rule_id_before": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "rule_id_after": "f6b0d8e2-4c71-4a39-8b25-9d3f1c7e6a04", "scope": "future"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"scope": {"description": "future exige `from_date` (dia de corte); padrão all.", "anyOf": [{"const": "future", "type": "string"}, {"const": "all", "type": "string"}]}, "from_date": {"description": "Dia de corte YYYY-MM-DD para scope future.", "type": "string"}, "type": {"anyOf": [{"const": "DEBIT", "type": "string"}, {"const": "CREDIT", "type": "string"}]}, "category_id": {"type": "string"}, "tags": {"anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "null"}]}, "description": {"minLength": 1, "type": "string"}, "amount": {"exclusiveMinimum": 0, "type": "number"}, "notes": {"maxLength": 1000, "type": "string"}, "hide_from_results": {"type": "boolean"}, "currency": {"maxLength": 3, "type": "string"}}}}}}, "operationId": "patch_v1_recurring_rules_id", "description": "Edita uma regra de recorrência. scope=all (padrão) altera toda a série; scope=future exige `from_date` (dia de corte) e cria uma nova versão a partir dele. tags:null limpa as etiquetas. Retorna os ids da regra antes/depois (podem diferir em scope=future), o escopo aplicado e, quando houver, o id do lançamento materializado. 404 (`not_found`) se a regra não existir; erros de domínio retornam problem+json."}, "delete": {"summary": "Excluir regra recorrente", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RecurrenceDeleteResult"}, "example": {"success": true, "scope": "all", "mode": "all", "rule_ids_touched": ["e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "f6b0d8e2-4c71-4a39-8b25-9d3f1c7e6a04"], "transaction_ids_deleted": ["b4d6f8a0-2c3e-4f5a-9b7d-1e3f5a7c9b0d"], "transaction_ids_unlinked": ["c5e7a9b1-3d4f-5a6b-8c0d-2f4a6c8e0b1d"], "markers_written": 0}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "preserve_posted", "in": "query", "required": false, "description": "true (padrão): mantém ocorrências `POSTED` como histórico.", "schema": {"description": "true (padrão): mantém ocorrências `POSTED` como histórico.", "type": "string"}}], "operationId": "delete_v1_recurring_rules_id", "description": "Exclui toda a cadeia da regra (scope `ALL`). Por padrão `preserve_posted`=true mantém as ocorrências `POSTED` como histórico (desvinculando-as da regra); `preserve_posted`=false remove também os lançamentos `POSTED`. Responde 200 com o resumo da exclusão (não é 204). 404 (`not_found`) se a regra não existir."}}, "/v1/recurring-rules/{id}/stop": {"post": {"summary": "Encerrar regra recorrente", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RecurrenceDeleteResult"}, "example": {"success": true, "scope": "future", "mode": "future", "rule_ids_touched": ["e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96"], "transaction_ids_deleted": ["a3c5e7f9-1b2d-4e6f-8a0c-2d4f6b8a0c2e"], "transaction_ids_unlinked": [], "markers_written": 0}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "post_v1_recurring_rules_id_stop", "description": "Encerra a regra a partir de hoje (truncamento `FUTURE`): as ocorrências futuras são interrompidas e o histórico `POSTED` é preservado — a regra permanece como seu passado. Requer o escopo de escrita. Retorna o resumo do encerramento. 404 (`not_found`) se a regra não existir."}}, "/v1/recurring-rules/{id}/occurrences/{date}/suppress": {"post": {"summary": "Suprimir ocorrência", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"rule_id": {"type": "string"}, "suppressed_date": {"type": "string", "format": "date", "description": "Dia suprimido (YYYY-MM-DD)."}}, "required": ["rule_id", "suppressed_date"]}, "example": {"rule_id": "e5a9c7d1-3b60-4f28-9a14-7c2e0b8d5f96", "suppressed_date": "2026-09-05"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "date", "in": "path", "required": true, "description": "Dia da ocorrência (YYYY-MM-DD).", "schema": {"description": "Dia da ocorrência (YYYY-MM-DD).", "type": "string"}}], "operationId": "post_v1_recurring_rules_id_occurrences_date_suppress", "description": "Suprime uma única ocorrência projetada da regra no dia informado (remove aquela cobrança futura sem afetar as demais). date deve ser YYYY-MM-DD (400 `validation_error` caso contrário). Requer o escopo de escrita. Retorna o id da regra e o dia suprimido. 404 (`not_found`) se a regra não existir."}}, "/v1/recurring-rules/{id}/occurrences/{date}/materialize": {"post": {"summary": "Materializar ocorrência", "tags": ["recurring-rules"], "security": [{"bearerAuth": []}], "responses": {"201": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"transaction_id": {"type": "string", "description": "Id do lançamento materializado."}, "deduped": {"type": "boolean", "description": "true quando a ocorrência já existia (resposta 200)."}}, "required": ["transaction_id", "deduped"]}, "example": {"transaction_id": "d7f9b1c3-5e6a-4b7c-9d8e-0f1a2b3c4d5e", "deduped": false}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "date", "in": "path", "required": true, "description": "Dia da ocorrência (YYYY-MM-DD).", "schema": {"description": "Dia da ocorrência (YYYY-MM-DD).", "type": "string"}}], "operationId": "post_v1_recurring_rules_id_occurrences_date_materialize", "description": "Materializa uma ocorrência projetada da regra no dia informado, transformando-a em um lançamento real. date deve ser YYYY-MM-DD (400 `validation_error` caso contrário). Requer o escopo de escrita. Retorna 201 com o id do lançamento criado; se a ocorrência já havia sido materializada, retorna 200 com deduped:true e o id existente. 404 (`not_found`) se a regra não existir."}}, "/v1/installment-series": {"get": {"summary": "Listar parcelamentos", "tags": ["installment-series"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/InstallmentSeries"}}, "next_cursor": {"type": ["string", "null"], "description": "Sempre null (endpoint não paginado)."}, "has_more": {"type": "boolean", "description": "Sempre false (endpoint não paginado)."}}, "required": ["data", "next_cursor", "has_more"]}, "example": {"data": [{"id": "e0a2c4e6-8b1d-4f3a-9c5e-7d9f1b3a5c7e", "account_id": "3b1e8c74-2f90-4a6d-8c2b-1d9e7f4a6c30", "type": "DEBIT", "description": "Notebook Dell - 10x", "amount": 450, "total": 10, "paid": 3, "remaining": 7, "projected_positions": 6, "is_complete": false, "is_stale": false, "is_hidden": false, "is_open_finance": true}], "next_cursor": null, "has_more": false}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_installment_series", "description": "Lista as séries de parcelamento do usuário, agrupadas a partir das parcelas persistidas (mesmo núcleo da visão unificada), ordenadas pela parcela mais recente. Somente leitura. A resposta traz os campos de paginação por convenção, mas não é paginada: `next_cursor` é sempre null e `has_more` sempre false."}}, "/v1/cards/{id}/bills": {"get": {"summary": "Listar faturas do cartão", "tags": ["cards"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CardBills"}, "example": {"card_id": "459af7c0-c917-4a18-9b3f-c6b4739b7a08", "bills": [{"cycle_start_date": "2026-06-04", "close_date": "2026-07-03", "due_date": "2026-07-10", "amount": 2431.88, "amount_is_estimate": false, "status": "paga", "projected_bill_id": null, "settled_payment_ids": ["txn_a1b2c3d4"]}, {"cycle_start_date": "2026-07-04", "close_date": "2026-08-03", "due_date": "2026-08-10", "amount": 1167.29, "amount_is_estimate": false, "status": "fechada", "projected_bill_id": "mocked-bill:6307ee15-f5c2-4e11-aeb3-d728d8a99ec4:1754179200000", "settled_payment_ids": []}, {"cycle_start_date": "2026-08-04", "close_date": "2026-09-03", "due_date": "2026-09-10", "amount": 842.15, "amount_is_estimate": true, "status": "aberta", "projected_bill_id": "mocked-bill:a12f1e74-b9d2-4e2e-922b-a1f4344db6fe:1756857600000", "settled_payment_ids": []}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "from", "in": "query", "required": true, "description": "Início da janela (YYYY-MM-DD).", "schema": {"description": "Início da janela (YYYY-MM-DD).", "type": "string"}}, {"name": "to", "in": "query", "required": true, "description": "Fim da janela (YYYY-MM-DD); máx. 366 dias.", "schema": {"description": "Fim da janela (YYYY-MM-DD); máx. 366 dias.", "type": "string"}}], "operationId": "get_v1_cards_id_bills", "description": "Lista as faturas por ciclo de um cartão de crédito dentro da janela informada em `from`/`to` (YYYY-MM-DD; janela máxima de 366 dias). Cada fatura traz datas de início de ciclo, fechamento e vencimento, valor, situação (aberta/fechada/vencida/paga) e indicadores de estimativa. Responde 400 quando a conta não é cartão de crédito e 404 quando não existe."}}, "/v1/cards/{id}/used-limit": {"get": {"summary": "Consultar limite usado do cartão", "tags": ["cards"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CardUsedLimit"}, "example": {"card_id": "459af7c0-c917-4a18-9b3f-c6b4739b7a08", "used_limit": 3599.17, "limit": 12000, "available": 8400.83}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}], "operationId": "get_v1_cards_id_used_limit", "description": "Retorna o limite utilizado, o limite total e o disponível de um cartão de crédito (valores com 2 casas decimais). Responde 400 quando a conta não é cartão de crédito e 404 quando não existe."}}, "/v1/reports/summary": {"get": {"summary": "Resumo mensal", "tags": ["reports"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"month": {"type": "string", "description": "Mês do relatório (YYYY-MM)."}, "basis": {"type": "string", "enum": ["consolidated", "cash"]}, "receitas": {"type": "number"}, "despesas": {"type": "number"}, "resultado": {"type": "number"}}, "required": ["month", "basis", "receitas", "despesas", "resultado"]}, "example": {"month": "2026-08", "basis": "consolidated", "receitas": 8200, "despesas": 6543.29, "resultado": 1656.71}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "month", "in": "query", "required": false, "description": "YYYY-MM (padrão: mês atual BRT).", "schema": {"description": "YYYY-MM (padrão: mês atual BRT).", "type": "string"}}, {"name": "basis", "in": "query", "required": false, "description": "consolidated (padrão: compras de cartão por categoria) ou cash (só movimentos bancários).", "schema": {"description": "consolidated (padrão: compras de cartão por categoria) ou cash (só movimentos bancários).", "type": "string"}}], "operationId": "get_v1_reports_summary", "description": "Totais do mês (receitas, despesas e resultado) pela doutrina de relatórios (linhas visíveis do extrato, política de status contável, sem transferências). Parâmetro `month` (YYYY-MM, padrão mês atual BRT) e `basis` (consolidated=compras de cartão por categoria, cash=só movimentos bancários). 400 se `month` for inválido."}}, "/v1/reports/breakdown": {"get": {"summary": "Detalhamento por categoria, tag ou conta", "tags": ["reports"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"from": {"type": "string", "description": "Início da janela (YYYY-MM-DD)."}, "to": {"type": "string", "description": "Fim da janela (YYYY-MM-DD)."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "basis": {"type": "string", "enum": ["consolidated", "cash"]}, "group_by": {"type": "string", "enum": ["category", "tag", "account"]}, "total": {"type": "number"}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/ReportBreakdownItem"}}}, "required": ["from", "to", "type", "basis", "group_by", "total", "items"]}, "example": {"from": "2026-08-01", "to": "2026-08-31", "type": "DEBIT", "basis": "consolidated", "group_by": "category", "total": 6543.29, "items": [{"id": "32a4c6fa-a026-4db8-9da8-c99b7d131ae4", "title": "Alimentação", "amount": 2180.44, "color": "#F59E0B"}, {"id": "2f405142-7132-421c-90ca-5d55a527bc2a", "title": "Transporte", "amount": 1320.1, "color": "#3B82F6"}, {"id": null, "title": "Sem categoria", "amount": 90.75, "color": "#888888"}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "from", "in": "query", "required": true, "description": "YYYY-MM-DD", "schema": {"description": "YYYY-MM-DD", "type": "string"}}, {"name": "to", "in": "query", "required": true, "description": "YYYY-MM-DD (máx. 366 dias)", "schema": {"description": "YYYY-MM-DD (máx. 366 dias)", "type": "string"}}, {"name": "type", "in": "query", "required": false, "description": "`DEBIT` (padrão) ou `CREDIT`.", "schema": {"description": "`DEBIT` (padrão) ou `CREDIT`.", "type": "string"}}, {"name": "basis", "in": "query", "required": false, "description": "consolidated (padrão: compras de cartão por categoria) ou cash (só movimentos bancários).", "schema": {"description": "consolidated (padrão: compras de cartão por categoria) ou cash (só movimentos bancários).", "type": "string"}}, {"name": "group_by", "in": "query", "required": false, "description": "category (padrão), tag ou account.", "schema": {"description": "category (padrão), tag ou account.", "type": "string"}}], "operationId": "get_v1_reports_breakdown", "description": "Detalha o total de despesas (`type=DEBIT`, padrão) ou receitas (`type=CREDIT`) da janela `from`/`to` (YYYY-MM-DD, máx. 366 dias), agrupado por `group_by` (category, tag ou account). `basis` controla consolidado x caixa. Retorna o total e as fatias ordenadas por valor decrescente."}}, "/v1/reports/series": {"get": {"summary": "Série mensal de gastos", "tags": ["reports"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"months": {"type": "integer", "description": "Número de meses efetivamente considerados (2–12)."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "total": {"type": "number", "description": "Soma de todos os buckets."}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/ReportSeriesItem"}}}, "required": ["months", "type", "total", "items"]}, "example": {"months": 6, "type": "DEBIT", "total": 38210.55, "items": [{"month": "2026-03", "label": "mar", "total": 6120}, {"month": "2026-04", "label": "abr", "total": 6540.31}, {"month": "2026-05", "label": "mai", "total": 5980.9}, {"month": "2026-06", "label": "jun", "total": 6810.05}, {"month": "2026-07", "label": "jul", "total": 6216}, {"month": "2026-08", "label": "ago", "total": 6543.29}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "months", "in": "query", "required": false, "description": "2–12 (padrão 6).", "schema": {"description": "2–12 (padrão 6).", "type": "string"}}, {"name": "type", "in": "query", "required": false, "description": "`DEBIT` (padrão) ou `CREDIT`.", "schema": {"description": "`DEBIT` (padrão) ou `CREDIT`.", "type": "string"}}, {"name": "category_id", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "tag_id", "in": "query", "required": false, "schema": {"type": "string"}}], "operationId": "get_v1_reports_series", "description": "Série dos últimos N meses (`months`, 2–12, padrão 6; mês atual parcial incluído) do total de despesas (`type=DEBIT`, padrão) ou receitas (`type=CREDIT`), opcionalmente filtrada por `category_id` ou `tag_id`. Retorna o total do período e um bucket por mês."}}, "/v1/reports/predicted-balance": {"get": {"summary": "Saldo previsto", "tags": ["reports"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"month": {"type": "string", "description": "Mês projetado (YYYY-MM)."}, "account_id": {"type": "string", "description": "Presente apenas quando a projeção foi restrita a uma conta."}, "base": {"type": "number", "description": "Saldo base atual (total ou da conta)."}, "expected_in": {"type": "number", "description": "Entradas esperadas no período."}, "committed_out": {"type": "object", "properties": {"bills": {"type": "number"}, "installments": {"type": "number"}, "subscriptions": {"type": "number"}, "scheduled": {"type": "number"}}, "required": ["bills", "installments", "subscriptions", "scheduled"]}, "result": {"type": "number", "description": "Saldo previsto ao fim do período."}, "explain": {"type": "array", "items": {"type": "string"}, "description": "Linhas de racional legíveis do cálculo."}}, "required": ["month", "base", "expected_in", "committed_out", "result", "explain"]}, "example": {"month": "2026-08", "base": 4210.55, "expected_in": 8200, "committed_out": {"bills": 3120.44, "installments": 740, "subscriptions": 129.7, "scheduled": 500}, "result": 7920.41, "explain": ["Saldo atual: R$ 4.210,55", "Entradas esperadas até 31 ago: R$ 8.200,00", "Faturas de cartão: -R$ 3.120,44", "Parcelas: -R$ 740,00", "Assinaturas: -R$ 129,70", "Agendados: -R$ 500,00", "Saldo previsto: R$ 7.920,41"]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "month", "in": "query", "required": false, "description": "YYYY-MM (padrão: mês atual BRT).", "schema": {"description": "YYYY-MM (padrão: mês atual BRT).", "type": "string"}}, {"name": "account_id", "in": "query", "required": false, "description": "Restringe a uma conta bancária.", "schema": {"description": "Restringe a uma conta bancária.", "type": "string"}}], "operationId": "get_v1_reports_predicted_balance", "description": "Saldo previsto ancorado no saldo atual para o mês (`month`, YYYY-MM, padrão mês atual BRT): base + entradas esperadas − compromissos (faturas, parcelas, assinaturas, agendados). `account_id` opcional restringe a uma conta bancária (400 se a conta não for bancária, 404 se não existir). `explain` traz as linhas de racional."}}, "/v1/reports/affordability": {"get": {"summary": "Projeção de capacidade de compra", "tags": ["reports"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"type": "object", "properties": {"has_data": {"type": "boolean"}, "horizon_days": {"type": "number", "description": "Dias cobertos pela projeção (presente quando `has_data`=true)."}, "target_date": {"type": ["string", "null"], "description": "Data-alvo ISO efetiva da projeção, ou null."}, "verdict": {"type": ["string", "null"], "enum": ["yes", "tight", "no", null], "description": "Veredito da compra: yes/tight/no; null quando não há compra hipotética."}, "current_balance": {"type": "number"}, "committed_outflows": {"type": "number"}, "expected_inflows": {"type": "number"}, "income_source": {"type": "string", "enum": ["recurring", "detected", "declared", "none"], "description": "Base de renda que alimentou a projeção."}, "declared_monthly_income": {"type": ["number", "null"], "description": "Renda declarada (só quando `income_source`=declared)."}, "detected_monthly_income": {"type": ["number", "null"], "description": "Renda inferida do histórico (só quando `income_source`=detected)."}, "projected_balance": {"type": "number", "description": "`current_balance` − `committed_outflows` + `expected_inflows`."}, "projected_low_point": {"type": "number", "description": "Menor saldo projetado no horizonte."}, "projected_low_point_date": {"type": ["string", "null"]}, "projection": {"type": ["array", "null"], "items": {"$ref": "#/components/schemas/AffordabilityProjectionPoint"}, "description": "Série amostrada do saldo projetado; null/vazia sem movimento."}, "hypothetical_amount": {"type": ["number", "null"]}, "installments": {"type": ["number", "null"]}, "monthly_parcel": {"type": ["number", "null"]}, "hypothetical_cost_in_horizon": {"type": ["number", "null"]}, "remaining_after": {"type": ["number", "null"], "description": "`projected_balance` − custo da compra no horizonte."}, "low_point_after": {"type": ["number", "null"]}, "low_point_after_date": {"type": ["string", "null"]}, "projection_with_purchase": {"type": ["array", "null"], "items": {"$ref": "#/components/schemas/AffordabilityProjectionPoint"}, "description": "Série de projeção considerando a compra hipotética."}}, "required": ["has_data"]}, "example": {"has_data": true, "horizon_days": 30, "target_date": null, "verdict": "tight", "current_balance": 4210.55, "committed_outflows": 4490.14, "expected_inflows": 8200, "income_source": "detected", "declared_monthly_income": null, "detected_monthly_income": 8200, "projected_balance": 7920.41, "projected_low_point": 320.11, "projected_low_point_date": "2026-08-27T00:00:00.000Z", "projection": [{"dateAt": "2026-08-24T00:00:00.000Z", "balance": 4210.55}, {"dateAt": "2026-08-27T00:00:00.000Z", "balance": 320.11}, {"dateAt": "2026-09-05T00:00:00.000Z", "balance": 7920.41}], "hypothetical_amount": 3000, "installments": 6, "monthly_parcel": 500, "hypothetical_cost_in_horizon": 500, "remaining_after": 7420.41, "low_point_after": -179.89, "low_point_after_date": "2026-08-27T00:00:00.000Z", "projection_with_purchase": [{"dateAt": "2026-08-24T00:00:00.000Z", "balance": 3710.55}, {"dateAt": "2026-08-27T00:00:00.000Z", "balance": -179.89}, {"dateAt": "2026-09-05T00:00:00.000Z", "balance": 7420.41}]}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "400": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "parameters": [{"name": "amount", "in": "query", "required": false, "description": "Valor da compra hipotética.", "schema": {"description": "Valor da compra hipotética.", "type": "string"}}, {"name": "installments", "in": "query", "required": false, "description": "Nº de parcelas mensais.", "schema": {"description": "Nº de parcelas mensais.", "type": "string"}}, {"name": "horizon_days", "in": "query", "required": false, "description": "Janela de projeção em dias.", "schema": {"description": "Janela de projeção em dias.", "type": "string"}}, {"name": "target_date", "in": "query", "required": false, "description": "Projeta até esta data (YYYY-MM-DD).", "schema": {"description": "Projeta até esta data (YYYY-MM-DD).", "type": "string"}}], "operationId": "get_v1_reports_affordability", "description": "Projeção honesta de saldo de curto prazo e veredito de compra hipotética. Parâmetros opcionais: `amount` (valor), `installments` (nº de parcelas), `horizon_days` (janela) e `target_date` (YYYY-MM-DD). Sem dados suficientes retorna apenas `{has_data:false}`; caso contrário, saldo projetado, ponto mais baixo, renda considerada e séries de projeção (com e sem a compra)."}}, "/v1/overview": {"get": {"summary": "Obter visão geral financeira", "tags": ["overview"], "security": [{"bearerAuth": []}], "responses": {"200": {"description": "Sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Overview"}, "example": {"bank_balance": 12430.55, "card_debt": 3820.14, "net_worth": 8610.41, "next_bills": [{"projected_bill_id": "mocked-bill:b03b9565-8adb-452c-9504-10fc38c4a05c:1725148800000", "card_account_id": "01d988ff-252f-4571-abad-79e3ba56b583", "description": "Fatura Nubank", "amount": 1842.9, "due_date": "2026-09-05", "amount_is_estimate": true}, {"projected_bill_id": "mocked-bill:654d9941-f276-4cdc-81da-5f6d9f788636:1725667200000", "card_account_id": "aabeaa80-96d2-4d33-808d-a4c55a73a901", "description": "Fatura Itaú", "amount": 977.24, "due_date": "2026-09-12", "amount_is_estimate": false}], "month": {"receitas": 8500, "despesas": 5233.71, "resultado": 3266.29}, "saldo_previsto": {"base": 12430.55, "expected_in": 0, "committed_out": {"bills": 2820.14, "installments": 430.5, "subscriptions": 89.9, "scheduled": 0}, "result": 9090.01, "explain": ["Saldo atual: R$ 12.430,55", "Faturas até 31 ago: -R$ 2.820,14", "Parcelas até 31 ago: -R$ 430,50", "Assinaturas até 31 ago: -R$ 89,90", "Saldo previsto em 31 ago: R$ 9.090,01"]}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/ServerError"}}, "operationId": "get_v1_overview", "description": "Snapshot de uma chamada: saldo bancário, dívida de cartão em aberto, patrimônio líquido, as faturas projetadas dos próximos 30 dias, o resultado do mês corrente (BRT) e o saldo previsto ancorado no saldo atual. É o gêmeo REST da ferramenta MCP `visao_geral`."}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "dz_live_...", "description": "Chave de API no cabeçalho Authorization: Bearer dz_live_..."}}, "schemas": {"Notification": {"type": "object", "description": "Notificação in-app do usuário (avisos de fatura, sincronização, metas, etc.).", "properties": {"id": {"type": "string", "description": "Identificador da notificação."}, "type": {"type": ["string", "null"], "description": "Tipo/categoria da notificação (ex.: 'fatura', 'sync'); null quando não classificada."}, "title": {"type": "string", "description": "Título da notificação."}, "message": {"type": "string", "description": "Corpo/texto da notificação."}, "unread": {"type": "boolean", "description": "true se ainda não foi lida."}, "app_link": {"type": ["string", "null"], "description": "Deep link para abrir no app; null quando não há destino."}, "web_link": {"type": ["string", "null"], "description": "Link para abrir na web; null quando não há destino."}, "created_at": {"type": "string", "format": "date-time", "description": "Data de criação (ISO 8601)."}}, "required": ["id", "type", "title", "message", "unread", "app_link", "web_link", "created_at"]}, "OpenFinanceConnectionAccount": {"type": "object", "description": "Conta vinculada a uma conexão Open Finance (Pluggy item).", "properties": {"id": {"type": "string", "description": "Identificador da conta no Dinzo."}, "title": {"type": "string", "description": "Nome da conta."}, "type": {"type": "string", "description": "Tipo da conta (ex.: 'checking', 'credit')."}}, "required": ["id", "title", "type"]}, "OpenFinanceConnection": {"type": "object", "description": "Saúde mascarada de uma conexão Open Finance (Pluggy item). Exclui deliberadamente PII verificada pelo banco (nome completo/documento) e internos da Pluggy além do id do item.", "properties": {"id": {"type": "string", "description": "Identificador da conexão (Pluggy item id)."}, "connector_name": {"type": ["string", "null"], "description": "Nome do conector/banco (denormalizado das contas); null quando nenhuma conta traz o nome."}, "status": {"type": ["string", "null"], "description": "Status do item na Pluggy (ex.: '`UPDATED`', '`LOGIN_ERROR`'); null quando desconhecido."}, "execution_status": {"type": ["string", "null"], "description": "Status da última execução de sincronização; null quando desconhecido."}, "error_code": {"type": ["string", "null"], "description": "Código de erro da última sincronização, quando houver; null caso contrário."}, "last_synced_at": {"type": ["string", "null"], "format": "date-time", "description": "Data da última sincronização bem-sucedida (ISO 8601); null quando nunca sincronizou."}, "next_auto_sync_at": {"type": ["string", "null"], "format": "date-time", "description": "Data da próxima sincronização automática agendada (ISO 8601); null quando não agendada."}, "consent_expires_at": {"type": ["string", "null"], "format": "date-time", "description": "Data de expiração do consentimento Open Finance (ISO 8601); null quando não aplicável."}, "products": {"type": "array", "items": {"type": "string"}, "description": "Produtos Pluggy habilitados no item (ex.: '`ACCOUNTS`', '`CREDIT_CARDS`', '`TRANSACTIONS`')."}, "created_at": {"type": "string", "format": "date-time", "description": "Data de criação da conexão (ISO 8601)."}, "accounts": {"type": "array", "items": {"$ref": "#/components/schemas/OpenFinanceConnectionAccount"}, "description": "Contas do usuário respaldadas por esta conexão."}}, "required": ["id", "connector_name", "status", "execution_status", "error_code", "last_synced_at", "next_auto_sync_at", "consent_expires_at", "products", "created_at", "accounts"]}, "Icon": {"type": "object", "description": "Ícone do catálogo do Dinzo, usado para contas, categorias e cartões.", "properties": {"id": {"type": "string", "description": "Identificador do ícone."}, "title": {"type": "string", "description": "Nome/rótulo do ícone."}, "icon_name": {"type": ["string", "null"], "description": "Nome simbólico do ícone (glyph), quando houver; null caso contrário."}, "image_url": {"type": "string", "description": "URL da imagem do ícone."}, "type": {"type": "string", "enum": ["ACCOUNT", "CATEGORY", "CARD"], "description": "Categoria de uso do ícone: `ACCOUNT` (conta), `CATEGORY` (categoria) ou `CARD` (cartão)."}}, "required": ["id", "title", "icon_name", "image_url", "type"]}, "MeProfile": {"type": "object", "description": "Perfil financeiro editável do usuário autenticado. É o corpo devolvido por `PATCH` /v1/me e o núcleo de `GET` /v1/me.", "properties": {"id": {"type": "string", "description": "ID do usuário."}, "name": {"type": ["string", "null"], "description": "Nome do usuário."}, "wage": {"type": ["number", "null"], "description": "Renda mensal declarada, em BRL."}, "monthly_living_cost": {"type": ["number", "null"], "description": "Custo de vida mensal declarado, em BRL."}, "has_spouse": {"type": ["boolean", "null"], "description": "Se o usuário declarou ter cônjuge."}, "has_children": {"type": ["boolean", "null"], "description": "Se o usuário declarou ter filhos."}, "is_entrepreneur": {"type": ["boolean", "null"], "description": "Se o usuário declarou ser empreendedor."}}, "required": ["id", "name", "wage", "monthly_living_cost", "has_spouse", "has_children", "is_entrepreneur"]}, "Me": {"type": "object", "description": "Perfil do usuário autenticado acrescido do plano vigente, dos escopos do token e dos limites de rate limit da API.", "properties": {"id": {"type": "string", "description": "ID do usuário."}, "name": {"type": ["string", "null"], "description": "Nome do usuário."}, "wage": {"type": ["number", "null"], "description": "Renda mensal declarada, em BRL."}, "monthly_living_cost": {"type": ["number", "null"], "description": "Custo de vida mensal declarado, em BRL."}, "has_spouse": {"type": ["boolean", "null"], "description": "Se o usuário declarou ter cônjuge."}, "has_children": {"type": ["boolean", "null"], "description": "Se o usuário declarou ter filhos."}, "is_entrepreneur": {"type": ["boolean", "null"], "description": "Se o usuário declarou ser empreendedor."}, "plan": {"type": "object", "description": "Direitos de acesso vigentes do usuário.", "properties": {"premium_access": {"type": "boolean", "description": "Acesso ao Premium."}, "ultra_access": {"type": "boolean", "description": "Acesso ao Ultra."}, "frequency": {"type": ["string", "null"], "enum": ["MONTHLY", "QUARTERLY", "ANNUALLY", null], "description": "Periodicidade da assinatura ativa. Pode vir null mesmo com acesso ativo (ex.: acesso via loja/cache, quando a frequência não é resolvida na hora)."}}, "required": ["premium_access", "ultra_access", "frequency"]}, "scopes": {"type": "array", "items": {"type": "string"}, "description": "Escopos concedidos ao token portador atual (ex.: [\"read\",\"write\"])."}, "limits": {"type": "object", "description": "Limites de uso aplicados às credenciais da API.", "properties": {"rate": {"type": "object", "properties": {"minute": {"type": "object", "properties": {"limit": {"type": "integer", "description": "Máximo de requisições na janela."}, "window_sec": {"type": "integer", "description": "Tamanho da janela, em segundos."}}, "required": ["limit", "window_sec"]}, "day": {"type": "object", "properties": {"limit": {"type": "integer", "description": "Máximo de requisições na janela."}, "window_sec": {"type": "integer", "description": "Tamanho da janela, em segundos."}}, "required": ["limit", "window_sec"]}}, "required": ["minute", "day"]}}, "required": ["rate"]}}, "required": ["id", "name", "wage", "monthly_living_cost", "has_spouse", "has_children", "is_entrepreneur", "plan", "scopes", "limits"]}, "OverviewNextBill": {"type": "object", "description": "Fatura de cartão projetada que vence dentro dos próximos 30 dias.", "properties": {"projected_bill_id": {"type": "string", "description": "ID sintético da fatura projetada (não é uma transação persistida)."}, "card_account_id": {"type": "string", "description": "ID da conta de cartão de crédito à qual a fatura pertence."}, "description": {"type": "string", "description": "Descrição da fatura."}, "amount": {"type": "number", "description": "Valor da fatura, em BRL (positivo, 2 casas)."}, "due_date": {"type": "string", "description": "Data de vencimento no formato YYYY-MM-DD (dia BRT)."}, "amount_is_estimate": {"type": "boolean", "description": "true quando é um ciclo de cartão Open Finance ainda sem fatura da Pluggy (valor estimado); cartões manuais são exatos por definição."}}, "required": ["projected_bill_id", "card_account_id", "description", "amount", "due_date", "amount_is_estimate"]}, "MonthSummary": {"type": "object", "description": "Totais do mês corrente (BRT) segundo a doutrina de relatório: linhas visíveis do razão, política de status contável, sem transferências, incluindo compras de cartão.", "properties": {"receitas": {"type": "number", "description": "Total de receitas do mês, em BRL."}, "despesas": {"type": "number", "description": "Total de despesas do mês, em BRL."}, "resultado": {"type": "number", "description": "Resultado (receitas menos despesas), em BRL."}}, "required": ["receitas", "despesas", "resultado"]}, "SaldoPrevisto": {"type": "object", "description": "Saldo previsto ancorado no saldo atual para a janela do mês: saldo base mais entradas esperadas menos compromissos por categoria.", "properties": {"base": {"type": "number", "description": "Saldo base (saldo total das contas hoje), em BRL."}, "expected_in": {"type": "number", "description": "Entradas esperadas até o fim do mês, em BRL."}, "committed_out": {"type": "object", "description": "Saídas comprometidas até o fim do mês, por categoria, em BRL.", "properties": {"bills": {"type": "number", "description": "Faturas de cartão."}, "installments": {"type": "number", "description": "Parcelas."}, "subscriptions": {"type": "number", "description": "Assinaturas detectadas."}, "scheduled": {"type": "number", "description": "Lançamentos agendados/recorrentes."}}, "required": ["bills", "installments", "subscriptions", "scheduled"]}, "result": {"type": "number", "description": "Saldo previsto ao fim da janela, em BRL."}, "explain": {"type": "array", "items": {"type": "string"}, "description": "Linhas legíveis explicando a composição do cálculo."}}, "required": ["base", "expected_in", "committed_out", "result", "explain"]}, "Overview": {"type": "object", "description": "Snapshot de uma chamada: saldo bancário, dívida de cartão em aberto, patrimônio, próximas faturas (30 dias), resultado do mês corrente e saldo previsto.", "properties": {"bank_balance": {"type": "number", "description": "Saldo total das contas bancárias, em BRL."}, "card_debt": {"type": "number", "description": "Total das faturas de cartão em aberto, em BRL."}, "net_worth": {"type": "number", "description": "Patrimônio líquido (saldo bancário menos dívida de cartão e demais), em BRL."}, "next_bills": {"type": "array", "items": {"$ref": "#/components/schemas/OverviewNextBill"}, "description": "Faturas projetadas nos próximos 30 dias, ordenadas por data de vencimento crescente."}, "month": {"$ref": "#/components/schemas/MonthSummary"}, "saldo_previsto": {"$ref": "#/components/schemas/SaldoPrevisto"}}, "required": ["bank_balance", "card_debt", "net_worth", "next_bills", "month", "saldo_previsto"]}, "Category": {"type": "object", "description": "Categoria de transação (própria do usuário ou pública do sistema). Formam uma árvore plana via `parent_id`.", "required": ["id", "title", "parent_id", "icon_id", "color_hex", "system", "archived", "created_at"], "properties": {"id": {"type": "string", "description": "UUID da categoria."}, "title": {"type": "string", "description": "Nome da categoria."}, "parent_id": {"type": ["string", "null"], "description": "UUID da categoria pai, ou null para categoria de topo."}, "icon_id": {"type": ["string", "null"], "description": "UUID do ícone associado, ou null."}, "color_hex": {"type": ["string", "null"], "description": "Cor do ícone em hexadecimal (ex.: \"#`FF5722`\"), ou null."}, "system": {"type": "boolean", "description": "true para categoria pública do sistema (sem dono), false para categoria do usuário."}, "archived": {"type": "boolean", "description": "true se a categoria está arquivada para este usuário."}, "created_at": {"type": "string", "format": "date-time", "description": "Instante de criação em ISO 8601."}}}, "Tag": {"type": "object", "description": "Etiqueta (tag) do usuário para marcar transações.", "required": ["id", "title", "color_hex", "created_at"], "properties": {"id": {"type": "string", "description": "UUID da tag."}, "title": {"type": "string", "description": "Nome da tag."}, "color_hex": {"type": "string", "description": "Cor em hexadecimal (ex.: \"#3B82F6\")."}, "created_at": {"type": "string", "format": "date-time", "description": "Instante de criação em ISO 8601."}}}, "Target": {"type": "object", "description": "Meta financeira. `current_amount` reflete o progresso ao vivo (consumo de limite ou soma de categoria acompanhada) quando aplicável; caso contrário o valor armazenado.", "required": ["id", "type", "title", "amount", "current_amount", "track_category", "category_id", "account_id", "start_date", "end_date", "created_at"], "properties": {"id": {"type": "string", "description": "UUID da meta."}, "type": {"type": "string", "enum": ["INCOMING", "OUTGOING"], "description": "`INCOMING` para meta de guardar/receber, `OUTGOING` para meta de gasto/limite."}, "title": {"type": "string", "description": "Título da meta."}, "amount": {"type": "number", "description": "Valor-alvo da meta, em reais com 2 casas decimais."}, "current_amount": {"type": "number", "description": "Progresso atual em reais com 2 casas decimais."}, "track_category": {"type": "boolean", "description": "true quando o progresso é calculado somando os lançamentos de uma categoria."}, "category_id": {"type": ["string", "null"], "description": "UUID da categoria acompanhada, ou null."}, "account_id": {"type": ["string", "null"], "description": "UUID da conta vinculada, ou null."}, "start_date": {"type": "string", "format": "date", "description": "Data de início \"YYYY-MM-DD\"."}, "end_date": {"type": ["string", "null"], "description": "Data de término \"YYYY-MM-DD\", ou null se sem prazo."}, "created_at": {"type": "string", "format": "date-time", "description": "Instante de criação em ISO 8601."}}}, "AccountCredit": {"type": ["object", "null"], "description": "Configuração de cartão de crédito. Presente (objeto) apenas quando `type` = `CREDIT`; caso contrário, null.", "required": ["close_day", "due_day", "due_day_of_month", "cycle_auto", "limit"], "properties": {"close_day": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Dia do mês em que a fatura fecha."}, "due_day": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Dia de vencimento derivado (`close_day` + prazo de dias configurado)."}, "due_day_of_month": {"type": ["integer", "null"], "minimum": 1, "maximum": 31, "description": "Dia fixo de vencimento no mês, quando definido explicitamente; null se derivado apenas do fechamento."}, "cycle_auto": {"type": "boolean", "description": "Se o ciclo de fatura é ajustado automaticamente (Open Finance)."}, "limit": {"type": ["number", "null"], "description": "Limite total do cartão (2 casas decimais); null se não informado."}}}, "Account": {"type": "object", "description": "Conta bancária ou cartão de crédito do usuário. Espelha o AccountDto (allowlist pública): dinheiro com 2 casas decimais, `created_at` como instante ISO.", "required": ["id", "type", "sub_type", "title", "archived", "exclude_from_totals", "currency", "balance", "credit", "pay_bill_from_account_id", "icon_id", "card_icon_id", "open_finance", "card_holders", "created_at"], "properties": {"id": {"type": "string", "description": "Identificador da conta."}, "type": {"type": "string", "enum": ["BANK", "CREDIT"], "description": "Tipo da conta: conta bancária ou cartão de crédito."}, "sub_type": {"type": ["string", "null"], "enum": ["SAVINGS_ACCOUNT", "CHECKING_ACCOUNT", "CREDIT_CARD", null], "description": "Subtipo da conta; null quando não classificado."}, "title": {"type": "string", "description": "Nome exibido da conta."}, "archived": {"type": "boolean", "description": "Se a conta está arquivada."}, "exclude_from_totals": {"type": "boolean", "description": "Se a conta é excluída dos totais consolidados."}, "currency": {"type": "string", "description": "Código ISO da moeda (ex.: BRL)."}, "balance": {"type": ["number", "null"], "description": "Saldo calculado (2 casas decimais). Null para contas arquivadas ou quando o saldo não é computado pelo endpoint."}, "credit": {"$ref": "#/components/schemas/AccountCredit"}, "pay_bill_from_account_id": {"type": ["string", "null"], "description": "Id da conta usada para pagar a fatura deste cartão; null se não configurada."}, "icon_id": {"type": ["string", "null"], "description": "Id do ícone da conta; null se não definido."}, "card_icon_id": {"type": ["string", "null"], "description": "Id do ícone específico do cartão; null se não definido."}, "open_finance": {"type": "object", "description": "Estado de conexão Open Finance da conta.", "required": ["connected", "connector_name"], "properties": {"connected": {"type": "boolean", "description": "Se a conta é sincronizada via Open Finance (possui item Pluggy)."}, "connector_name": {"type": ["string", "null"], "description": "Nome do conector/instituição; null se manual."}}}, "card_holders": {"type": ["object", "null"], "additionalProperties": {"type": "string"}, "description": "Mapa dos últimos 4 dígitos do cartão para o nome do portador (o portador titular aparece como o sentinela \"me\"). Null quando ausente."}, "created_at": {"type": "string", "format": "date-time", "description": "Instante de criação da conta (ISO 8601)."}}}, "AccountCreated": {"description": "Conta recém-criada: todos os campos de Account mais o id da transação de saldo inicial gerada.", "allOf": [{"$ref": "#/components/schemas/Account"}, {"type": "object", "required": ["initial_balance_transaction_id"], "properties": {"initial_balance_transaction_id": {"type": ["string", "null"], "description": "Id da transação de saldo inicial criada junto com a conta; null se nenhum saldo inicial foi informado."}}}]}, "CardBill": {"type": "object", "description": "Fatura de um ciclo de cartão de crédito.", "required": ["cycle_start_date", "close_date", "due_date", "amount", "amount_is_estimate", "status", "projected_bill_id", "settled_payment_ids"], "properties": {"cycle_start_date": {"type": "string", "format": "date", "description": "Data de início do ciclo (YYYY-MM-DD)."}, "close_date": {"type": "string", "format": "date", "description": "Data de fechamento do ciclo/fatura (YYYY-MM-DD)."}, "due_date": {"type": "string", "format": "date", "description": "Data de vencimento da fatura (YYYY-MM-DD)."}, "amount": {"type": "number", "description": "Valor da fatura (2 casas decimais)."}, "amount_is_estimate": {"type": "boolean", "description": "True quando é um cartão Open Finance e ainda não há fatura oficial da instituição para o ciclo (valor estimado)."}, "status": {"type": "string", "enum": ["aberta", "fechada", "vencida", "paga"], "description": "Situação da fatura: aberta (ciclo não fechado), fechada (dentro do prazo de pagamento), vencida (passou do vencimento e não paga) ou paga."}, "projected_bill_id": {"type": ["string", "null"], "description": "Id da linha de fatura projetada na visão consolidada; null quando o ciclo não gerou projeção (fatura liquidada ou zerada)."}, "settled_payment_ids": {"type": "array", "items": {"type": "string"}, "description": "Ids das transações de pagamento associadas à fatura, quando o casador de liquidação as encontrou."}}}, "CardBills": {"type": "object", "description": "Faturas de um cartão de crédito dentro da janela consultada.", "required": ["card_id", "bills"], "properties": {"card_id": {"type": "string", "description": "Id do cartão consultado."}, "bills": {"type": "array", "items": {"$ref": "#/components/schemas/CardBill"}, "description": "Faturas ordenadas por data de fechamento (ascendente)."}}}, "CardUsedLimit": {"type": "object", "description": "Limite utilizado, total e disponível de um cartão de crédito.", "required": ["card_id", "used_limit", "limit", "available"], "properties": {"card_id": {"type": "string", "description": "Id do cartão consultado."}, "used_limit": {"type": "number", "description": "Limite atualmente utilizado (2 casas decimais)."}, "limit": {"type": ["number", "null"], "description": "Limite total do cartão (2 casas decimais); null se não informado."}, "available": {"type": ["number", "null"], "description": "Limite disponível (total menos utilizado); null se o limite total não estiver informado."}}}, "Investment": {"type": "object", "description": "Posição de investimento Open Finance ingerida via Pluggy. Valores monetários em BRL arredondados a 2 casas; `balance` é o saldo canônico da posição.", "properties": {"id": {"type": "string", "description": "ID da linha da posição (muda a cada sincronização — use `asset_key` para identidade estável)."}, "asset_key": {"type": "string", "description": "Identidade estável da posição (tipo + isin/code/name), persistente entre sincronizações."}, "name": {"type": "string"}, "type": {"type": "string", "description": "Tipo do ativo informado pela instituição (ex.: `FIXED_INCOME`, `MUTUAL_FUND`, `EQUITY`, `ETF`)."}, "sub_type": {"type": ["string", "null"]}, "balance": {"type": "number", "description": "Saldo atual da posição em BRL."}, "quantity": {"type": ["number", "null"]}, "value": {"type": ["number", "null"], "description": "Valor unitário/cotação informado, quando disponível."}, "code": {"type": ["string", "null"], "description": "Código de negociação (ex.: ticker B3)."}, "isin": {"type": ["string", "null"]}, "issuer": {"type": ["string", "null"]}, "currency": {"type": "string", "description": "Código da moeda (ex.: BRL)."}, "due_date": {"type": ["string", "null"], "description": "Data de vencimento (YYYY-MM-DD)."}, "purchase_date": {"type": ["string", "null"], "description": "Data de compra (YYYY-MM-DD)."}, "rate": {"type": ["number", "null"]}, "rate_type": {"type": ["string", "null"]}, "fixed_annual_rate": {"type": ["number", "null"]}, "last_twelve_months_rate": {"type": ["number", "null"]}, "indexer_additional_info": {"type": ["string", "null"]}, "tax_exempt": {"type": ["boolean", "null"]}, "status": {"type": ["string", "null"]}, "updated_at": {"type": ["string", "null"], "description": "Timestamp ISO 8601 da última sincronização da posição."}}, "required": ["id", "asset_key", "name", "type", "sub_type", "balance", "quantity", "value", "code", "isin", "issuer", "currency", "due_date", "purchase_date", "rate", "rate_type", "fixed_annual_rate", "last_twelve_months_rate", "indexer_additional_info", "tax_exempt", "status", "updated_at"]}, "InvestmentTransaction": {"type": "object", "description": "Movimento (aporte, resgate, provento etc.) de uma posição de investimento.", "properties": {"id": {"type": "string"}, "type": {"type": "string"}, "movement_type": {"type": ["string", "null"]}, "date": {"type": "string", "description": "Data de negociação (YYYY-MM-DD)."}, "quantity": {"type": ["number", "null"]}, "value": {"type": ["number", "null"]}, "amount": {"type": ["number", "null"]}, "net_amount": {"type": ["number", "null"]}, "description": {"type": ["string", "null"]}}, "required": ["id", "type", "movement_type", "date", "quantity", "value", "amount", "net_amount", "description"]}, "InvestmentSummaryHolding": {"type": "object", "description": "Posição individual no resumo agregado de investimentos.", "properties": {"name": {"type": "string"}, "type": {"type": "string"}, "balance": {"type": "number"}, "code": {"type": ["string", "null"]}, "issuer": {"type": ["string", "null"]}, "currency": {"type": "string"}}, "required": ["name", "type", "balance", "code", "issuer", "currency"]}, "InvestmentByTypeEntry": {"type": "object", "description": "Total investido agrupado por tipo de ativo.", "properties": {"type": {"type": "string"}, "total": {"type": "number"}}, "required": ["type", "total"]}, "AffordabilityProjectionPoint": {"type": "object", "description": "Ponto amostrado da projeção de saldo bancário.", "properties": {"dateAt": {"type": "string", "description": "Data ISO 8601 da amostra."}, "balance": {"type": "number", "description": "Saldo bancário projetado nessa data."}}, "required": ["dateAt", "balance"]}, "ReportBreakdownItem": {"type": "object", "description": "Fatia do detalhamento (por categoria, tag ou conta).", "properties": {"id": {"type": ["string", "null"], "description": "ID da categoria/tag/conta; null para itens sem categoria."}, "title": {"type": "string"}, "amount": {"type": "number"}, "color": {"type": "string", "description": "Cor hex (#RRGGBB). Presente em `group_by`=category e, quando a tag tem cor, em `group_by`=tag; ausente em `group_by`=account."}}, "required": ["id", "title", "amount"]}, "ReportSeriesItem": {"type": "object", "description": "Bucket mensal da série de gastos.", "properties": {"month": {"type": "string", "description": "Mês do bucket no formato YYYY-MM."}, "label": {"type": "string", "description": "Rótulo curto em pt-BR (ex.: \"fev\" ou \"fev/25\" ao cruzar ano)."}, "total": {"type": "number"}}, "required": ["month", "label", "total"]}, "TransactionTag": {"type": "object", "description": "Tag vinculada a um lançamento (subconjunto do TagDto para linhas de transação).", "required": ["id", "title", "color_hex"], "properties": {"id": {"type": "string"}, "title": {"type": "string"}, "color_hex": {"type": "string", "description": "Cor hex, ex. \"#`FF8A00`\"."}}}, "Subscription": {"type": "object", "description": "Assinatura recorrente detectada nos cartões do usuário (ou criada manualmente).", "properties": {"id": {"type": "string"}, "merchant_name": {"type": "string", "description": "Nome do estabelecimento/serviço."}, "amount": {"type": "number", "description": "Valor da cobrança, 2 casas decimais."}, "currency": {"type": "string", "description": "Código ISO da moeda, ex. \"BRL\"."}, "cadence": {"type": "string", "enum": ["WEEKLY", "MONTHLY", "YEARLY", "QUARTERLY", "SEMIANNUAL"], "description": "Periodicidade da cobrança."}, "charge_day": {"type": ["integer", "null"], "description": "Dia do mês da cobrança (1-31), ou null."}, "status": {"type": "string", "enum": ["DETECTED", "CONFIRMED", "REJECTED", "CANCELLED"], "description": "`DETECTED` é exclusivo do detector; clientes só definem `CONFIRMED`, `CANCELLED` ou `REJECTED`."}, "source": {"type": "string", "enum": ["AUTO", "MANUAL"], "description": "`AUTO` = detectada pelo job diário; `MANUAL` = criada pelo usuário."}, "account_id": {"type": ["string", "null"], "description": "Conta/cartão associado, ou null."}, "card_last_digits": {"type": ["string", "null"], "description": "Últimos dígitos do cartão da cobrança, ou null."}, "occurrences": {"type": "integer", "description": "Quantidade de cobranças observadas."}, "first_seen_at": {"type": "string", "format": "date-time", "description": "Instante ISO da primeira cobrança observada."}, "last_seen_at": {"type": "string", "format": "date-time", "description": "Instante ISO da cobrança mais recente."}, "created_at": {"type": "string", "format": "date-time"}}, "required": ["id", "merchant_name", "amount", "currency", "cadence", "charge_day", "status", "source", "account_id", "card_last_digits", "occurrences", "first_seen_at", "last_seen_at", "created_at"]}, "RecurringRule": {"type": "object", "description": "Regra de recorrência (transação recorrente) como recurso de primeira classe.", "properties": {"id": {"type": "string"}, "account_id": {"type": "string", "description": "Conta em que a recorrência é lançada."}, "bill_to_account_id": {"type": ["string", "null"], "description": "Cartão/conta de cobrança da fatura, ou null."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"], "description": "`DEBIT` = saída (despesa); `CREDIT` = entrada (receita)."}, "category_id": {"type": ["string", "null"]}, "recurrence_type": {"type": "string", "enum": ["DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "SEMIANNUALLY", "ANNUALLY"], "description": "Frequência-base da recorrência."}, "recurrence_interval": {"type": "integer", "description": "Multiplicador do período: `MONTHLY` + 3 = a cada 3 meses. Regras de parcelamento ficam sempre em 1."}, "is_installments": {"type": "boolean", "description": "true quando a regra representa um parcelamento."}, "parent_id": {"type": ["string", "null"], "description": "Versão anterior na cadeia de edições (scope future gera nova versão), ou null."}, "start_date": {"type": "string", "format": "date", "description": "Início da recorrência (YYYY-MM-DD)."}, "end_date": {"type": ["string", "null"], "format": "date", "description": "Fim da recorrência (YYYY-MM-DD), ou null se sem término."}, "description": {"type": "string"}, "amount": {"type": "number", "description": "Valor de cada ocorrência, 2 casas decimais, sempre positivo."}, "currency": {"type": "string", "description": "Código ISO da moeda, ex. \"BRL\"."}, "notes": {"type": ["string", "null"]}, "hide_from_results": {"type": "boolean", "description": "Quando true, as ocorrências não entram nos totais/relatórios."}, "tags": {"type": "array", "items": {"$ref": "#/components/schemas/TransactionTag"}}, "created_at": {"type": "string", "format": "date-time"}}, "required": ["id", "account_id", "bill_to_account_id", "type", "category_id", "recurrence_type", "recurrence_interval", "is_installments", "parent_id", "start_date", "end_date", "description", "amount", "currency", "notes", "hide_from_results", "tags", "created_at"]}, "RecurringOccurrence": {"type": "object", "description": "Ocorrência projetada de uma regra (sintetizada pelo projetor, sem linha no banco).", "properties": {"id": {"type": "string", "description": "Id sintético estável \"mocked-recurrence:<`rule_id`>:<ms>\", idêntico ao que os clientes geram para a mesma ocorrência."}, "rule_id": {"type": "string", "description": "Id da regra que gerou a ocorrência."}, "date": {"type": "string", "format": "date", "description": "Dia da ocorrência (YYYY-MM-DD)."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "description": {"type": "string"}, "amount": {"type": "number", "description": "Valor da ocorrência, 2 casas decimais, sempre positivo."}, "currency": {"type": "string"}, "category_id": {"type": ["string", "null"]}, "installment": {"type": ["object", "null"], "description": "Presente apenas em recorrências de parcelamento.", "properties": {"current": {"type": "integer"}, "total": {"type": "integer"}}, "required": ["current", "total"]}, "status": {"type": "string", "enum": ["PENDING", "POSTED"], "description": "Ocorrências futuras projetadas são `PENDING`."}}, "required": ["id", "rule_id", "date", "type", "description", "amount", "currency", "category_id", "installment", "status"]}, "RecurringException": {"type": "object", "description": "Ocorrência suprimida (exceção) de uma regra — não deve ser projetada naquele dia.", "properties": {"rule_id": {"type": "string"}, "date": {"type": "string", "format": "date", "description": "Dia suprimido (YYYY-MM-DD)."}}, "required": ["rule_id", "date"]}, "RecurrenceWindow": {"type": "object", "description": "Janela (semiaberta na omissão dos parâmetros) usada para projetar ocorrências.", "properties": {"from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}}, "required": ["from", "to"]}, "RecurrenceDeleteResult": {"type": "object", "description": "Resultado das operações que encerram/excluem uma regra (stop e `DELETE`).", "properties": {"success": {"type": "boolean"}, "scope": {"type": "string", "enum": ["future", "all"], "description": "Escopo aplicado: stop usa \"future\"; `DELETE` usa \"all\"."}, "mode": {"type": "string", "enum": ["single", "future", "all"], "description": "Modo interno do core de exclusão de recorrência."}, "rule_ids_touched": {"type": "array", "items": {"type": "string"}, "description": "Ids de todas as versões da cadeia afetadas."}, "transaction_ids_deleted": {"type": "array", "items": {"type": "string"}, "description": "Lançamentos vinculados que foram removidos (soft-delete)."}, "transaction_ids_unlinked": {"type": "array", "items": {"type": "string"}, "description": "Lançamentos `POSTED` preservados que foram desvinculados da regra (só ocorre em \"all\" com `preserve_posted`)."}, "markers_written": {"type": "integer", "description": "Quantidade de marcadores de supressão gravados (>0 apenas no modo single)."}}, "required": ["success", "scope", "mode", "rule_ids_touched", "transaction_ids_deleted", "transaction_ids_unlinked", "markers_written"]}, "InstallmentSeries": {"type": "object", "description": "Série de parcelamento (cluster sobre as parcelas persistidas). Somente leitura; a série não tem linha própria — o id é o da parcela mais recente.", "properties": {"id": {"type": "string", "description": "Handle da série = id do lançamento da parcela mais recente."}, "account_id": {"type": "string"}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "description": {"type": ["string", "null"], "description": "Descrição de exibição da parcela mais recente, ou null."}, "amount": {"type": "number", "description": "Valor de cada parcela, 2 casas decimais, sempre positivo."}, "total": {"type": "integer", "description": "Número total de parcelas da série."}, "paid": {"type": "integer", "description": "Maior número de parcela já efetivada (`POSTED`)."}, "remaining": {"type": "integer", "description": "Parcelas restantes (max(0, total - paid))."}, "projected_positions": {"type": "integer", "description": "Posições ainda sem parcela persistida (max(0, total - legs))."}, "is_complete": {"type": "boolean", "description": "true quando todas as parcelas já foram efetivadas."}, "is_stale": {"type": "boolean", "description": "true quando a série está defasada (sem sincronização recente do cartão)."}, "is_hidden": {"type": "boolean", "description": "true quando a série foi ocultada por tombstone de \"ocultar série\"."}, "is_open_finance": {"type": "boolean", "description": "true quando a série vem de conta Open Finance."}}, "required": ["id", "account_id", "type", "description", "amount", "total", "paid", "remaining", "projected_positions", "is_complete", "is_stale", "is_hidden", "is_open_finance"]}, "TransactionProjection": {"type": "object", "description": "Metadados de projeção presentes apenas em linhas projetadas (ids mocked-*). Null em linhas persistidas.", "required": ["kind", "rule_id", "occurrence_date", "source_transaction_id", "installment_number", "card_account_id", "cycle_end_date", "amount_is_estimate"], "properties": {"kind": {"type": "string", "enum": ["recurrence", "installment", "bill"], "description": "Tipo de projeção."}, "rule_id": {"type": ["string", "null"], "description": "Id da regra de recorrência (kind=recurrence)."}, "occurrence_date": {"type": ["string", "null"], "description": "Dia da ocorrência YYYY-MM-DD (kind=recurrence)."}, "source_transaction_id": {"type": ["string", "null"], "description": "Id da transação-origem da série (kind=installment)."}, "installment_number": {"type": ["integer", "null"], "description": "Número da parcela projetada (kind=installment)."}, "card_account_id": {"type": ["string", "null"], "description": "Id da conta do cartão (kind=bill)."}, "cycle_end_date": {"type": ["string", "null"], "description": "Dia de fechamento do ciclo YYYY-MM-DD (kind=bill)."}, "amount_is_estimate": {"type": "boolean", "description": "true quando a fatura é estimativa computada (cartão Open Finance sem fatura Pluggy ainda)."}}}, "Transaction": {"type": "object", "description": "Lançamento na visão canônica mesclada (linhas persistidas + projeções mocked-*). Dinheiro em 2 casas; dias calendário como YYYY-MM-DD; instantes como ISO. Somente os campos do allowlist saem da API.", "required": ["id", "projected", "projection", "date", "type", "status", "amount", "currency", "description", "notes", "account_id", "bill_to_account_id", "category_id", "tags", "recurrence_id", "recurrence_period_date", "installment", "transfer_group_id", "created_by_user", "source", "hide_from_results", "card_number", "holder", "holder_is_me", "original_description", "receipt_url", "open_finance"], "properties": {"id": {"type": "string", "description": "Id persistido (uuid) ou handle projetado (mocked-recurrence:/mocked-installment:/mocked-bill:...)."}, "projected": {"type": "boolean", "description": "true quando a linha é uma projeção (projection != null)."}, "projection": {"anyOf": [{"$ref": "#/components/schemas/TransactionProjection"}, {"type": "null"}]}, "date": {"type": "string", "description": "Dia calendário YYYY-MM-DD (dia UTC do instante ancorado em BRT)."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"], "description": "`DEBIT` (saída) ou `CREDIT` (entrada)."}, "status": {"type": "string", "enum": ["PENDING", "POSTED"]}, "amount": {"type": "number", "description": "Valor sempre positivo, 2 casas."}, "currency": {"type": "string", "description": "Código ISO da moeda; padrão BRL."}, "description": {"type": "string"}, "notes": {"type": ["string", "null"]}, "account_id": {"type": "string"}, "bill_to_account_id": {"type": ["string", "null"], "description": "Em pagamentos de fatura: o cartão pago."}, "category_id": {"type": ["string", "null"]}, "tags": {"type": "array", "items": {"$ref": "#/components/schemas/TransactionTag"}, "description": "Vazio em projeções (ids sintéticos não têm join de tags)."}, "recurrence_id": {"type": ["string", "null"]}, "recurrence_period_date": {"type": ["string", "null"], "description": "YYYY-MM-DD."}, "installment": {"anyOf": [{"type": "object", "required": ["current", "total"], "properties": {"current": {"type": "integer"}, "total": {"type": "integer"}}}, {"type": "null"}]}, "transfer_group_id": {"type": ["string", "null"], "description": "Presente quando o lançamento está marcado como transferência interna."}, "created_by_user": {"type": "boolean"}, "source": {"type": ["string", "null"], "description": "Origem da linha, ex. API, `OPEN_FINANCE`, `MANUAL`."}, "hide_from_results": {"type": "boolean"}, "card_number": {"type": ["string", "null"], "description": "Últimos 4 dígitos do cartão usado, quando conhecido."}, "holder": {"type": ["string", "null"], "description": "Nome do portador do cartão; null quando não nomeado ou quando é o dono da conta."}, "holder_is_me": {"type": "boolean", "description": "true quando o portador é o próprio dono da conta (sentinela \"me\")."}, "original_description": {"type": ["string", "null"], "description": "Descrição original do banco antes de renomeação."}, "receipt_url": {"type": ["string", "null"], "description": "URL do comprovante anexado, quando houver."}, "open_finance": {"type": "boolean", "description": "true quando a linha veio de Open Finance."}}}, "DuplicateTransaction": {"type": "object", "description": "Linha resumida dentro de um grupo de duplicatas.", "required": ["id", "description", "amount", "type", "status", "date", "account_id", "category_id", "source"], "properties": {"id": {"type": "string"}, "description": {"type": "string"}, "amount": {"type": "number", "description": "Valor positivo, 2 casas."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "status": {"type": "string", "enum": ["PENDING", "POSTED"]}, "date": {"type": "string", "description": "YYYY-MM-DD."}, "account_id": {"type": "string"}, "category_id": {"type": ["string", "null"]}, "source": {"type": ["string", "null"]}}}, "DuplicateGroup": {"type": "object", "description": "Grupo de lançamentos considerados possíveis duplicatas (mesma descrição/valor/tipo).", "required": ["description", "amount", "type", "transactions"], "properties": {"description": {"type": "string"}, "amount": {"type": "number", "description": "Valor positivo, 2 casas."}, "type": {"type": "string", "enum": ["DEBIT", "CREDIT"]}, "transactions": {"type": "array", "items": {"$ref": "#/components/schemas/DuplicateTransaction"}}}}, "BulkSkippedRow": {"type": "object", "description": "Linha que recusou parte das alterações em bulk update (campos bloqueados por Open Finance, cartão de crédito ou transferência).", "required": ["id", "reason", "fields"], "properties": {"id": {"type": "string"}, "reason": {"type": "string"}, "fields": {"type": "array", "items": {"type": "string"}}}}, "PossibleDuplicateWarning": {"type": "object", "description": "Aviso de possível duplicata retornado ao criar um lançamento parecido com um já existente.", "required": ["code", "transaction_id"], "properties": {"code": {"type": "string", "enum": ["possible_duplicate"]}, "transaction_id": {"type": "string", "description": "Id do lançamento existente semelhante."}}}, "Problem": {"type": "object", "description": "Erro no formato RFC 7807 (application/problem+json). O campo `code` é estável para tratamento por programa.", "properties": {"type": {"type": "string", "description": "URI que identifica o tipo do erro."}, "title": {"type": "string", "description": "Resumo legível do erro."}, "status": {"type": "integer", "description": "Código HTTP."}, "detail": {"type": "string", "description": "Detalhe legível do que ocorreu."}, "code": {"type": "string", "description": "Código estável do erro (ex.: `validation_error`, `not_found`, `insufficient_scope`, `rate_limited`, `UPGRADE_REQUIRED`)."}}, "required": ["type", "title", "status", "code"]}}, "responses": {"Unauthorized": {"description": "Não autenticado", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#unauthorized", "title": "Não autenticado", "status": 401, "code": "unauthorized", "detail": "Chave de API ausente ou inválida."}}}}, "Forbidden": {"description": "Sem permissão", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#insufficient_scope", "title": "Sem permissão", "status": 403, "code": "insufficient_scope", "detail": "Sua chave é somente leitura (dinzo:read) e esta operação exige escrita (dinzo:write)."}}}}, "NotFound": {"description": "Não encontrado", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#not_found", "title": "Não encontrado", "status": 404, "code": "not_found", "detail": "O recurso não existe ou não é seu."}}}}, "ValidationError": {"description": "Requisição inválida", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#validation_error", "title": "Requisição inválida", "status": 400, "code": "validation_error", "detail": "Algum parâmetro ou o corpo está fora do formato esperado."}}}}, "RateLimited": {"description": "Limite de requisições excedido", "headers": {"Retry-After": {"schema": {"type": "integer"}, "description": "Segundos até poder tentar de novo."}}, "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#rate_limited", "title": "Limite de requisições excedido", "status": 429, "code": "rate_limited", "detail": "120 req/min e 5.000 req/dia por credencial."}}}}, "ServerError": {"description": "Erro interno", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}, "example": {"type": "https://dinzo.com.br/docs/api/erros#internal_error", "title": "Erro interno", "status": 500, "code": "internal_error", "detail": "Algo falhou do nosso lado. Tente de novo em instantes."}}}}}}, "tags": [{"name": "me", "x-displayName": "Conta", "description": "Seu perfil e as configurações da sua conta."}, {"name": "overview", "x-displayName": "Visão geral", "description": "Saldos, dívida de cartão, resultado do mês e saldo previsto."}, {"name": "accounts", "x-displayName": "Contas", "description": "Contas bancárias e cartões — saldos e gestão."}, {"name": "cards", "x-displayName": "Cartões", "description": "Faturas e limite usado dos cartões de crédito."}, {"name": "transactions", "x-displayName": "Lançamentos", "description": "Receitas, despesas, parcelas e a visão consolidada."}, {"name": "transfers", "x-displayName": "Transferências", "description": "Transferências entre as suas próprias contas."}, {"name": "categories", "x-displayName": "Categorias", "description": "Categorias e subcategorias — próprias e do sistema."}, {"name": "tags", "x-displayName": "Tags", "description": "Etiquetas livres para agrupar lançamentos."}, {"name": "targets", "x-displayName": "Metas", "description": "Metas financeiras e o progresso de cada uma."}, {"name": "subscriptions", "x-displayName": "Assinaturas", "description": "Assinaturas detectadas e recorrentes."}, {"name": "recurring-rules", "x-displayName": "Recorrências", "description": "Regras de lançamentos recorrentes e suas ocorrências."}, {"name": "installment-series", "x-displayName": "Parcelamentos", "description": "Séries de compras parceladas."}, {"name": "investments", "x-displayName": "Investimentos", "description": "Posições, rendimentos e evolução dos investimentos."}, {"name": "reports", "x-displayName": "Relatórios", "description": "Resumos, quebra por categoria, séries e previsões."}, {"name": "notifications", "x-displayName": "Notificações", "description": "Suas notificações no app."}, {"name": "open-finance", "x-displayName": "Open Finance", "description": "Conexões bancárias via Open Finance."}, {"name": "icons", "x-displayName": "Ícones", "description": "Catálogo de ícones para categorias e contas."}]}