> ## Documentation Index > Fetch the complete documentation index at: https://docs.finsync.ar/llms.txt > Use this file to discover all available pages before exploring further. # Create a new operation (up/down/other/exchange/budget) > Creates a new operation. Supports UP/DOWN, OTHER, EXCHANGE, and BUDGET (centros de resultados) operations. Optional `date` (ISO timestamp or YYYY-MM-DD) sets Operation.date and each created Transaction.created_at/updated_at the same way as the dashboard with-transactions path; omit it to use NOW(). Exchange operations have dedicated internal/external payloads: internal exchanges require explicit account IDs, while external exchanges require an external client and currencies so accounts can be resolved or created automatically. OTHER already accepts two internal (type=0) legs for same-currency internal transfers. Budget operations require cost_center_id + amount; direction defaults to expense. payment_source / payment_source_mode defaults to internal (caja) and then also requires internal_account_id. Expense+external credits payer_client_id (type=1, not the center client) and does not require or debit caja. Income stays caja + optional payer_client_id. Optional `counterparty_client_id` is a soft Client link (customer or supplier) that does not create transactions or change that party's balances. Optionally pass `external_transaction_id` (your own reference) to detect duplicate creates after network retries. ## OpenAPI ````yaml /docs/openapi.json post /api/operations openapi: 3.0.0 info: title: FinSync API Documentation version: 1.0.0 description: API documentation for FinSync application contact: name: FinSync Support email: support@finsync.com servers: - url: https://api.finsync.ar description: Direct Fly API (preferred for API keys and webhooks) - url: https://finsync.ar description: Same-origin via finsync.ar (Vercel rewrite) security: - apiKey: [] tags: - name: Clients description: Operations related to clients and their accounts - name: Tags description: >- Company-scoped client labels (Configuración > Etiquetas). Distinct from the special Centro de resultados / Centro de costos tag used for budget clients. - name: Accounts description: Operations related to account balances - name: Cost Centers description: Company centros de resultados (cost_center_id) and their budgets - name: Operations description: Operations for creating and managing financial operations - name: Operation Types description: Company operation types management - name: Transaction Types description: Company transaction types management - name: WhatsApp Tools description: >- Company-scoped WhatsApp bot operation tools (Configuración > WhatsApp > Tools). Same WhatsAppOperationTool rows as the dashboard. Authenticate with x-api-key. - name: External client description: >- Exports for external (portal-linked) clients. Authenticate with `x-api-key` (company-owned client ID) or `Authorization: Bearer` (Auth.js session for an ExternalAccessGrant). - name: Mesas description: >- Company FX trading desks (mesas). Same records and paths as the dashboard Mesas module. Integrators authenticate with x-api-key; the dashboard uses an employee session. Superadmin must set mesas_enabled first; there is no public PATCH for that flag. created_by / opened_by / closed_by are null for API-key callers. - name: Home metrics description: >- Named dashboard home metrics (list + values). API keys receive the Métricas-group cards (day P&L, commissions, cost centers) without the metrics-password cookie. Employee sessions need the matching view permission; they still skip the UI password gate on this surface. paths: /api/operations: post: tags: - Operations summary: Create a new operation (up/down/other/exchange/budget) description: >- Creates a new operation. Supports UP/DOWN, OTHER, EXCHANGE, and BUDGET (centros de resultados) operations. Optional `date` (ISO timestamp or YYYY-MM-DD) sets Operation.date and each created Transaction.created_at/updated_at the same way as the dashboard with-transactions path; omit it to use NOW(). Exchange operations have dedicated internal/external payloads: internal exchanges require explicit account IDs, while external exchanges require an external client and currencies so accounts can be resolved or created automatically. OTHER already accepts two internal (type=0) legs for same-currency internal transfers. Budget operations require cost_center_id + amount; direction defaults to expense. payment_source / payment_source_mode defaults to internal (caja) and then also requires internal_account_id. Expense+external credits payer_client_id (type=1, not the center client) and does not require or debit caja. Income stays caja + optional payer_client_id. Optional `counterparty_client_id` is a soft Client link (customer or supplier) that does not create transactions or change that party's balances. Optionally pass `external_transaction_id` (your own reference) to detect duplicate creates after network retries. requestBody: required: true content: application/json: schema: oneOf: - title: UP/DOWN Operation type: object required: - operation_type_id - internal_account_id - external_client_id - internal_amount - external_amount - external_currency properties: operation_type_id: type: integer description: ID of the operation type (must be UP or DOWN type) description: type: string description: Optional operation description counterparty_client_id: type: integer minimum: 1 nullable: true description: >- Optional soft Client link (customer or supplier). Associates the operation with that party without creating transactions, ledger rows, or balance changes on their accounts. Omit for backward compatibility. date: type: string format: date-time description: >- Optional operation date (ISO timestamp or YYYY-MM-DD). Sets Operation.date and each created Transaction.created_at/updated_at. Omitted → NOW(). internal_account_id: type: integer description: ID of the internal account external_client_id: type: integer description: ID of the external client external_currency: type: string description: Currency for the external client account internal_amount: type: number minimum: 0.01 description: Amount for the internal transaction external_amount: type: number minimum: 0.01 description: Amount for the external transaction internal_description: type: string description: Optional description for internal transaction external_description: type: string description: Optional description for external transaction external_transaction_id: type: string maxLength: 200 description: >- Optional client reference for idempotent creates. Stored on the external transaction. Retries with the same value return 409 when a pending or completed operation already exists. commissions: type: array description: Optional array of commission transactions items: type: object required: - type - transaction_type_id properties: type: type: string enum: - fixed - percentage - both description: Type of commission calculation fixed_amount: type: number minimum: 0.01 description: >- Fixed commission amount (required if type is fixed or both) percentage: type: number minimum: 0.01 maximum: 100 description: >- Percentage commission (required if type is percentage or both) transaction_type_id: type: integer description: ID of the transaction type for this commission apply_to_account: type: string enum: - internal - external - third_party description: >- Legacy target. Use third_party with third_party_client_id to charge/pay a third party. target: type: string enum: - source - destination - third_party - thirdParty description: >- UI-style target alias. source/destination follow the UP/DOWN side mapping; thirdParty is accepted as an alias for third_party. percentage_base: type: string enum: - source - destination description: >- Amount side used as the percentage base. Defaults to the selected target, or destination for third-party commissions. third_party_client_id: type: integer description: >- External client identifier for third-party commissions. The API resolves it against Client.id first and then company_client_id. currency: type: string description: >- Currency for the third-party account. Required when applying a commission to third_party. description: type: string description: Optional commission description - title: OTHER Operation type: object required: - operation_type_id - transactions properties: operation_type_id: type: integer description: ID of the operation type (must be OTHER type) description: type: string description: Optional operation description counterparty_client_id: type: integer minimum: 1 nullable: true description: >- Optional soft Client link (customer or supplier). Associates the operation with that party without creating transactions, ledger rows, or balance changes on their accounts. Omit for backward compatibility. date: type: string format: date-time description: >- Optional operation date (ISO timestamp or YYYY-MM-DD). Sets Operation.date and each created Transaction.created_at/updated_at. Omitted → NOW(). external_transaction_id: type: string maxLength: 200 description: >- Optional client reference for idempotent creates. Stored on the first transaction. Retries with the same value return 409 when a pending or completed operation already exists. transactions: type: array description: Array of transactions (at least 1 required) minItems: 1 items: type: object required: - amount - transaction_type_id properties: client_id: type: integer description: >- Internal database client ID (use either this or company_client_id) company_client_id: type: integer description: >- Company's custom client ID (use either this or client_id) account_id: type: integer description: >- Required for internal clients (type=0). Must belong to the specified client. Two internal legs (debit one caja, credit another) are the supported same-currency internal transfer path. currency_name: type: string description: >- Required for external clients (type=1). Account will be auto-created if needed. amount: type: number minimum: 0.01 description: Transaction amount transaction_type_id: type: integer description: >- Company transaction type ID from CompanyTransactionTypes table (determines credit/debit) description: type: string description: Optional transaction description - title: Internal EXCHANGE Operation type: object required: - operation_type_id - client_mode - debit_account_id - credit_account_id - debit_amount - credit_amount properties: operation_type_id: type: integer description: ID of the operation type (must be EXCHANGE type) client_mode: type: string enum: - internal description: type: string description: Optional operation description counterparty_client_id: type: integer minimum: 1 nullable: true description: >- Optional soft Client link (customer or supplier). Associates the operation with that party without creating transactions, ledger rows, or balance changes on their accounts. Omit for backward compatibility. date: type: string format: date-time description: >- Optional operation date (ISO timestamp or YYYY-MM-DD). Sets Operation.date and each created Transaction.created_at/updated_at. Omitted → NOW(). debit_account_id: type: integer description: Internal source account ID credit_account_id: type: integer description: Internal destination account ID debit_amount: type: number minimum: 0.01 description: Amount debited from the source account credit_amount: type: number minimum: 0.01 description: Amount credited to the destination account debit_description: type: string description: Optional description for the debit side credit_description: type: string description: Optional description for the credit side external_transaction_id: type: string maxLength: 200 description: >- Optional client reference for idempotent creates. Stored on the debit transaction. Retries with the same value return 409 when a pending or completed operation already exists. commissions: type: array description: Optional exchange commissions items: type: object required: - type - target - transaction_type_id properties: type: type: string enum: - fixed - percentage - both fixed_amount: type: number minimum: 0.01 percentage: type: number minimum: 0.01 maximum: 100 percentage_base: type: string enum: - source - destination target: type: string enum: - source - destination - third_party transaction_type_id: type: integer third_party_client_id: type: integer third_party_company_client_id: type: integer currency: type: string description: Required when target is third_party description: type: string - title: External EXCHANGE Operation type: object required: - operation_type_id - client_mode - debit_currency - credit_currency - debit_amount - credit_amount properties: operation_type_id: type: integer description: ID of the operation type (must be EXCHANGE type) client_mode: type: string enum: - external description: type: string description: Optional operation description counterparty_client_id: type: integer minimum: 1 nullable: true description: >- Optional soft Client link (customer or supplier). Associates the operation with that party without creating transactions, ledger rows, or balance changes on their accounts. Omit for backward compatibility. date: type: string format: date-time description: >- Optional operation date (ISO timestamp or YYYY-MM-DD). Sets Operation.date and each created Transaction.created_at/updated_at. Omitted → NOW(). external_client_id: type: integer description: External client database ID external_company_client_id: type: integer description: External client company-specific ID debit_currency: type: string description: Currency sold by the external client credit_currency: type: string description: Currency bought by the external client debit_amount: type: number minimum: 0.01 description: Amount sold by the external client credit_amount: type: number minimum: 0.01 description: Amount bought by the external client debit_description: type: string description: Optional description for the debit side credit_description: type: string description: Optional description for the credit side external_transaction_id: type: string maxLength: 200 description: >- Optional client reference for idempotent creates. Stored on the debit transaction. Retries with the same value return 409 when a pending or completed operation already exists. commissions: type: array description: Optional exchange commissions items: type: object required: - type - target - transaction_type_id properties: type: type: string enum: - fixed - percentage - both fixed_amount: type: number minimum: 0.01 percentage: type: number minimum: 0.01 maximum: 100 percentage_base: type: string enum: - source - destination target: type: string enum: - source - destination - third_party transaction_type_id: type: integer third_party_client_id: type: integer third_party_company_client_id: type: integer currency: type: string description: Required when target is third_party description: type: string - title: BUDGET Operation type: object required: - operation_type_id - cost_center_id - amount properties: operation_type_id: type: integer description: >- ID of the operation type (must be type=budget). Resolve from GET /api/operation-types. cost_center_id: type: integer description: >- Company cost center / centro de resultados ID from GET /api/cost-centers internal_account_id: type: integer description: >- Required when payment_source is internal (default). Internal caja account. Expense debits it; income credits it. Omit for expense+external (no caja debit). amount: type: number minimum: 0.01 description: Positive amount for every leg direction: type: string enum: - expense - income default: expense description: >- Budget direction. Defaults to expense so existing callers stay unchanged. Income inverts caja/center legs. payment_source: type: string enum: - internal - external default: internal description: >- Alias of payment_source_mode. internal = caja (default, existing callers). external = credit a type=1 CC (expense only, no caja debit). Same planner as the dashboard Gastos form (paymentSourceMode). payment_source_mode: type: string enum: - internal - external default: internal description: >- Expense source: internal caja or external CC. Default internal so existing caja callers stay unchanged. Income is always internal. If both payment_source and payment_source_mode are sent they must match. date: type: string format: date-time description: >- Optional operation date (ISO timestamp or YYYY-MM-DD). Sets Operation.date and each created Transaction.created_at/updated_at. Omitted → NOW(). currency: type: string description: >- Optional. On internal source, must match the caja currency when provided (defaults to that account). On expense+external, defaults to the cost center default_currency. payer_client_id: type: integer description: >- Income: optional paying client (credit caja + debit this CC). Expense+external: required type=1 client that paid (credit their CC, no caja). Must not be the cost center client. Attribution stays on cost_center_id. net_balance: type: boolean description: >- When omitted, uses the cost center net_balance_by_default. Expense: extra debit on the center client. Income without payer: extra credit so the center client nets to 0. Income with payer_client_id: extra credit on the paying client (caja credit is kept; no center-client legs). description: type: string description: Optional operation description counterparty_client_id: type: integer minimum: 1 nullable: true description: >- Optional soft Client link (customer or supplier). Associates the operation with that party without creating transactions, ledger rows, or balance changes on their accounts. Omit for backward compatibility. external_transaction_id: type: string maxLength: 200 description: >- Optional client reference for idempotent creates. Stored on the first transaction. Retries with the same value return 409 when a pending or completed operation already exists. debit_transaction_type_id: type: integer description: >- Optional regular debit type. Defaults to the company's first regular debit type, same as the dashboard. credit_transaction_type_id: type: integer description: >- Optional regular credit type. Defaults to the company's first regular credit type, same as the dashboard. examples: upOperation: summary: Create UP operation value: operation_type_id: 1 description: UP operation example internal_account_id: 123 external_client_id: 456 internal_amount: 1000 external_amount: 1000 external_currency: USD internal_description: Débito desde cuenta principal external_description: Crédito para proveedor externo downOperation: summary: Create DOWN operation value: operation_type_id: 2 description: DOWN operation example internal_account_id: 123 external_client_id: 456 internal_amount: 1000 external_amount: 1000 external_currency: USD internal_description: Crédito recibido en caja external_description: Débito desde cliente externo otherOperationInternal: summary: Create OTHER operation (internal client) value: operation_type_id: 3 description: OTHER operation with internal client transactions: - client_id: 123 account_id: 456 amount: 500 transaction_type_id: 1 description: Internal transaction otherOperationExternal: summary: Create OTHER operation (external client) value: operation_type_id: 3 description: OTHER operation with external client transactions: - company_client_id: 42 currency_name: USD amount: 1000 transaction_type_id: 2 description: External transaction otherOperationMultiple: summary: Create OTHER operation (multiple transactions) value: operation_type_id: 3 description: Multi-transaction operation transactions: - client_id: 123 account_id: 456 amount: 500 transaction_type_id: 1 description: First internal transaction - company_client_id: 42 currency_name: USD amount: 500 transaction_type_id: 2 description: Second external transaction exchangeInternalOperation: summary: Create EXCHANGE operation (internal) value: operation_type_id: 4 client_mode: internal description: Cambio USD a EUR debit_account_id: 456 credit_account_id: 789 debit_amount: 1000 credit_amount: 920 debit_description: Debito USD credit_description: Credito EUR exchangeExternalOperation: summary: Create EXCHANGE operation (external) value: operation_type_id: 4 client_mode: external description: Cambio USD a EUR para cliente externo external_client_id: 456 debit_currency: USD credit_currency: EUR debit_amount: 1000 credit_amount: 920 debit_description: Cliente vende USD credit_description: Cliente compra EUR budgetExpenseInternal: summary: Create BUDGET expense (caja / office) value: operation_type_id: 12 cost_center_id: 4 internal_account_id: 101 amount: 1500 description: Gasto del centro budgetExpenseExternal: summary: Create BUDGET expense (cuenta corriente / personal) value: operation_type_id: 12 cost_center_id: 4 payment_source_mode: external payer_client_id: 88 amount: 1500 description: Gasto personal imputado al centro responses: '201': description: Operation created successfully content: application/json: schema: type: object properties: operation_id: type: integer description: ID of the created operation message: type: string description: Success message transactions: type: array description: List of created transaction IDs items: type: integer '400': description: >- Bad request - Invalid operation type, missing parameters, or validation error '401': description: Unauthorized - Missing or invalid API key '404': description: Not found - Operation type, account, or client not found '409': description: >- Conflict - external_transaction_id already used by a pending or completed operation content: application/json: schema: type: object properties: error: type: string external_transaction_id: type: string operation_id: type: integer status: type: string enum: - pending - completed '500': description: Server error security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: API Key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.