> ## 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) > Creates a new operation. Supports UP/DOWN operations, OTHER operations, and EXCHANGE operations. 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. Optionally pass `external_transaction_id` (your own reference) to detect duplicate creates after network retries. ## OpenAPI ````yaml /openapi/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://finsync.ar description: API server security: - apiKey: [] tags: - name: Clients description: Operations related to clients and their accounts - name: Accounts description: Operations related to account balances - 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: Superadmin description: Cross-tenant operations (JWT + email allowlist) - name: External client description: >- Exports for external (portal-linked) clients. Authenticate with `x-api-key` (company-owned client ID) or `Authorization: Bearer` (Supabase access token with an ExternalClient invite). paths: /api/operations: post: tags: - Operations summary: Create a new operation (up/down/other/exchange) description: >- Creates a new operation. Supports UP/DOWN operations, OTHER operations, and EXCHANGE operations. 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. 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 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 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. 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 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 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 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 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 ````