{ "info": { "name": "API do Financeiro Inteligente (v1.0.0) — Português", "description": "Você que é dev, divirta-se! ✨\n\n> **Índice da documentação** — acesse o índice completo em [https://docs.finance.kobana.com.br/llms.txt](https://docs.finance.kobana.com.br/llms.txt). Use este arquivo para descobrir todas as páginas disponíveis antes de explorar.\n\n## Autenticação\n\nA API usa **Bearer JWT (HS512)**. Envie o token no cabeçalho de toda requisição:\n\n```\nAuthorization: Bearer \n```\n\nPara testes em linha de comando, exporte o token: `export KOBANA_TOKEN=xxxxxxxx` e cole os comandos da documentação no terminal.\n\n## Formato\n\nA API aceita apenas o formato `JSON`. Todas as requisições devem usar `Content-Type: application/json`. Todas as respostas usam `snake_case`.\n\n| Tipo de Campo | Formato |\n| :--- | :--- |\n| **DateTime** | Formato [ISO8601](https://pt.wikipedia.org/wiki/ISO_8601). Exemplos — Data: `2026-01-24`. Data e Hora: `2026-01-24T10:07:00.000Z` |\n| **Money** | Decimal como string com 2 casas (`\"150.00\"`). Sempre positivo — direção indicada pelo campo `type` (`debit`/`credit`) ou pelo contexto (payable/receivable). |\n| **UUID** | Identificadores de recursos no formato UUID v4 |\n\n## Convenções\n\nConvenções usadas nesta documentação:\n\n| Convenção | Descrição |\n| :--- | :--- |\n| **`:id`** | Parâmetro de path que deve ser substituído pelo UUID do recurso. |\n| **`#{variable}`** | Valor da sua conta que deve ser substituído no exemplo. |\n| **`...`** | Conteúdo da resposta truncado para facilitar a leitura. |\n| **`$KOBANA_TOKEN`** | Token JWT de acesso. Exporte com `export KOBANA_TOKEN=xxxxxxxx`. |\n\n## Ambientes\n\n| Ambiente | Base URL |\n| :--- | :--- |\n| **Produção** | `https://api.finance.kobana.com.br/v1` |\n| **Sandbox** | `https://api.finance.sandbox.kobana.com.br/v1` |\n\n## Códigos de Retorno\n\nA API retorna códigos HTTP padrão:\n\n| | Código | Descrição |\n| :--- | :--- | :--- |\n| ✅ | **200 OK** | Requisição bem-sucedida com corpo de resposta. |\n| ✅ | **201 Created** | Recurso criado com sucesso. |\n| ✅ | **204 No Content** | Requisição bem-sucedida, sem corpo de resposta. |\n| ❌ | **400 Bad Request** | Requisição inválida, em geral conteúdo mal formado. |\n| ❌ | **401 Unauthorized** | Token ausente, inválido ou expirado. |\n| ❌ | **403 Forbidden** | Escopo insuficiente para a operação. |\n| ❌ | **404 Not Found** | Recurso não encontrado ou fora do workspace. |\n| ❌ | **422 Unprocessable Entity** | Requisição válida, mas os dados enviados não são. |\n| ❌ | **429 Too Many Requests** | Limite de requisições atingido. |\n| ❌ | **500 Internal Server Error** | Erro interno no processamento. Consulte o [status dos servidores](https://status.kobana.com.br). |\n\n## Listagem e Paginação\n\nTodos os endpoints de listagem usam **paginação por cursor**:\n\n```\nGET /v1/payables?cursor=&limit=25\n```\n\nA resposta inclui `meta.next_cursor` — passe-o como `?cursor=` na próxima requisição para buscar a página seguinte. Quando `meta.next_cursor` é `null`, não há mais páginas.\n\n## Idempotência\n\nOperações de criação (`POST`) aceitam o cabeçalho `X-Idempotency-Key`. Reenvios com a mesma chave retornam o resultado original sem criar duplicatas — seguro para retry em caso de falha de rede.\n\n```\nX-Idempotency-Key: \n```\n\n## ID das Requisições (Request ID)\n\nCada requisição possui um identificador associado, disponível no cabeçalho `Request-Id` da resposta. Esse valor ajuda na depuração e auditoria. O log de requisições fica disponível por **30 dias**. Ao abrir um chamado de suporte sobre uma requisição específica, informe o `Request-Id` para acelerar a investigação.\n\n## Segurança\n\nA API usa certificados **SSL 2048 bits**. Toda requisição deve ser feita via **HTTPS** — chamadas na porta 80 são redirecionadas para 443.\n\nOs clientes devem suportar `TLSv1.2` ou `TLSv1.3` com uma das cifras: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` e `TLSv1.1` não são suportados.\n\n## Cache HTTP\n\nUse os cabeçalhos HTTP de cache para reduzir carga e ganhar velocidade. A maioria das respostas inclui `ETag` e/ou `Last-Modified` — armazene esses valores e reenvie nas próximas requisições via `If-None-Match` e `If-Modified-Since`. Se o recurso não mudou, a resposta será `304 Not Modified`, sem corpo e sem reprocessamento.\n\n## Tratamento de Erros\n\nErros 5xx indicam falhas no servidor: **500 Internal Server Error** (aplicação indisponível), **502 Bad Gateway**, **503 Service Unavailable** e **504 Gateway Timeout** (falhas pontuais de infraestrutura). Sua aplicação deve identificar esses códigos e reagendar a requisição após alguns minutos com backoff exponencial. Status dos servidores: [https://status.kobana.com.br](https://status.kobana.com.br).\n\n## Spec OpenAPI\n\nImporte a spec no Postman ou Insomnia para ter uma coleção pronta que sempre reflete a API atual:\n\n- **YAML:** `/api/v1/openapi.yaml`\n- **JSON:** `/api/v1/openapi.json`", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{bearerToken}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api.finance.kobana.com.br/v1", "type": "string", "description": "https://api.finance.kobana.com.br/v1 — Production\nhttps://api.finance.sandbox.kobana.com.br/v1 — Sandbox" }, { "key": "bearerToken", "value": "", "type": "string", "description": "JWT (HS512) usado no header Authorization: Bearer." } ], "item": [ { "name": "Contas Financeiras", "item": [ { "name": "Listar contas financeiras", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-accounts?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&type=checking&bank_id=00000000-0000-0000-0000-000000000000&active=true&name=&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts" ], "query": [ { "key": "company_id", "value": "62057dab-0f98-4020-ae1e-2c0803251b1e", "disabled": true }, { "key": "type", "value": "checking", "disabled": true }, { "key": "bank_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "active", "value": "true", "disabled": true }, { "key": "name", "value": "", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of financial accounts for the workspace tied to the token's `sub` claim. Accounts may belong to a specific company or be workspace-level (`company_id` nullable). **The current balance is NOT returned by this listing** — the stored `balance` column is a write-only seed; the real balance is derived from the transactions ledger and will be available on the detail endpoint. Requires scope `finance.accounts`." }, "response": [] }, { "name": "Criar conta financeira", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/financial-accounts", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"\",\n \"type\": \"checking\",\n \"bank_id\": \"00000000-0000-0000-0000-000000000000\",\n \"bank_code\": \"341\",\n \"agency\": \"\",\n \"agency_digit\": \"\",\n \"account_number\": \"\",\n \"account_digit\": \"\",\n \"balance\": \"0.00\",\n \"disable_reconcile\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a financial account. Requires scope `finance.accounts.write`. `workspace_id` is taken from the token. `company_id` is required (accounts must belong to a company; workspace-level accounts exist from imports but aren't creatable via v1). `balance` is an opening seed (default `0.00`) — it is NOT the live balance (that is computed from transactions and returned on the detail endpoint) and cannot be updated. The bank may be given as `bank_id` (UUID) or `bank_code` (public COMPE/BACEN, e.g. `341`) — not both (400); an unknown code → 422. The response echoes the resolved bank as `bank: { code, name }`. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter conta financeira por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Returns the account plus the **computed `balance`** (live, derived from posted transactions — not the creation seed; #13). The listing still omits balance. Returns the same shape as the rows from the list endpoint. Requires scope `finance.accounts`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar conta financeira", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/financial-accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"\",\n \"type\": \"checking\",\n \"bank_id\": \"00000000-0000-0000-0000-000000000000\",\n \"bank_code\": \"341\",\n \"agency\": \"\",\n \"agency_digit\": \"\",\n \"account_number\": \"\",\n \"account_digit\": \"\",\n \"disable_reconcile\": false,\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update. Requires scope `finance.accounts.write`. `balance` is never settable (the live balance is computed). Set `active: false` to soft-deactivate (existing transactions stay valid). The bank accepts `bank_id` or `bank_code` (not both → 400; unknown code → 422); the response echoes `bank: { code, name }`." }, "response": [] }, { "name": "Excluir conta financeira", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/financial-accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes an account. Requires scope `finance.accounts.write`. Returns 422 (`reason: in_use`, with a `usage` breakdown) when the account has any transaction, payable or receivable — deleting would cascade-delete its transactions, so soft-deactivate via `PATCH { active: false }` instead. Calling DELETE twice returns 204 then 404." }, "response": [] }, { "name": "Ajustar saldo da conta", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/financial-accounts/:id/adjust-balance", "host": [ "{{baseUrl}}" ], "path": [ "financial-accounts", ":id", "adjust-balance" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"target_balance\": \"1500.00\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"occurred_at\": \"2026-01-01T00:00:00Z\",\n \"description\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Corrects the account's calculated balance to `target_balance` by inserting an auto-created adjustment transaction for the signed diff. Requires scope `finance.accounts.write`. The `category_id` type must match the diff direction (credit for a positive diff, debit for negative) and its company must match the account's. A target equal to the current balance is rejected (422). Pass an `X-Idempotency-Key` header on retries." }, "response": [] } ] }, { "name": "Contas a Pagar", "item": [ { "name": "Somar totais de contas a pagar", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payables/aggregates?company_id=00000000-0000-0000-0000-000000000000&month=0&year=2026&start_date=2026-07-01&end_date=2026-07-31", "host": [ "{{baseUrl}}" ], "path": [ "payables", "aggregates" ], "query": [ { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "month", "value": "0", "disabled": true }, { "key": "year", "value": "2026", "disabled": true }, { "key": "start_date", "value": "2026-07-01", "disabled": true }, { "key": "end_date", "value": "2026-07-31", "disabled": true } ] }, "description": "Sums payables for the workspace tied to the token: `count`, `total`, `pending`, `paid`, `overdue_count`. Requires scope `finance.payables`. Filter by `company_id` and a period; omit all filters for all-time." }, "response": [] }, { "name": "Listar IDs de contas a pagar", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payables/ids?limit=&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "payables", "ids" ], "query": [ { "key": "limit", "value": "", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Every payable id the token can see. Requires scope `finance.payables`. Pairs with `?updated_at[gte]=` on the listing. The delta reports what changed; this reports what still exists. A delta can never report a disappearance — the row it would have to describe is gone — so an id that stops appearing here is the only signal that something left. Diff this set against your mirror and drop what is missing. Takes no filters: the sweep must cover exactly what the listing shows, and a filter applied here but not to your mirror would read as mass deletion. Note that deletion is not the only exit: a payable whose payment authorization is rejected leaves the visible set while its row stays put, and it disappears from this sweep exactly as a deleted one would." }, "response": [] }, { "name": "Listar contas a pagar", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payables?company_id=00000000-0000-0000-0000-000000000000&status=pending&type=normal&person_id=00000000-0000-0000-0000-000000000000&category_id=00000000-0000-0000-0000-000000000000&classification_center_id=00000000-0000-0000-0000-000000000000&financial_account_id=00000000-0000-0000-0000-000000000000&payment_method_kind=bank_billet&payment_authorization=pending_authorization&due_date=&payment_date=&competence_date=&updated_at=&amount=&document_number=&ir_relevant=true&group_id=00000000-0000-0000-0000-000000000000&sort=due_date&limit=0&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "payables" ], "query": [ { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "status", "value": "pending", "disabled": true }, { "key": "type", "value": "normal", "disabled": true }, { "key": "person_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "category_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "classification_center_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "financial_account_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "payment_method_kind", "value": "bank_billet", "disabled": true }, { "key": "payment_authorization", "value": "pending_authorization", "disabled": true }, { "key": "due_date", "value": "", "disabled": true }, { "key": "payment_date", "value": "", "disabled": true }, { "key": "competence_date", "value": "", "disabled": true }, { "key": "updated_at", "value": "", "disabled": true }, { "key": "amount", "value": "", "disabled": true }, { "key": "document_number", "value": "", "disabled": true }, { "key": "ir_relevant", "value": "true", "disabled": true }, { "key": "group_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "sort", "value": "due_date", "disabled": true }, { "key": "limit", "value": "0", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of payables (accounts payable) for the workspace tied to the token's `sub` claim. Each row includes denormalised display names (`person_name`, `category_name`, `classification_center_name`) and aggregate counts (`tax_charges_count`, `classification_center_allocations_count`, `attachments_count`) — full child collections live in the per-resource detail endpoints. Each row also carries the settlement amounts (`interest_amount`, `discount_amount`, `ticket_amount`) and a derived `nominal_amount = amount + interest - discount`. Status is the raw DB enum (`pending` / `paid` / `cancelled`); derive overdue client-side via `status === \"pending\" AND due_date < today`. Default sort is `due_date` ascending. Payables awaiting human authorization (see the create endpoint) are **omitted** from this list until an operator authorizes them in the app; a title is still retrievable by id via `GET /payables/{id}`. To **list the authorization queue** instead, filter it explicitly — `?payment_authorization=pending_authorization` (read-only; there is no authorize/reject action on this API). Each row carries its `payment_authorization` state. Requires scope `finance.payables`." }, "response": [] }, { "name": "Criar conta a pagar", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/payables", "host": [ "{{baseUrl}}" ], "path": [ "payables" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"description\": \"\",\n \"amount\": \"1500.00\",\n \"due_date\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"normal\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"payment_method_kind\": \"bank_billet\",\n \"operation_kind\": \"payment\",\n \"financial_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"expected_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"document_number\": \"\",\n \"notes\": \"\",\n \"ir_relevant\": false,\n \"recurrence_period\": \"\",\n \"total_installments\": 0,\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"tax_charges\": [\n {\n \"tax_id\": \"00000000-0000-0000-0000-000000000000\",\n \"amount\": 0,\n \"withholding\": false\n }\n ],\n \"barcode\": \"\",\n \"pix_copia_e_cola\": \"\",\n \"pix_key\": \"\",\n \"pix_key_type\": \"cpf\",\n \"bank_code\": \"\",\n \"bank_ispb\": \"\",\n \"agency\": \"\",\n \"agency_digit\": \"\",\n \"account_number\": \"\",\n \"account_digit\": \"\",\n \"transfer_purpose\": \"\",\n \"tax_kind\": \"itbi\",\n \"tax_data\": {\n \"tax_code\": \"\",\n \"reference_number\": \"\",\n \"taxpayer_type\": \"\",\n \"taxpayer_number\": \"\",\n \"taxpayer_name\": \"\",\n \"calculation_date\": \"\",\n \"competence_date\": \"\",\n \"expire_at\": \"\",\n \"fine_amount\": 0,\n \"interest_amount\": 0,\n \"gross_income_amount\": 0,\n \"total_amount\": 0,\n \"discount_amount\": 0,\n \"other_deduction_amount\": 0,\n \"other_addition_amount\": 0,\n \"other_entities_amount\": 0,\n \"monetary_update_amount\": 0,\n \"contributor_code\": \"\",\n \"fgts_code\": \"\",\n \"collection_code\": \"\",\n \"pis_pasep_number\": \"\",\n \"jam_percentage\": 0,\n \"connectivity_seal\": \"\"\n },\n \"beneficiary_name\": \"\",\n \"beneficiary_document\": \"\",\n \"scheduled_to\": \"2026-01-01T00:00:00Z\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a single payable (or an installment/recurring series). Requires scope `finance.payables.write`. `workspace_id` is always taken from the token. A person is required — send `person_id` or `person_name`. `*_name` (person / category / classification_center) is find-or-create; sending both `*_id` and `*_name` for the same FK returns 400. `classification_centers[]` (rateio) and `tax_charges[]` are accepted; the rateio Σ is validated against `amount`. When payment authorization is enabled for the workspace (a per-workspace setting, on by default), the created payable enters an **authorization queue**: it is returned here (with its id) but is **hidden from `GET /payables` until an operator authorizes it in the app** — fetch it by id meanwhile. With the setting off, the payable appears on `GET /payables` immediately. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter conta a pagar por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payables/:id", "host": [ "{{baseUrl}}" ], "path": [ "payables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "List-row shape plus the expanded child arrays the list only counts: `classification_center_allocations[]` (rateio) and `tax_charges[]`, plus the `reconciliation` group (`null` when not reconciled). Returns the same shape as the rows from the list endpoint. Requires scope `finance.payables`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar ou liquidar conta a pagar", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/payables/:id", "host": [ "{{baseUrl}}" ], "path": [ "payables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"\",\n \"amount\": \"1500.00\",\n \"due_date\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"normal\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"payment_method_kind\": \"bank_billet\",\n \"operation_kind\": \"payment\",\n \"financial_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"expected_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"document_number\": \"\",\n \"notes\": \"\",\n \"ir_relevant\": false,\n \"recurrence_period\": \"\",\n \"total_installments\": 0,\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"tax_charges\": [\n {\n \"tax_id\": \"00000000-0000-0000-0000-000000000000\",\n \"amount\": 0,\n \"withholding\": false\n }\n ],\n \"barcode\": \"\",\n \"pix_copia_e_cola\": \"\",\n \"pix_key\": \"\",\n \"pix_key_type\": \"cpf\",\n \"bank_code\": \"\",\n \"bank_ispb\": \"\",\n \"agency\": \"\",\n \"agency_digit\": \"\",\n \"account_number\": \"\",\n \"account_digit\": \"\",\n \"transfer_purpose\": \"\",\n \"tax_kind\": \"itbi\",\n \"tax_data\": {\n \"tax_code\": \"\",\n \"reference_number\": \"\",\n \"taxpayer_type\": \"\",\n \"taxpayer_number\": \"\",\n \"taxpayer_name\": \"\",\n \"calculation_date\": \"\",\n \"competence_date\": \"\",\n \"expire_at\": \"\",\n \"fine_amount\": 0,\n \"interest_amount\": 0,\n \"gross_income_amount\": 0,\n \"total_amount\": 0,\n \"discount_amount\": 0,\n \"other_deduction_amount\": 0,\n \"other_addition_amount\": 0,\n \"other_entities_amount\": 0,\n \"monetary_update_amount\": 0,\n \"contributor_code\": \"\",\n \"fgts_code\": \"\",\n \"collection_code\": \"\",\n \"pis_pasep_number\": \"\",\n \"jam_percentage\": 0,\n \"connectivity_seal\": \"\"\n },\n \"beneficiary_name\": \"\",\n \"beneficiary_document\": \"\",\n \"scheduled_to\": \"2026-01-01T00:00:00Z\",\n \"status\": \"pending\",\n \"payment_date\": \"2026-01-01T00:00:00Z\",\n \"interest_amount\": 0,\n \"discount_amount\": 0,\n \"ticket_amount\": 0\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update. Only fields present in the body are written; unknown / response-only fields (`id`, `created_at`, `transaction_id`, denorm names, counts, `is_reconciled`) are silently dropped. Requires scope `finance.payables.write`. **Settle**: send `status:\"paid\"` with `payment_date` and `financial_account_id` (or rely on a previously-set account) — a debit payment transaction is generated automatically. The settlement amounts (`interest_amount` / `discount_amount` / `ticket_amount`) are persisted on the row. Set `status` back to `pending` to revert, or `cancelled` to cancel. `draft` is never accepted." }, "response": [] }, { "name": "Excluir conta a pagar", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/payables/:id", "host": [ "{{baseUrl}}" ], "path": [ "payables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Hard-deletes the payable. Requires scope `finance.payables.write`. Dissolves any reconciliation the payable is part of and removes the auto-created payment transaction (manually-linked transactions are preserved). Calling DELETE twice on the same id returns 204 then 404 (Stripe-style). Deletes a single row — series-aware delete is not yet exposed." }, "response": [] }, { "name": "Enviar conta a pagar ao banco", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": false } ], "url": { "raw": "{{baseUrl}}/payables/:id/send-to-bank", "host": [ "{{baseUrl}}" ], "path": [ "payables", ":id", "send-to-bank" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Dispatches an authorized payable to the bank through the Kobana gateway (creates the payment, then envelopes and approves it). Requires scope `finance.payables.dispatch` — deliberately **separate** from `finance.payables.write` (dispatching money is not editing a title) and, by default, never granted in the same token as `.authorize`. `X-Idempotency-Key` is **required**. Only an **official** title dispatches — one whose `payment_authorization` is `null` or `authorized`; a title still awaiting authorization (`pending_authorization` / `authorizing`) or `rejected` returns 422. The payable must also carry the payment coordinates for its method and a Kobana-mirrored source account. Returns the refreshed payable detail with the execution mirror (`kobana_status`, `kobana_payment_uid`) populated. **Note:** the Kobana sandbox `example_bank` does not execute outbound payments, so the full `confirmed` cycle is only observable against an environment that actually settles." }, "response": [] }, { "name": "Cancelar o envio ao banco", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": false } ], "url": { "raw": "{{baseUrl}}/payables/:id/cancel-dispatch", "host": [ "{{baseUrl}}" ], "path": [ "payables", ":id", "cancel-dispatch" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Undoes a payable's bank dispatch on the Kobana side and mirrors the payment as `canceled` (the `kobana_*` mirror is kept, not cleared — the title returns to the manual rail because `canceled` is terminal). Requires scope `finance.payables.dispatch` and a **required** `X-Idempotency-Key`. A title that was never dispatched, or whose execution already reached a terminal state (`confirmed` / `canceled` / …), returns 422. Returns the refreshed payable detail." }, "response": [] } ] }, { "name": "Contas a Receber", "item": [ { "name": "Somar totais de contas a receber", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/receivables/aggregates?company_id=00000000-0000-0000-0000-000000000000&month=0&year=2026&start_date=2026-07-01&end_date=2026-07-31", "host": [ "{{baseUrl}}" ], "path": [ "receivables", "aggregates" ], "query": [ { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "month", "value": "0", "disabled": true }, { "key": "year", "value": "2026", "disabled": true }, { "key": "start_date", "value": "2026-07-01", "disabled": true }, { "key": "end_date", "value": "2026-07-31", "disabled": true } ] }, "description": "Sums receivables for the workspace tied to the token: `count`, `total`, `pending`, `received`, `overdue_count`. Requires scope `finance.receivables`. Filter by `company_id` and a period; omit all filters for all-time." }, "response": [] }, { "name": "Listar IDs de contas a receber", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/receivables/ids?limit=&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "receivables", "ids" ], "query": [ { "key": "limit", "value": "", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Every receivable id the token can see. Requires scope `finance.receivables`. Pairs with `?updated_at[gte]=` on the listing. The delta reports what changed; this reports what still exists. A delta can never report a disappearance — the row it would have to describe is gone — so an id that stops appearing here is the only signal that something left. Diff this set against your mirror and drop what is missing. Takes no filters: the sweep must cover exactly what the listing shows, and a filter applied here but not to your mirror would read as mass deletion." }, "response": [] }, { "name": "Listar contas a receber", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/receivables?company_id=00000000-0000-0000-0000-000000000000&status=pending&type=normal&person_id=00000000-0000-0000-0000-000000000000&category_id=00000000-0000-0000-0000-000000000000&classification_center_id=00000000-0000-0000-0000-000000000000&financial_account_id=00000000-0000-0000-0000-000000000000&payment_method_kind=bank_billet&due_date=&payment_date=&competence_date=&updated_at=&amount=&document_number=&ir_relevant=true&group_id=00000000-0000-0000-0000-000000000000&sort=due_date&limit=0&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "receivables" ], "query": [ { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "status", "value": "pending", "disabled": true }, { "key": "type", "value": "normal", "disabled": true }, { "key": "person_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "category_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "classification_center_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "financial_account_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "payment_method_kind", "value": "bank_billet", "disabled": true }, { "key": "due_date", "value": "", "disabled": true }, { "key": "payment_date", "value": "", "disabled": true }, { "key": "competence_date", "value": "", "disabled": true }, { "key": "updated_at", "value": "", "disabled": true }, { "key": "amount", "value": "", "disabled": true }, { "key": "document_number", "value": "", "disabled": true }, { "key": "ir_relevant", "value": "true", "disabled": true }, { "key": "group_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "sort", "value": "due_date", "disabled": true }, { "key": "limit", "value": "0", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of receivables (accounts receivable) for the workspace tied to the token's `sub` claim. Mirror of `/payables` with the receive-side settlement amounts (`interest_amount`, `discount_amount`, `ticket_amount`) and a derived `nominal_amount = amount + interest - discount`. Status is the raw DB enum (`pending` / `received` / `cancelled`); derive overdue client-side. Default sort is `due_date` ascending. Requires scope `finance.receivables`." }, "response": [] }, { "name": "Criar conta a receber", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/receivables", "host": [ "{{baseUrl}}" ], "path": [ "receivables" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"description\": \"\",\n \"amount\": \"1500.00\",\n \"due_date\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"normal\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"payment_method_kind\": \"bank_billet\",\n \"financial_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"expected_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"document_number\": \"\",\n \"notes\": \"\",\n \"ir_relevant\": false,\n \"recurrence_period\": \"\",\n \"total_installments\": 0,\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"tax_charges\": [\n {\n \"tax_id\": \"00000000-0000-0000-0000-000000000000\",\n \"amount\": 0,\n \"withholding\": false\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a single receivable (or an installment/recurring series). Requires scope `finance.receivables.write`. `workspace_id` is always taken from the token. A person is required — send `person_id` or `person_name`. `*_name` (person / category / classification_center) is find-or-create (customer/credit/revenue polarity); sending both `*_id` and `*_name` for the same FK returns 400. `classification_centers[]` (rateio) and `tax_charges[]` are accepted. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter conta a receber por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/receivables/:id", "host": [ "{{baseUrl}}" ], "path": [ "receivables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Mirror of the payable detail — denorm names + counts + `nominal_amount`, plus the expanded `classification_center_allocations[]` / `tax_charges[]` arrays and the `reconciliation` group (`null` when not reconciled). Returns the same shape as the rows from the list endpoint. Requires scope `finance.receivables`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar ou liquidar conta a receber", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/receivables/:id", "host": [ "{{baseUrl}}" ], "path": [ "receivables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"\",\n \"amount\": \"1500.00\",\n \"due_date\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"normal\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"payment_method_kind\": \"bank_billet\",\n \"financial_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"expected_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"document_number\": \"\",\n \"notes\": \"\",\n \"ir_relevant\": false,\n \"recurrence_period\": \"\",\n \"total_installments\": 0,\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"tax_charges\": [\n {\n \"tax_id\": \"00000000-0000-0000-0000-000000000000\",\n \"amount\": 0,\n \"withholding\": false\n }\n ],\n \"status\": \"pending\",\n \"payment_date\": \"2026-01-01T00:00:00Z\",\n \"interest_amount\": 0,\n \"discount_amount\": 0,\n \"ticket_amount\": 0\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update. Only fields present in the body are written; unknown / response-only fields are silently dropped. Requires scope `finance.receivables.write`. **Settle (receive)**: send `status:\"received\"` with `payment_date` and `financial_account_id` (or a previously-set account) — an auto credit transaction is generated; the receive-time `interest_amount` / `discount_amount` / `ticket_amount` are persisted. Set `status` back to `pending` to revert, or `cancelled` to cancel. `draft` is never accepted." }, "response": [] }, { "name": "Excluir conta a receber", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/receivables/:id", "host": [ "{{baseUrl}}" ], "path": [ "receivables", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Hard-deletes the receivable. Requires scope `finance.receivables.write`. Dissolves any reconciliation and removes the auto-created receipt transaction (manually-linked transactions are preserved). Calling DELETE twice returns 204 then 404 (Stripe-style). Single-row — series-aware delete is not yet exposed." }, "response": [] } ] }, { "name": "Transações Financeiras", "item": [ { "name": "Somar totais de transações", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-transactions/aggregates?company_id=00000000-0000-0000-0000-000000000000&month=0&year=2026&start_date=2026-07-01&end_date=2026-07-31", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions", "aggregates" ], "query": [ { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "month", "value": "0", "disabled": true }, { "key": "year", "value": "2026", "disabled": true }, { "key": "start_date", "value": "2026-07-01", "disabled": true }, { "key": "end_date", "value": "2026-07-31", "disabled": true } ] }, "description": "Sums realised transactions for the workspace tied to the token (forecasts excluded): `count`, `credit`, `debit`, `net`. Requires scope `finance.transactions`. Filter by `company_id` and a period; omit all filters for all-time." }, "response": [] }, { "name": "Listar IDs de transações", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-transactions/ids?limit=&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions", "ids" ], "query": [ { "key": "limit", "value": "", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Every financial transaction id the token can see. Requires scope `finance.transactions`. Pairs with `?updated_at[gte]=` on the listing. The delta reports what changed; this reports what still exists. A delta can never report a disappearance — the row it would have to describe is gone — so an id that stops appearing here is the only signal that something left. Diff this set against your mirror and drop what is missing. Takes no filters: the sweep must cover exactly what the listing shows, and a filter applied here but not to your mirror would read as mass deletion. This is the largest resource in the API, which is what makes the pairing worth the trouble: re-paging the full history to find a handful of removals is exactly the cost the delta exists to avoid." }, "response": [] }, { "name": "Listar transações", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-transactions?company_id=11111111-1111-1111-1111-111111111111&type=debit&financial_account_id=00000000-0000-0000-0000-000000000000&person_id=00000000-0000-0000-0000-000000000000&category_id=00000000-0000-0000-0000-000000000000&classification_center_id=00000000-0000-0000-0000-000000000000&occurred_at=2026-01-01&updated_at=&amount=100.00&sort=occurred_at&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions" ], "query": [ { "key": "company_id", "value": "11111111-1111-1111-1111-111111111111", "disabled": true }, { "key": "type", "value": "debit", "disabled": true }, { "key": "financial_account_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "person_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "category_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "classification_center_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "occurred_at", "value": "2026-01-01", "disabled": true }, { "key": "updated_at", "value": "", "disabled": true }, { "key": "amount", "value": "100.00", "disabled": true }, { "key": "sort", "value": "occurred_at", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of transactions for the workspace tied to the token's `sub` claim. Requires scope `finance.transactions`." }, "response": [] }, { "name": "Criar transação", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/financial-transactions", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"financial_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"description\": \"\",\n \"bank_description\": \"\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"amount\": \"1500.00\",\n \"occurred_at\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"debit\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"payment_method_kind\": \"bank_billet\",\n \"classified\": false,\n \"notes\": \"\",\n \"is_pending\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a single transaction. Requires scope `finance.transactions.write`. `workspace_id` is always taken from the token, never from the body. `auto_created` and `transfer_id` are always server-controlled — values in the request are ignored. `*_name` accepted as alternative to `*_id` (person / category / classification_center) for CSV-importer ergonomics; sending both for the same FK returns 400. Send `classification_centers[]` to split the amount across classification centers (rateio): effective amounts must sum to `amount` (1-cent tolerance) and each center's polarity must match `type` (`both` matches either). When present it supersedes `classification_center_id`/`_name` (which then mirrors rows[0]); the full split rides back on every read as `classification_center_allocations[]`. Pass an `X-Idempotency-Key` header on retries to avoid duplicate inserts." }, "response": [] }, { "name": "Atualizar transação", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/financial-transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"description\": \"\",\n \"bank_description\": \"\",\n \"document\": \"\",\n \"document_date\": \"2026-01-01T00:00:00Z\",\n \"amount\": \"1500.00\",\n \"occurred_at\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"type\": \"debit\",\n \"category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"category_name\": \"\",\n \"person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"person_name\": \"\",\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"classification_center_name\": \"\",\n \"classification_centers\": [\n {\n \"classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"percentage\": 0,\n \"amount\": 0\n }\n ],\n \"payment_method_kind\": \"bank_billet\",\n \"classified\": false,\n \"notes\": \"\",\n \"is_pending\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update. Only fields present in the body are written. Requires scope `finance.transactions.write`. Read-only fields in the body (`id`, `workspace_id`, `company_id`, `financial_account_id`, `auto_created`, `transfer_id`, `created_at`) are silently dropped — the response is the new persisted state." }, "response": [] }, { "name": "Excluir transação", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/financial-transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Hard-deletes the row. Requires scope `finance.transactions.write`. Deleting an auto-created row (one generated by paying / receiving a payable / receivable) returns 422 — cancel the source billing instead. Calling DELETE twice on the same id returns 204 then 404 (Stripe-style)." }, "response": [] }, { "name": "Obter transação por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/financial-transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "financial-transactions", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.transactions`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] } ] }, { "name": "Anexos", "item": [ { "name": "Listar anexos", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/attachments?mime_type=application/pdf&file_name=&uploaded_by=&uploaded_at=&linked_to_payable_id=00000000-0000-0000-0000-000000000000&linked_to_receivable_id=00000000-0000-0000-0000-000000000000&linked_to_transaction_id=00000000-0000-0000-0000-000000000000&sort=uploaded_at&limit=0&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "attachments" ], "query": [ { "key": "mime_type", "value": "application/pdf", "disabled": true }, { "key": "file_name", "value": "", "disabled": true }, { "key": "uploaded_by", "value": "", "disabled": true }, { "key": "uploaded_at", "value": "", "disabled": true }, { "key": "linked_to_payable_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "linked_to_receivable_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "linked_to_transaction_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "sort", "value": "uploaded_at", "disabled": true }, { "key": "limit", "value": "0", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of attachment metadata for the workspace tied to the token's `sub` claim. Each row carries an absolute `download_url` pointing at the download endpoint; fetching the bytes requires the same Bearer JWT (scope `finance.attachments`). Aggregate counts (`linked_payables_count` etc.) expose how many parent rows reference each blob without forcing the client to call every parent endpoint. Default sort is `uploaded_at` descending (newest first). Requires scope `finance.attachments`." }, "response": [] }, { "name": "Enviar um anexo", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/attachments", "host": [ "{{baseUrl}}" ], "path": [ "attachments" ] }, "description": "Uploads a file to the workspace blob registry. Send as `multipart/form-data` with a `file` part and an optional `title`. Requires scope `finance.attachments.write`. Allowed types: pdf, png, jpg/jpeg, xml, ofx, csv, xlsx; max 10 MB. For PDF/PNG/JPEG the declared MIME must match the payload's magic bytes (mismatch → 422). The response is the same metadata shape as `GET /attachments/{id}`; link counts start at 0 — associate the file via `POST /attachments/{id}/links`. No `X-Idempotency-Key` support on upload." }, "response": [] }, { "name": "Baixar bytes do anexo", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/attachments/:id/download", "host": [ "{{baseUrl}}" ], "path": [ "attachments", ":id", "download" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Streams the file bytes for the attachment back to the caller. Same Bearer JWT (scope `finance.attachments`) as the listing endpoint. `Content-Type` reflects the stored MIME; `Content-Disposition` is `inline` for PDF / images and `attachment` for other types. No caching — `Cache-Control: private, no-store`." }, "response": [] }, { "name": "Obter metadados do anexo por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/attachments/:id", "host": [ "{{baseUrl}}" ], "path": [ "attachments", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Returns the metadata row including `download_url`. Fetching the bytes still requires `GET /attachments/{id}/download` with the same scope. Returns the same shape as the rows from the list endpoint. Requires scope `finance.attachments`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Excluir anexo", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/attachments/:id", "host": [ "{{baseUrl}}" ], "path": [ "attachments", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes the attachment row and its stored bytes. Requires scope `finance.attachments.write`. Returns 409 (`conflict`, with per-entity link counts in `details`) when the file is still linked to any payable / receivable / transaction — unlink it first via `DELETE /attachments/{id}/links`. Calling DELETE twice returns 204 then 404." }, "response": [] }, { "name": "Vincular anexo a um registro", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/attachments/:id/links", "host": [ "{{baseUrl}}" ], "path": [ "attachments", ":id", "links" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"type\": \"payable\",\n \"id\": \"8c8b4c4f-2e0e-4f6e-9b8a-2a1c2b3d4e5f\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Associates an existing attachment with a payable / receivable / transaction. The `{id}` path segment is the attachment; the body identifies the parent. Requires scope `finance.attachments.write`. Returns 409 when the association already exists, 404 when either the attachment or the parent is outside the tenant." }, "response": [] }, { "name": "Desvincular anexo de um registro", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/attachments/:id/links", "host": [ "{{baseUrl}}" ], "path": [ "attachments", ":id", "links" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"type\": \"payable\",\n \"id\": \"8c8b4c4f-2e0e-4f6e-9b8a-2a1c2b3d4e5f\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Removes a single association between the attachment (`{id}`) and the parent identified in the body. Requires scope `finance.attachments.write`. Returns 404 when no such association exists. The attachment row itself is left intact — delete it with `DELETE /attachments/{id}`." }, "response": [] } ] }, { "name": "Regras Automáticas", "item": [ { "name": "Listar regras automáticas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/automatic-rules?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&scope=transactions&active=false&sort=position&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules" ], "query": [ { "key": "company_id", "value": "62057dab-0f98-4020-ae1e-2c0803251b1e", "disabled": true }, { "key": "scope", "value": "transactions", "disabled": true }, { "key": "active", "value": "false", "disabled": true }, { "key": "sort", "value": "position", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of automatic (classification) rules for the workspace tied to the token's `sub` claim. Rules fire on freshly-created transactions/billings, first-match-wins within `(company, scope, position)`. Default order is the evaluation order `(company, scope, position)`. Requires scope `finance.automatic_rules`." }, "response": [] }, { "name": "Criar regra automática", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/automatic-rules", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"scope\": \"transactions\",\n \"active\": false,\n \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"transaction_type\": \"debit\",\n \"match_person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"description_contains\": \"\",\n \"notes_contains\": \"\",\n \"set_description\": \"\",\n \"set_person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_expected_account_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a rule and appends it at the end of its `(company, scope)` group (`position` = next). Requires scope `finance.automatic_rules.write`. `workspace_id` comes from the token. A rule needs at least one criterion and at least one action; `account_id` is only valid for `scope=transactions` and `set_expected_account_id` only for `scope=billings`. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter regra automática por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/automatic-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.automatic_rules`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar regra automática", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/automatic-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"active\": false,\n \"account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"transaction_type\": \"debit\",\n \"match_person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"description_contains\": \"\",\n \"notes_contains\": \"\",\n \"set_description\": \"\",\n \"set_person_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_category_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_classification_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"set_expected_account_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update of criteria/actions and `active`. Requires scope `finance.automatic_rules.write`. `scope` and `company_id` are immutable (delete + recreate to move a rule); `position` is changed via `POST /automatic-rules/reorder`. The merged rule must still have at least one criterion and one action." }, "response": [] }, { "name": "Excluir regra automática", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/automatic-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Hard-deletes a rule. Requires scope `finance.automatic_rules.write`. Surviving rules keep their positions (a gap is left — reorder to compact). Calling DELETE twice returns 204 then 404." }, "response": [] }, { "name": "Reordenar regras automáticas", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/automatic-rules/reorder", "host": [ "{{baseUrl}}" ], "path": [ "automatic-rules", "reorder" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"scope\": \"transactions\",\n \"ordered_ids\": [\n \"00000000-0000-0000-0000-000000000000\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Rewrites `position` for one `(company_id, scope)` group so it matches `ordered_ids` (first → position 1). Requires scope `finance.automatic_rules.write`. `ordered_ids` must be the COMPLETE ordered set for that group — a partial or foreign set is rejected (422). Idempotent via `X-Idempotency-Key`. Returns 204." }, "response": [] } ] }, { "name": "Bancos", "item": [ { "name": "Listar bancos", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/banks?code=341&name=Itaú Unibanco S.A.&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "banks" ], "query": [ { "key": "code", "value": "341", "disabled": true }, { "key": "name", "value": "Itaú Unibanco S.A.", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of the global bank catalog (COMPE/BACEN codes). Requires scope `finance.banks`. Tenant-less reference data — every token sees the same rows. Defaults to alphabetical sort by `name`." }, "response": [] } ] }, { "name": "Fluxo de Caixa", "item": [ { "name": "Obter a projeção de fluxo de caixa", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/cash-flow?from=2026-01-01&to=2026-12-31&granularity=day&company_id=00000000-0000-0000-0000-000000000000&account_id=00000000-0000-0000-0000-000000000000&tz=", "host": [ "{{baseUrl}}" ], "path": [ "cash-flow" ], "query": [ { "key": "from", "value": "2026-01-01", "disabled": false }, { "key": "to", "value": "2026-12-31", "disabled": false }, { "key": "granularity", "value": "day", "disabled": true }, { "key": "company_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "account_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "tz", "value": "", "disabled": true } ] }, "description": "Returns the cash-flow projection for the workspace tied to the token: a series of time buckets (realised + projected income/expenses, running balance) plus `current_balance`, the `today_bucket` seam and `retroactive_overdue`. Requires scope `finance.cash_flow`. Read-only." }, "response": [] } ] }, { "name": "Categorias", "item": [ { "name": "Listar categorias", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/categories?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&parent_id=00000000-0000-0000-0000-000000000000&type=debit&level=1&name=Aluguel&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "categories" ], "query": [ { "key": "company_id", "value": "62057dab-0f98-4020-ae1e-2c0803251b1e", "disabled": true }, { "key": "parent_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "type", "value": "debit", "disabled": true }, { "key": "level", "value": "1", "disabled": true }, { "key": "name", "value": "Aluguel", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of categories for the workspace tied to the token's `sub` claim. Company-scoped within the workspace; categories form a tree via `parent_id` but are returned flat — build the tree client-side using `parent_id` and `level`. Requires scope `finance.categories`." }, "response": [] }, { "name": "Criar categoria", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/categories", "host": [ "{{baseUrl}}" ], "path": [ "categories" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"\",\n \"type\": \"debit\",\n \"parent_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a category. Requires scope `finance.categories.write`. `workspace_id` is taken from the token. Omit `parent_id` for a root (`level` 1); when set, the server derives `level = parent.level + 1` (max depth 3) and requires `type` to match the parent. The response is flat (`parent_id` + `level`). Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter categoria por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "categories", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.categories`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar categoria", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "categories", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"type\": \"debit\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update of `name` and `type` only. Requires scope `finance.categories.write`. Re-parenting is not supported via v1. Changing a parent's `type` cascades to all descendants (internal behavior)." }, "response": [] }, { "name": "Excluir categoria", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "categories", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes a category. Requires scope `finance.categories.write`. Returns 422 (`reason: has_children`) while the category still has subcategories — delete the children first. For a leaf, references on transactions / payables / receivables are set to null and the row is removed. Calling DELETE twice returns 204 then 404." }, "response": [] } ] }, { "name": "Empresas", "item": [ { "name": "Listar empresas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/companies?active=true&type=matriz&cnpj=12345678000190&name=ACME Comércio Ltda&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "companies" ], "query": [ { "key": "active", "value": "true", "disabled": true }, { "key": "type", "value": "matriz", "disabled": true }, { "key": "cnpj", "value": "12345678000190", "disabled": true }, { "key": "name", "value": "ACME Comércio Ltda", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of companies for the workspace tied to the token's `sub` claim. Requires scope `finance.companies`. Catalogal entity — defaults to alphabetical sort by `name`." }, "response": [] }, { "name": "Criar empresa", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/companies", "host": [ "{{baseUrl}}" ], "path": [ "companies" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"ACME Comércio Ltda\",\n \"cnpj\": \"12345678000190\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a company. Requires scope `finance.companies.write`. **`cnpj` is required and validated** with the standard BR check-digit algorithm — a missing, invalid, or document-less value returns 422 (there is no pessoa-física / document-less company in this API; a migrating client whose source row has no CNPJ must supply one). The CNPJ must be unique among active companies in the workspace (duplicate → 409). `type` (matriz/filial) is derived server-side from the CNPJ branch digits and is never read from the request. `active` starts `true`. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter empresa por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/companies/:id", "host": [ "{{baseUrl}}" ], "path": [ "companies", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.companies`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar empresa", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/companies/:id", "host": [ "{{baseUrl}}" ], "path": [ "companies", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update of `name` and `active`. Requires scope `finance.companies.write`. The CNPJ (and the `type` it derives) is immutable via the public API — send `active: false` to soft-deactivate." }, "response": [] }, { "name": "Excluir empresa", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/companies/:id", "host": [ "{{baseUrl}}" ], "path": [ "companies", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Hard-deletes a company. Requires scope `finance.companies.write`. Blocked with 409 (`details` carries the per-table counts `{ transactions, payables, receivables, people }`) when the company still has financial records or active people — remove or reassign those first, or soft-deactivate via `PATCH { active: false }`. Config tables (categories, classification centers, financial accounts, soft-deleted people) cascade automatically. Calling DELETE twice returns 204 then 404." }, "response": [] } ] }, { "name": "Centros de classificação", "item": [ { "name": "Listar centros de classificação", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/classification_centers?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&active=true&type=cost&name=Operacional&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "classification_centers" ], "query": [ { "key": "company_id", "value": "62057dab-0f98-4020-ae1e-2c0803251b1e", "disabled": true }, { "key": "active", "value": "true", "disabled": true }, { "key": "type", "value": "cost", "disabled": true }, { "key": "name", "value": "Operacional", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of classification centers for the workspace tied to the token's `sub` claim. Company-scoped within the workspace — pass `?company_id=…` to narrow. Requires scope `finance.cost_centers`." }, "response": [] }, { "name": "Criar centro de classificação", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/classification_centers", "host": [ "{{baseUrl}}" ], "path": [ "classification_centers" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"\",\n \"type\": \"cost\",\n \"description\": \"\",\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a classification center. Requires scope `finance.cost_centers.write`. `workspace_id` is taken from the token. `type` (`cost` / `revenue`) drives the rateio polarity. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter centro de classificação por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/classification_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "classification_centers", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.cost_centers`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar centro de classificação", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/classification_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "classification_centers", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"type\": \"cost\",\n \"description\": \"\",\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update of `name`, `type`, `description`, `active`. Requires scope `finance.cost_centers.write`. Send `description: null` to clear it, or `active: false` to soft-deactivate (existing references are preserved)." }, "response": [] }, { "name": "Excluir centro de classificação", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/classification_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "classification_centers", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes a classification center. Requires scope `finance.cost_centers.write`. Returns 422 (`reason: in_use`, with a `usage` breakdown) when the classification center is referenced by a rateio allocation, billing or transaction — soft-deactivate via `PATCH { active: false }` instead. Calling DELETE twice returns 204 then 404." }, "response": [] } ] }, { "name": "Pessoas", "item": [ { "name": "Listar IDs de pessoas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/people/ids?limit=&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "people", "ids" ], "query": [ { "key": "limit", "value": "", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Every person id the token can see. Requires scope `finance.people`. Pairs with `?updated_at[gte]=` on the listing. The delta reports what changed; this reports what still exists. A delta can never report a disappearance — the row it would have to describe is gone — so an id that stops appearing here is the only signal that something left. Diff this set against your mirror and drop what is missing. Takes no filters: the sweep must cover exactly what the listing shows, and a filter applied here but not to your mirror would read as mass deletion. People are soft-deleted, so a removed person's row survives internally — but it is filtered out of every v1 read, including this one, which makes its absence here the deletion signal." }, "response": [] }, { "name": "Listar pessoas (clientes / fornecedores)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/people?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&kind=natural&is_customer=true&is_supplier=true&active=true&document_number=12345678901&name=&updated_at=&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "people" ], "query": [ { "key": "company_id", "value": "62057dab-0f98-4020-ae1e-2c0803251b1e", "disabled": true }, { "key": "kind", "value": "natural", "disabled": true }, { "key": "is_customer", "value": "true", "disabled": true }, { "key": "is_supplier", "value": "true", "disabled": true }, { "key": "active", "value": "true", "disabled": true }, { "key": "document_number", "value": "12345678901", "disabled": true }, { "key": "name", "value": "", "disabled": true }, { "key": "updated_at", "value": "", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of people for the workspace tied to the token's `sub` claim. Soft-deleted rows are never returned. Company-scoped within the workspace — `?company_id=…` narrows. Sensitive fields (bank/PIX info, addresses, custom_data, birthday) are intentionally excluded from this endpoint. Requires scope `finance.people`." }, "response": [] }, { "name": "Criar pessoa (cliente / fornecedor)", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/people", "host": [ "{{baseUrl}}" ], "path": [ "people" ] }, "body": { "mode": "raw", "raw": "{\n \"company_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"\",\n \"legal_name\": \"\",\n \"nickname\": \"\",\n \"kind\": \"natural\",\n \"document_type\": \"cpf\",\n \"document_number\": \"\",\n \"is_customer\": false,\n \"is_supplier\": false,\n \"active\": false,\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a person. Requires scope `finance.people.write`. `workspace_id` is always taken from the token. Set `is_customer` / `is_supplier` to make the row referenceable by receivables / payables. `document_number` (CPF 11 digits / CNPJ 14 digits) is validated and stored numeric-only; `document_type` is inferred from the length when omitted. Contact details (`emails` / `phones`), addresses, and bank/PIX coordinates are not yet writable via v1. Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter pessoa por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/people/:id", "host": [ "{{baseUrl}}" ], "path": [ "people", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Soft-deleted rows return 404 — same `deleted_at IS NULL` filter as the listing. Returns the same shape as the rows from the list endpoint. Requires scope `finance.people`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar pessoa", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/people/:id", "host": [ "{{baseUrl}}" ], "path": [ "people", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"legal_name\": \"\",\n \"nickname\": \"\",\n \"kind\": \"natural\",\n \"document_type\": \"cpf\",\n \"document_number\": \"\",\n \"is_customer\": false,\n \"is_supplier\": false,\n \"active\": false,\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update. Only fields present in the body are written; non-writable fields (`emails`, `phones`, bank/PIX, `id`, `workspace_id`, `company_id`, `created_at`) are dropped. Requires scope `finance.people.write`. Sending `null` for an optional string field is a no-op (clearing to null is not supported via v1). The CPF/CNPJ is re-validated only when `document_number` / `document_type` actually changes — re-sending the stored value verbatim (even a legacy/invalid one) is accepted so unrelated edits aren't blocked. A `document_type` sent on its own is rejected with 422 when it contradicts the stored number's digit count (e.g. tagging an 11-digit number as `cnpj`)." }, "response": [] }, { "name": "Excluir pessoa", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/people/:id", "host": [ "{{baseUrl}}" ], "path": [ "people", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Soft-deletes the person (sets `deleted_at`). Requires scope `finance.people.write`. Existing payables / receivables / transactions referencing the person stay valid — the row just stops surfacing in listings and lookups. Calling DELETE twice returns 204 then 404 (Stripe-style). Refused with 409 while a classification rule still references the person (as match criterion or set action) — edit or remove the rule first." }, "response": [] } ] }, { "name": "Conciliações", "item": [ { "name": "Criar conciliação", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/reconciliations", "host": [ "{{baseUrl}}" ], "path": [ "reconciliations" ] }, "body": { "mode": "raw", "raw": "{\n \"billings\": [\n {\n \"kind\": \"payable\",\n \"id\": \"00000000-0000-0000-0000-000000000000\"\n }\n ],\n \"transaction_ids\": [\n \"00000000-0000-0000-0000-000000000000\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Reconciles billings against bank transactions (n:m), settling every billing (paid/received). Requires scope `finance.reconciliations.write`. All billings must share one polarity and one company; transaction polarity must match (payable↔debit, receivable↔credit). A billing already reconciled/linked, cancelled or draft is rejected (422). Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter conciliação por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reconciliations/:id", "host": [ "{{baseUrl}}" ], "path": [ "reconciliations", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Returns the reconciliation's light id-list shape (`source`, `kind`, `billing_ids`, `transaction_ids`). Requires scope `finance.reconciliations`. 404 when not in the tenant." }, "response": [] }, { "name": "Excluir conciliação", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/reconciliations/:id", "host": [ "{{baseUrl}}" ], "path": [ "reconciliations", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Dissolves a `manual` reconciliation: reverts every member billing to pending and clears the links. Requires scope `finance.reconciliations.write`. Imported (`fintera`) reconciliations are read-only → 422." }, "response": [] } ] }, { "name": "Impostos", "item": [ { "name": "Listar impostos", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/taxes?active=true&default_withholding=true&name=IRRF&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "taxes" ], "query": [ { "key": "active", "value": "true", "disabled": true }, { "key": "default_withholding", "value": "true", "disabled": true }, { "key": "name", "value": "IRRF", "disabled": true }, { "key": "sort", "value": "name", "disabled": true }, { "key": "limit", "value": "25", "disabled": true }, { "key": "cursor", "value": "", "disabled": true } ] }, "description": "Returns a cursor-paginated page of tax kinds for the workspace tied to the token's `sub` claim. Requires scope `finance.taxes`. Catalogal entity — defaults to alphabetical sort by `name`." }, "response": [] }, { "name": "Criar imposto", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/taxes", "host": [ "{{baseUrl}}" ], "path": [ "taxes" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"IRRF\",\n \"default_rate\": \"1.50\",\n \"default_withholding\": false,\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates a tax kind. Requires scope `finance.taxes.write`. Workspace-scoped (no company). `name` is unique per workspace (duplicate → 409). `default_rate` is a percent string (0–100). Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter imposto por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/taxes/:id", "host": [ "{{baseUrl}}" ], "path": [ "taxes", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": " Returns the same shape as the rows from the list endpoint. Requires scope `finance.taxes`. 404 covers both \"doesn't exist\" and \"not in the tenant\" — the API does not distinguish." }, "response": [] }, { "name": "Atualizar imposto", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/taxes/:id", "host": [ "{{baseUrl}}" ], "path": [ "taxes", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"IRRF\",\n \"default_rate\": \"1.50\",\n \"default_withholding\": false,\n \"active\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Partial update of `name`, `default_rate`, `default_withholding`, `active`. Requires scope `finance.taxes.write`. Send `default_rate: null` to clear it, or `active: false` to soft-deactivate." }, "response": [] }, { "name": "Excluir imposto", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/taxes/:id", "host": [ "{{baseUrl}}" ], "path": [ "taxes", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes a tax. Requires scope `finance.taxes.write`. Returns 422 (`reason: in_use`, with the referencing payable/receivable ids) when the tax still has charges — soft-deactivate via `PATCH { active: false }` instead. Calling DELETE twice returns 204 then 404." }, "response": [] } ] }, { "name": "Transferências", "item": [ { "name": "Criar transferência", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "type": "text", "disabled": true }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/transfers", "host": [ "{{baseUrl}}" ], "path": [ "transfers" ] }, "body": { "mode": "raw", "raw": "{\n \"from_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"to_account_id\": \"00000000-0000-0000-0000-000000000000\",\n \"amount\": \"1500.00\",\n \"occurred_at\": \"2026-01-01T00:00:00Z\",\n \"competence_date\": \"2026-01-01T00:00:00Z\",\n \"description\": \"Aporte para conta pagamentos\",\n \"notes\": \"\",\n \"is_pending\": false\n}", "options": { "raw": { "language": "json" } } }, "description": "Creates an account-to-account transfer as a linked debit/credit pair sharing one `transfer_id`. Requires scope `finance.transactions.write`. The two accounts must differ, both must belong to the tenant, and both must have a linked company (cross-company is allowed). Pass an `X-Idempotency-Key` header on retries." }, "response": [] }, { "name": "Obter transferência por ID", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/transfers/:id", "host": [ "{{baseUrl}}" ], "path": [ "transfers", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Returns the linked debit/credit pair for a `transfer_id`. Requires scope `finance.transactions`. 404 when the transfer is not in the tenant." }, "response": [] } ] } ] }