{ "info": { "name": "API do Financeiro Inteligente (v1.0.0)", "description": "Public REST API for Kobana Financeiro Inteligente. Authenticated via Bearer JWT (HS512) — send `Authorization: Bearer ` on every request.\n\n**Using this spec in Postman / Insomnia:** import this spec URL (`/api/v1/openapi.yaml` or `/api/v1/openapi.json`) to get a ready-to-use collection. Re-importing always reflects the current API — no separately-maintained collection to fall out of date.", "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": "Accounts", "item": [ { "name": "List financial accounts", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/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": [ "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": "Create a financial account", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/accounts", "host": [ "{{baseUrl}}" ], "path": [ "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 \"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. Pass an `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a financial account by id", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "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": "Update a financial account", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "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 \"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)." }, "response": [] }, { "name": "Delete a financial account", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/accounts/:id", "host": [ "{{baseUrl}}" ], "path": [ "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": "Attachments", "item": [ { "name": "List attachments", "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": "Upload an attachment", "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 `Idempotency-Key` support on upload." }, "response": [] }, { "name": "Download attachment bytes", "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": "Get attachment metadata by 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": "Delete an attachment", "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": "Link an attachment to a record", "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": "Unlink an attachment from a record", "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": "Categories", "item": [ { "name": "List categories", "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": "Create a category", "request": { "method": "POST", "header": [ { "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 `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a category by 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": "Update a category", "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": "Delete a category", "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": "Companies", "item": [ { "name": "List companies", "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": "Create a company", "request": { "method": "POST", "header": [ { "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 `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a company by 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": "Update a company", "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": "Delete a company", "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, cost centers, financial accounts, payment methods, soft-deleted people) cascade automatically. Calling DELETE twice returns 204 then 404." }, "response": [] } ] }, { "name": "CostCenters", "item": [ { "name": "List cost centers", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/cost_centers?company_id=62057dab-0f98-4020-ae1e-2c0803251b1e&active=true&type=cost&name=Operacional&sort=name&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "cost_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 cost 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": "Create a cost center", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/cost_centers", "host": [ "{{baseUrl}}" ], "path": [ "cost_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 cost center. Requires scope `finance.cost_centers.write`. `workspace_id` is taken from the token. `type` (`cost` / `revenue`) drives the rateio polarity. Pass an `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a cost center by id", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/cost_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "cost_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": "Update a cost center", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/cost_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "cost_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": "Delete a cost center", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/cost_centers/:id", "host": [ "{{baseUrl}}" ], "path": [ "cost_centers", ":id" ], "variable": [ { "key": "id", "value": "00000000-0000-0000-0000-000000000000" } ] }, "description": "Deletes a cost center. Requires scope `finance.cost_centers.write`. Returns 422 (`reason: in_use`, with a `usage` breakdown) when the cost 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": "Payables", "item": [ { "name": "List payables", "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&cost_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=&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": "cost_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": "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`, `cost_center_name`) and aggregate counts (`tax_charges_count`, `cost_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. Requires scope `finance.payables`." }, "response": [] }, { "name": "Create a payable", "request": { "method": "POST", "header": [ { "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_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 \"cost_centers\": [\n {\n \"cost_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 / cost_center) is find-or-create; sending both `*_id` and `*_name` for the same FK returns 400. `cost_centers[]` (rateio) and `tax_charges[]` are accepted; the rateio Σ is validated against `amount`. Pass an `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a payable by 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: `cost_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": "Update or settle a payable", "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_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 \"cost_centers\": [\n {\n \"cost_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": "Delete a payable", "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": "People", "item": [ { "name": "List people (customers / suppliers)", "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=&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": "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": "Create a person (customer / supplier)", "request": { "method": "POST", "header": [ { "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 `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a person by 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": "Update a person", "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)." }, "response": [] }, { "name": "Delete a person", "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)." }, "response": [] } ] }, { "name": "Receivables", "item": [ { "name": "List receivables", "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&cost_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=&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": "cost_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": "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": "Create a receivable", "request": { "method": "POST", "header": [ { "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_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 \"cost_centers\": [\n {\n \"cost_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 / cost_center) is find-or-create (customer/credit/revenue polarity); sending both `*_id` and `*_name` for the same FK returns 400. `cost_centers[]` (rateio) and `tax_charges[]` are accepted. Pass an `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a receivable by 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 `cost_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": "Update or settle a receivable", "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_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 \"cost_centers\": [\n {\n \"cost_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": "Delete a receivable", "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": "Taxes", "item": [ { "name": "List tax kinds", "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": "Create a tax kind", "request": { "method": "POST", "header": [ { "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 `Idempotency-Key` header on retries." }, "response": [] }, { "name": "Get a tax kind by 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": "Update a tax kind", "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": "Delete a tax kind", "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": "Transactions", "item": [ { "name": "List transactions", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/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&cost_center_id=00000000-0000-0000-0000-000000000000&occurred_at=2026-01-01&amount=100.00&sort=occurred_at&limit=25&cursor=", "host": [ "{{baseUrl}}" ], "path": [ "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": "cost_center_id", "value": "00000000-0000-0000-0000-000000000000", "disabled": true }, { "key": "occurred_at", "value": "2026-01-01", "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": "Create a transaction", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/transactions", "host": [ "{{baseUrl}}" ], "path": [ "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_center_name\": \"\",\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 / cost_center) for CSV-importer ergonomics; sending both for the same FK returns 400. Pass an `Idempotency-Key` header on retries to avoid duplicate inserts." }, "response": [] }, { "name": "Update a transaction", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{baseUrl}}/transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "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 \"cost_center_id\": \"00000000-0000-0000-0000-000000000000\",\n \"cost_center_name\": \"\",\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": "Delete a transaction", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "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": "Get a transaction by id", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/transactions/:id", "host": [ "{{baseUrl}}" ], "path": [ "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": [] } ] } ] }