{ "info": { "name": "API de Financeiro Inteligente (v1.0.0) — Español", "description": "¡Eh, dev, diviértete! ✨\n\n> **Índice de la documentación** — accede al índice completo en [https://docs.finance.kobana.com.br/llms.txt](https://docs.finance.kobana.com.br/llms.txt). Usa este archivo para descubrir todas las páginas disponibles antes de empezar a explorar.\n\n## Autenticación\n\nLa API usa **Bearer JWT (HS512)**. Envía el token en la cabecera de cada solicitud:\n\n```\nAuthorization: Bearer \n```\n\nPara pruebas en línea de comandos, exporta el token: `export KOBANA_TOKEN=xxxxxxxx` y pega los comandos de la documentación directamente en tu terminal.\n\n## Formato\n\nLa API solo acepta el formato `JSON`. Todas las solicitudes deben usar `Content-Type: application/json`. Todas las respuestas usan `snake_case`.\n\n| Tipo de Campo | Formato |\n| :--- | :--- |\n| **DateTime** | Formato [ISO8601](https://es.wikipedia.org/wiki/ISO_8601). Ejemplos — Fecha: `2026-01-24`. Fecha y hora: `2026-01-24T10:07:00.000Z` |\n| **Money** | Decimal como cadena con 2 decimales (`\"150.00\"`). Siempre positivo — la dirección la indica el campo `type` (`debit`/`credit`) o el contexto (payable/receivable). |\n| **UUID** | Identificadores de recursos en formato UUID v4 |\n\n## Convenciones\n\nConvenciones usadas en esta documentación:\n\n| Convención | Descripción |\n| :--- | :--- |\n| **`:id`** | Parámetro de path que debe reemplazarse por el UUID del recurso. |\n| **`#{variable}`** | Un valor de tu cuenta que debe sustituirse en el ejemplo. |\n| **`...`** | Contenido de la respuesta truncado para facilitar la lectura. |\n| **`$KOBANA_TOKEN`** | Token JWT de acceso. Expórtalo con `export KOBANA_TOKEN=xxxxxxxx`. |\n\n## Entornos\n\n| Entorno | Base URL |\n| :--- | :--- |\n| **Producción** | `https://api.finance.kobana.com.br/v1` |\n| **Sandbox** | `https://api.finance.sandbox.kobana.com.br/v1` |\n\n## Códigos de Retorno\n\nLa API devuelve códigos HTTP estándar:\n\n| | Código | Descripción |\n| :--- | :--- | :--- |\n| ✅ | **200 OK** | Solicitud exitosa con cuerpo de respuesta. |\n| ✅ | **201 Created** | Recurso creado con éxito. |\n| ✅ | **204 No Content** | Solicitud exitosa, sin cuerpo de respuesta. |\n| ❌ | **400 Bad Request** | Solicitud inválida, normalmente un cuerpo mal formado. |\n| ❌ | **401 Unauthorized** | Token ausente, inválido o expirado. |\n| ❌ | **403 Forbidden** | Alcance insuficiente para la operación. |\n| ❌ | **404 Not Found** | Recurso no encontrado o fuera del workspace. |\n| ❌ | **422 Unprocessable Entity** | Solicitud válida, pero los datos enviados no lo son. |\n| ❌ | **429 Too Many Requests** | Límite de solicitudes alcanzado. |\n| ❌ | **500 Internal Server Error** | Error interno de procesamiento. Consulta el [estado de los servidores](https://status.kobana.com.br). |\n\n## Listado y Paginación\n\nTodos los endpoints de listado usan **paginación por cursor**:\n\n```\nGET /v1/payables?cursor=&limit=25\n```\n\nLa respuesta incluye `meta.next_cursor` — pásalo como `?cursor=` en la siguiente solicitud para obtener la página siguiente. Cuando `meta.next_cursor` es `null`, no hay más páginas.\n\n## Idempotencia\n\nLas operaciones de creación (`POST`) aceptan la cabecera `X-Idempotency-Key`. Los reenvíos con la misma clave devuelven el resultado original sin crear duplicados — seguro para reintentar ante un fallo de red.\n\n```\nX-Idempotency-Key: \n```\n\n## ID de las Solicitudes (Request ID)\n\nCada solicitud tiene un identificador asociado, disponible en la cabecera `Request-Id` de la respuesta. Este valor ayuda en la depuración y auditoría. El registro de solicitudes se conserva durante **30 días**. Al abrir un ticket de soporte sobre una solicitud específica, indica el `Request-Id` para acelerar la investigación.\n\n## Seguridad\n\nLa API usa certificados **SSL de 2048 bits**. Toda solicitud debe hacerse vía **HTTPS** — las llamadas al puerto 80 se redirigen al 443.\n\nLos clientes deben admitir `TLSv1.2` o `TLSv1.3` con una de las siguientes 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` y `TLSv1.1` no son compatibles.\n\n## Caché HTTP\n\nUsa las cabeceras HTTP de caché para reducir carga y ganar velocidad. La mayoría de las respuestas incluyen `ETag` y/o `Last-Modified` — almacena estos valores y reenvíalos en las siguientes solicitudes mediante `If-None-Match` e `If-Modified-Since`. Si el recurso no cambió, la respuesta será `304 Not Modified`, sin cuerpo y sin reprocesamiento.\n\n## Manejo de Errores\n\nLos errores 5xx indican fallos del servidor: **500 Internal Server Error** (aplicación no disponible), **502 Bad Gateway**, **503 Service Unavailable** y **504 Gateway Timeout** (fallos puntuales de infraestructura). Tu aplicación debe identificar estos códigos y reprogramar la solicitud tras unos minutos con backoff exponencial. Estado de los servidores: [https://status.kobana.com.br](https://status.kobana.com.br).\n\n## Spec OpenAPI\n\nImporta la spec en Postman o Insomnia para tener una colección lista que siempre refleja la API actual:\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": "Cuentas Financieras", "item": [ { "name": "Listar cuentas financieras", "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": "Crear cuenta financiera", "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": "Obtener cuenta financiera 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": "Actualizar cuenta financiera", "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": "Eliminar cuenta financiera", "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 de la cuenta", "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": "Cuentas por Pagar", "item": [ { "name": "Sumar totales de cuentas por 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 cuentas por 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 cuentas por 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": "Crear cuenta por 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": "Obtener cuenta por 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": "Actualizar o liquidar cuenta por 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": "Eliminar cuenta por 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 cuenta por pagar al 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 el envío al 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": "Cuentas por Cobrar", "item": [ { "name": "Sumar totales de cuentas por cobrar", "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 cuentas por cobrar", "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 cuentas por cobrar", "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": "Crear cuenta por cobrar", "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": "Obtener cuenta por cobrar 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": "Actualizar o liquidar cuenta por cobrar", "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": "Eliminar cuenta por cobrar", "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": "Transacciones Financieras", "item": [ { "name": "Sumar totales de transacciones", "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 transacciones", "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 transacciones", "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": "Crear transacción", "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": "Actualizar transacción", "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": "Eliminar transacción", "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": "Obtener transacción 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": "Adjuntos", "item": [ { "name": "Listar adjuntos", "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": "Subir adjunto", "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": "Descargar bytes del adjunto", "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": "Obtener metadatos del adjunto 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": "Eliminar adjunto", "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 adjunto a un 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 adjunto de un 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": "Reglas Automáticas", "item": [ { "name": "Listar reglas 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": "Crear regla 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": "Obtener regla 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": "Actualizar regla 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": "Eliminar regla 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 reglas 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": "Flujo de Caja", "item": [ { "name": "Obtener la proyección de flujo de caja", "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": "Categorías", "item": [ { "name": "Listar categorías", "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": "Crear categoría", "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": "Obtener categoría 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": "Actualizar categoría", "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": "Eliminar categoría", "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": "Crear 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": "Obtener 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": "Actualizar 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": "Eliminar 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 clasificación", "item": [ { "name": "Listar centros de clasificación", "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": "Crear centro de clasificación", "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": "Obtener centro de clasificación 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": "Actualizar centro de clasificación", "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": "Eliminar centro de clasificación", "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": "Personas", "item": [ { "name": "Listar IDs de personas", "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 personas (clientes / proveedores)", "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": "Crear persona (cliente / proveedor)", "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": "Obtener persona 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": "Actualizar persona", "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": "Eliminar persona", "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": "Conciliaciones", "item": [ { "name": "Crear conciliación", "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": "Obtener conciliación 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": "Eliminar conciliación", "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": "Impuestos", "item": [ { "name": "Listar impuestos", "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": "Crear impuesto", "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": "Obtener impuesto 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": "Actualizar impuesto", "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": "Eliminar impuesto", "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": "Transferencias", "item": [ { "name": "Crear transferencia", "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": "Obtener transferencia 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": [] } ] } ] }