> ## Documentation Index > Fetch the complete documentation index at: https://docs.openfiskal.com/llms.txt > Use this file to discover all available pages before exploring further. # Create operation > Starts a new operation. The body is a discriminated union on `type`: goods movement (sale / return / exchange) or session lifecycle (session_open / session_cash_adjustment / session_cash_count / session_close). ## OpenAPI ````yaml /api-reference/openapi.yaml post /operations openapi: 3.0.0 info: title: OpenFiskal fiscalization API description: >- OpenFiskal exposes a server-to-server fiscalization API for merchant onboarding, register setup, and operation handling. The `v1` contract uses server-issued resource versions and conditional writes through `If-Match` for safe concurrent mutation handling. version: 1.1.0 contact: {} license: name: Proprietary servers: - url: https://api.openfiskal.com/v1 description: Production - url: https://sandbox.api.openfiskal.com/v1 description: Sandbox security: [] tags: - name: Merchants description: Create and manage merchant merchants. - name: Locations description: Create and manage merchant locations. - name: Registers description: Create and manage registers or terminals. - name: Operations description: Start, update, complete, cancel, list, and read operations. paths: /operations: post: tags: - Operations summary: Create operation description: >- Starts a new operation. The body is a discriminated union on `type`: goods movement (sale / return / exchange) or session lifecycle (session_open / session_cash_adjustment / session_cash_count / session_close). operationId: OperationsController_create parameters: - name: X-OpenFiskal-Merchant in: header description: Merchant identifier returned by the merchants resource. required: true schema: type: string - name: Idempotency-Key in: header description: >- Unique key per endpoint, merchant, and tenant. Retained for at least 24 hours. required: true schema: type: string requestBody: required: true description: Discriminated request body. The `type` field selects the variant. content: application/json: schema: oneOf: - title: SaleOperation allOf: - $ref: '#/components/schemas/CreateSaleOperationDto' - title: ReturnOperation allOf: - $ref: '#/components/schemas/CreateReturnOperationDto' - title: ExchangeOperation allOf: - $ref: '#/components/schemas/CreateExchangeOperationDto' - title: SessionOpenOperation allOf: - $ref: '#/components/schemas/CreateSessionOpenOperationDto' - title: SessionCashAdjustmentOperation allOf: - $ref: >- #/components/schemas/CreateSessionCashAdjustmentOperationDto - title: SessionCashCountOperation allOf: - $ref: '#/components/schemas/CreateSessionCashCountOperationDto' - title: SessionCloseOperation allOf: - $ref: '#/components/schemas/CreateSessionCloseOperationDto' discriminator: propertyName: type mapping: sale: $ref: '#/components/schemas/CreateSaleOperationDto' return: $ref: '#/components/schemas/CreateReturnOperationDto' exchange: $ref: '#/components/schemas/CreateExchangeOperationDto' session_open: $ref: '#/components/schemas/CreateSessionOpenOperationDto' session_cash_adjustment: $ref: >- #/components/schemas/CreateSessionCashAdjustmentOperationDto session_cash_count: $ref: '#/components/schemas/CreateSessionCashCountOperationDto' session_close: $ref: '#/components/schemas/CreateSessionCloseOperationDto' responses: '201': description: Operation created content: application/json: schema: oneOf: - title: SaleOperation allOf: - $ref: '#/components/schemas/SaleOperation' - title: ReturnOperation allOf: - $ref: '#/components/schemas/ReturnOperation' - title: ExchangeOperation allOf: - $ref: '#/components/schemas/ExchangeOperation' - title: SessionOpenOperation allOf: - $ref: '#/components/schemas/SessionOpenOperation' - title: SessionCashAdjustmentOperation allOf: - $ref: '#/components/schemas/SessionCashAdjustmentOperation' - title: SessionCashCountOperation allOf: - $ref: '#/components/schemas/SessionCashCountOperation' - title: SessionCloseOperation allOf: - $ref: '#/components/schemas/SessionCloseOperation' discriminator: propertyName: type mapping: sale: $ref: '#/components/schemas/SaleOperation' return: $ref: '#/components/schemas/ReturnOperation' exchange: $ref: '#/components/schemas/ExchangeOperation' session_open: $ref: '#/components/schemas/SessionOpenOperation' session_cash_adjustment: $ref: '#/components/schemas/SessionCashAdjustmentOperation' session_cash_count: $ref: '#/components/schemas/SessionCashCountOperation' session_close: $ref: '#/components/schemas/SessionCloseOperation' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: invalid_request value: code: invalid_request message: The request body is malformed. retryable: false '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: unauthorized value: code: unauthorized message: Authentication failed. retryable: false '403': description: >- Authenticated caller is not allowed to access the requested tenant, country, or merchant. content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: forbidden value: code: forbidden message: The authenticated caller cannot access this resource. retryable: false '409': description: Idempotency key reused with a different payload content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: idempotency_key_conflict value: code: idempotency_key_conflict message: >- The idempotency key was already used with a different payload. retryable: false '422': description: Domain validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: regime_validation_failed value: code: regime_validation_failed message: The payload violates regime-specific validation rules. retryable: false '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorDto' examples: default: summary: rate_limit_exceeded value: code: rate_limit_exceeded message: Too many requests. retryable: true security: - BearerAuth: [] components: schemas: CreateSaleOperationDto: type: object properties: register_id: type: string example: reg_abc123 description: Required for POS, must be null for ONLINE. source: type: string enum: - POS - ONLINE example: POS currency: type: string example: USD description: ISO 4217 currency code external_id: type: string example: order-12345 description: Merchant or POS identifier for the upstream order. note: type: string example: Customer requested extra napkins pretax_amount: type: string example: '9.00' description: Total before taxes tax_amount: type: string example: '0.95' description: Total tax amount tip_amount: type: string example: '0.00' description: Tip amount total_amount: type: string example: '9.95' description: Total amount (pretax + tax + tip) line_items: type: array items: $ref: '#/components/schemas/LineItemDto' type: type: string enum: - sale example: sale cart_level_discounts: description: >- Cart-level (order-level) discounts applied across the SALE, not apportioned onto specific line items. Each entry surfaces as a separate `Rabatt` business case in DSFinV-K. Line-item totals must already reflect their post-discount values. type: array items: $ref: '#/components/schemas/CartLevelDiscountDto' required: - source - currency - pretax_amount - tax_amount - tip_amount - total_amount - line_items - type CreateReturnOperationDto: type: object properties: register_id: type: string example: reg_abc123 description: Required for POS, must be null for ONLINE. source: type: string enum: - POS - ONLINE example: POS currency: type: string example: USD description: ISO 4217 currency code external_id: type: string example: order-12345 description: Merchant or POS identifier for the upstream order. note: type: string example: Customer requested extra napkins pretax_amount: type: string example: '9.00' description: Total before taxes tax_amount: type: string example: '0.95' description: Total tax amount tip_amount: type: string example: '0.00' description: Tip amount total_amount: type: string example: '9.95' description: Total amount (pretax + tax + tip) line_items: type: array items: $ref: '#/components/schemas/LineItemDto' related_operation_id: type: string example: op_abc123 description: >- For returns/exchanges: the OpenFiskal operation ID of the original sale. Exactly one of `related_operation_id` or `external_related_operation` must be set. external_related_operation: description: >- For returns/exchanges of sales that were never ingested into OpenFiskal (typically during platform migration). Exactly one of `related_operation_id` or `external_related_operation` must be set. allOf: - $ref: '#/components/schemas/ExternalRelatedOperationDto' type: type: string enum: - return example: return required: - source - currency - pretax_amount - tax_amount - tip_amount - total_amount - line_items - type CreateExchangeOperationDto: type: object properties: register_id: type: string example: reg_abc123 description: Required for POS, must be null for ONLINE. source: type: string enum: - POS - ONLINE example: POS currency: type: string example: USD description: ISO 4217 currency code external_id: type: string example: order-12345 description: Merchant or POS identifier for the upstream order. note: type: string example: Customer requested extra napkins pretax_amount: type: string example: '9.00' description: Total before taxes tax_amount: type: string example: '0.95' description: Total tax amount tip_amount: type: string example: '0.00' description: Tip amount total_amount: type: string example: '9.95' description: Total amount (pretax + tax + tip) line_items: type: array items: $ref: '#/components/schemas/LineItemDto' related_operation_id: type: string example: op_abc123 description: >- For returns/exchanges: the OpenFiskal operation ID of the original sale. Exactly one of `related_operation_id` or `external_related_operation` must be set. external_related_operation: description: >- For returns/exchanges of sales that were never ingested into OpenFiskal (typically during platform migration). Exactly one of `related_operation_id` or `external_related_operation` must be set. allOf: - $ref: '#/components/schemas/ExternalRelatedOperationDto' type: type: string enum: - exchange example: exchange required: - source - currency - pretax_amount - tax_amount - tip_amount - total_amount - line_items - type CreateSessionOpenOperationDto: type: object properties: type: type: string enum: - session_open example: session_open register_id: type: string example: reg_abc123 description: Register on which the session is being opened. currency: type: string example: EUR description: ISO 4217 currency code opening_balance_amount: type: string example: '50.00' description: Opening cash drawer balance as a decimal string. Must be ≥ 0. opening_note: type: string example: Float supplied by office manager. required: - type - register_id - currency - opening_balance_amount CreateSessionCashAdjustmentOperationDto: type: object properties: type: type: string enum: - session_cash_adjustment example: session_cash_adjustment register_id: type: string example: reg_abc123 description: Register that the adjustment applies to. currency: type: string example: EUR description: ISO 4217 currency code cash_amount: type: string example: '-20.00' description: >- Signed cash adjustment as a decimal string. Negative = cash out, positive = cash in. note: type: string example: Cash drop to safe. required: - type - register_id - currency - cash_amount CreateSessionCashCountOperationDto: type: object properties: type: type: string enum: - session_cash_count example: session_cash_count register_id: type: string example: reg_abc123 description: Register whose drawer is being counted. currency: type: string example: EUR description: ISO 4217 currency code counted_closing_amount: type: string example: '127.50' description: >- Merchant-counted closing cash balance as a decimal string. Must be ≥ 0. Captures the drawer state BEFORE any closing pull/add — count first, then move cash. The counted-vs-expected variance is fiscally attested. On write the session is frozen — only `session_close` is accepted from there. discrepancy_note: type: string example: Two coins from the day before were unaccounted for. required: - type - register_id - currency - counted_closing_amount CreateSessionCloseOperationDto: type: object properties: type: type: string enum: - session_close example: session_close register_id: type: string example: reg_abc123 description: Register whose session is being closed. currency: type: string example: EUR description: ISO 4217 currency code business_date: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-05-04T00:00:00.000Z' description: >- Date of posting for financial accounting matters, formatted `YYYY-MM-DD`. If your session is opened and closed on the same day, then that date should be the business_date. If your session reaches across multiple calendar days (e.g. a bar that closes after midnight), you need to decide which date to use as business_date. If in doubt, consult your tax advisor. closing_adjustment_amount: type: string example: '-50.00' description: >- Optional cash pulled (or added) at close. Signed decimal string: negative = cash out (deposit, transport to bank); positive = cash in (e.g., next-shift float top-up). Omit if no cash was moved at close. The counted closing balance and discrepancy note live on the preceding SESSION_CASH_COUNT — SESSION_CLOSE only carries the optional pull. closing_adjustment_note: type: string example: Safe deposit at end of shift. description: Optional explanation for the closing pull/add. required: - type - register_id - currency - business_date SaleOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time note: type: string nullable: true description: Merchant free-text note for the goods-movement event. pretax_amount: type: string tax_amount: type: string tip_amount: type: string total_amount: type: string line_items: type: array items: $ref: '#/components/schemas/LineItem' payments: type: array items: $ref: '#/components/schemas/Payment' type: type: string enum: - sale example: sale cart_level_discounts: description: >- Cart-level (order-level) discounts applied across the SALE. Empty array when none. Surfaced separately from line items so consumers do not need to back-derive from totals. type: array items: $ref: '#/components/schemas/CartLevelDiscount' required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - pretax_amount - tax_amount - tip_amount - total_amount - line_items - payments - type - cart_level_discounts ReturnOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time note: type: string nullable: true description: Merchant free-text note for the goods-movement event. pretax_amount: type: string tax_amount: type: string tip_amount: type: string total_amount: type: string line_items: type: array items: $ref: '#/components/schemas/LineItem' payments: type: array items: $ref: '#/components/schemas/Payment' type: type: string enum: - return example: return related_operation_id: type: string nullable: true description: Set when the return references an OpenFiskal operation. external_related_operation: nullable: true description: >- Set when the return references a sale that lives outside OpenFiskal (e.g. legacy platform). allOf: - $ref: '#/components/schemas/ExternalRelatedOperation' required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - pretax_amount - tax_amount - tip_amount - total_amount - line_items - payments - type ExchangeOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time note: type: string nullable: true description: Merchant free-text note for the goods-movement event. pretax_amount: type: string tax_amount: type: string tip_amount: type: string total_amount: type: string line_items: type: array items: $ref: '#/components/schemas/LineItem' payments: type: array items: $ref: '#/components/schemas/Payment' type: type: string enum: - exchange example: exchange related_operation_id: type: string nullable: true description: Set when the exchange references an OpenFiskal operation. external_related_operation: nullable: true description: >- Set when the exchange references a sale that lives outside OpenFiskal (e.g. legacy platform). allOf: - $ref: '#/components/schemas/ExternalRelatedOperation' required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - pretax_amount - tax_amount - tip_amount - total_amount - line_items - payments - type SessionOpenOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: type: string enum: - session_open example: session_open opening_balance_amount: type: string description: Opening cash balance as a decimal string. opening_note: type: string nullable: true required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - type - opening_balance_amount SessionCashAdjustmentOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: type: string enum: - session_cash_adjustment example: session_cash_adjustment cash_amount: type: string description: Signed cash adjustment as a decimal string. Negative = cash out. note: type: string nullable: true description: Merchant free-text note for the cash adjustment. required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - type - cash_amount SessionCashCountOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: type: string enum: - session_cash_count example: session_cash_count counted_closing_amount: type: string description: >- Merchant-counted closing cash balance as a decimal string. Captured BEFORE any closing pull/add. expected_closing_amount: type: string description: >- System-calculated expected drawer balance at count time, derived from the session opening balance plus cash payments and adjustments. Decimal string. closing_cashcount_diff: type: string description: >- Signed difference between counted and expected (`counted - expected`). Positive = drawer over, negative = drawer short, zero = on the dot. Decimal string. Fiscally attested. discrepancy_note: type: string nullable: true required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - type - counted_closing_amount - expected_closing_amount - closing_cashcount_diff SessionCloseOperation: type: object properties: id: type: string merchant_id: type: string location_id: type: string nullable: true description: 'Only set for source: POS.' register_id: type: string nullable: true description: 'Only set for source: POS.' session_id: type: string nullable: true description: >- The RegisterSession this Operation is bound to. Set on every POS Operation; null for ONLINE goods-movement (no register, hence no session). On session-event variants this is the session being opened, adjusted, or closed; on goods-movement variants it is the session the operation was rung up during. source: type: string enum: - POS - ONLINE status: type: string enum: - open - completed - voided currency: type: string description: ISO 4217 currency code. example: EUR external_id: type: string description: Merchant or POS identifier for the upstream order. nullable: true resource_version: type: number description: >- Current server-issued version for the operation, starting at 1. Returned as `ETag` header. fiscal_information: nullable: true description: >- The Fiskaly signature attached to this Operation, when one exists. Null until the operation has been signed. oneOf: - title: FiscalInformationKassenSichV allOf: - $ref: '#/components/schemas/FiscalInformationKassenSichV' - title: FiscalInformationRKSV allOf: - $ref: '#/components/schemas/FiscalInformationRKSV' - title: FiscalInformationRT allOf: - $ref: '#/components/schemas/FiscalInformationRT' discriminator: propertyName: regime mapping: KassenSichV: $ref: '#/components/schemas/FiscalInformationKassenSichV' RKSV: $ref: '#/components/schemas/FiscalInformationRKSV' RT: $ref: '#/components/schemas/FiscalInformationRT' completed_at: type: string format: date-time nullable: true voided_at: type: string format: date-time nullable: true void_reason: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: type: string enum: - session_close example: session_close closing_adjustment_amount: type: string nullable: true description: >- Optional signed cash adjustment performed at close (negative = pull, positive = add). Null if no cash was moved at close. The counted closing balance and discrepancy note live on the preceding SESSION_CASH_COUNT response — SESSION_CLOSE only carries the optional pull. example: '-50.00' closing_adjustment_note: type: string nullable: true description: Optional explanation for the closing pull/add. required: - id - merchant_id - source - status - currency - resource_version - created_at - updated_at - type ErrorDto: type: object properties: code: type: string description: Stable machine-readable error code. example: invalid_request message: type: string description: Human-readable explanation of the error. retryable: type: boolean description: Whether retrying the request is safe. details: type: object description: Additional structured context for the error. additionalProperties: true required: - code - message - retryable LineItemDto: type: object properties: type: type: string enum: - item - gift_card default: item description: >- Classifies the line item. `gift_card` lines are multi-purpose vouchers (Mehrzweckgutschein) — all taxes must carry rate "0" and tax_amount "0". title: type: string example: Café Latte quantity: type: integer minimum: 1 example: 2 description: >- Positive integer count of units. A return of 2 tshirts also has quantity 2. unit_price: type: string example: '4.50' description: Price per unit total_amount: type: string example: '9.00' description: Total amount for this line item (quantity * unit_price) sku_identifier: type: string example: TSHIRT-BLUE-M maxLength: 50 description: >- Identifies a unique number used to maintain and manage the item, product, or merchandise category in the company's systems. Example: A Tshirt has one sku for each size + color combination. At most 50 characters long. gift_card_id: type: string example: gc_abc123 description: >- Integrator-supplied gift card identifier. Only meaningful when type is "gift_card". Flows through to DSFinV-K voucher_id. taxes: description: >- One entry per VAT rate applied to this line. At least one entry required. type: array items: $ref: '#/components/schemas/LineItemTaxDto' required: - title - quantity - unit_price - total_amount - sku_identifier - taxes CartLevelDiscountDto: type: object properties: description: type: string example: WELCOME10 maxLength: 255 description: >- Free-text label shown on the receipt and audit trail. Trimmed to 255 characters in DSFinV-K exports. amount: type: string example: '5.00' description: Discount amount applied to the cart, as a positive decimal string. required: - amount ExternalRelatedOperationDto: type: object properties: description: type: string example: Return against order from external platform. description: >- Free-text description identifying the external sale being returned/exchanged against. external_operation_id: type: string example: shopify-order-4711 description: >- The integrator-side identifier of the original sale in the external system. required: - description - external_operation_id FiscalInformationKassenSichV: type: object properties: regime: type: string enum: - KassenSichV document_number: type: string document_type: type: string tss_serial_number: type: string pos_client_serial_number: type: string signature_algorithm: type: string time_format: type: string start_event: $ref: '#/components/schemas/FiscalInformationKassenSichVStartEvent' end_event: $ref: '#/components/schemas/FiscalInformationKassenSichVEndEvent' verification: $ref: '#/components/schemas/FiscalInformationKassenSichVVerification' required: - regime - document_number - document_type - tss_serial_number - pos_client_serial_number - signature_algorithm - time_format - start_event - end_event - verification FiscalInformationRKSV: type: object properties: regime: type: string enum: - RKSV document_number: type: string document_type: type: string transmitted_at: type: string format: date-time nullable: true cashbox_id: type: string certificate_serial: type: string signature: $ref: '#/components/schemas/FiscalInformationRKSVSignature' verification: $ref: '#/components/schemas/FiscalInformationRKSVVerification' required: - regime - document_number - document_type - cashbox_id - signature - verification FiscalInformationRT: type: object properties: regime: type: string enum: - RT document_number: type: string document_type: type: string transmitted_at: type: string format: date-time nullable: true rt_serial: type: string rt_firmware: type: string progressive_number: type: number daily_closing_number: type: number lottery_code: type: string nullable: true signature: $ref: '#/components/schemas/FiscalInformationRTSignature' required: - regime - document_number - document_type - rt_serial - rt_firmware - progressive_number - daily_closing_number - signature LineItem: type: object properties: id: type: string type: type: string enum: - item - gift_card default: item description: >- Line item classification. `gift_card` = multi-purpose voucher (Mehrzweckgutschein). title: type: string quantity: type: number unit_price: type: string total_amount: type: string sku_identifier: type: string example: TSHIRT-BLUE-M description: >- Identifies a unique number used to maintain and manage the item, product, or merchandise category in the company's systems. Example: A Tshirt has one sku for each size + color combination. gift_card_id: type: string nullable: true description: Gift card identifier. Only present when type is "gift_card". taxes: type: array items: $ref: '#/components/schemas/LineItemTax' required: - id - type - title - quantity - unit_price - total_amount - sku_identifier - taxes Payment: type: object properties: id: type: string payment_id: type: string description: Merchant or PSP identifier for the payment. method: type: string amount: type: string currency: type: string status: type: string enum: - captured - refunded description: >- Direction of money movement: `captured` for money-in (SALE legs, EXCHANGE legs with amount > 0), `refunded` for money-out (RETURN legs, EXCHANGE legs with amount < 0). Zero-amount EXCHANGE legs accept either. processor: type: string nullable: true card_brand: type: string nullable: true processor_reference: type: string nullable: true processed_at: type: string format: date-time nullable: true gift_card_id: type: string nullable: true description: Gift card identifier. Only present when method is "gift_card". required: - id - payment_id - method - amount - currency - status CartLevelDiscount: type: object properties: id: type: string description: type: string nullable: true description: Free-text label for the discount (e.g. promo code, campaign name). amount: type: string description: Discount amount as a positive decimal string. required: - id - amount ExternalRelatedOperation: type: object properties: description: type: string description: >- Free-text description identifying the external sale being returned/exchanged against. external_operation_id: type: string description: >- The integrator-side identifier of the original sale in the external system. required: - description - external_operation_id LineItemTaxDto: type: object properties: name: type: string example: State SUT description: Tax name, e.g. "Municipal Tax" or "State Tax" rate: type: string example: '0.105' description: Tax rate as a decimal string, e.g. "0.105" for 10.5% tax_amount: type: string example: '1.58' description: Computed tax amount for this line item required: - name - rate - tax_amount FiscalInformationKassenSichVStartEvent: type: object properties: signed_at: type: string format: date-time required: - signed_at FiscalInformationKassenSichVEndEvent: type: object properties: signed_at: type: string format: date-time transaction_counter: type: number signature: type: string public_key: type: string process_type: type: string process_data: type: string required: - signed_at - transaction_counter - signature - public_key - process_type - process_data FiscalInformationKassenSichVVerification: type: object properties: qr_data: type: string required: - qr_data FiscalInformationRKSVSignature: type: object properties: signed_at: type: string format: date-time transaction_counter: type: number turnover_counter: type: string description: Running turnover counter as a decimal string. signature: type: string certificate_serial: type: string required: - signed_at - transaction_counter - turnover_counter - signature - certificate_serial FiscalInformationRKSVVerification: type: object properties: qr_data: type: string required: - qr_data FiscalInformationRTSignature: type: object properties: signed_at: type: string format: date-time signature: type: string required: - signed_at - signature LineItemTax: type: object properties: id: type: string name: type: string rate: type: string description: Tax rate as a decimal string (e.g. "0.19"). tax_amount: type: string description: Tax amount as a decimal string. required: - id - name - rate - tax_amount securitySchemes: BearerAuth: scheme: bearer bearerFormat: API key type: http ````