> ## Documentation Index > Fetch the complete documentation index at: https://docs-pos.solya.app/llms.txt > Use this file to discover all available pages before exploring further. # Finalize a settled sale (encaissement) > Commits an encaissement: turns a settled cart plus its tenders into one idempotent sale event (vente), booked against the register session, and produces the ticket de caisse / reçu (201). This is the ONLY way to commit a sale. The submitted `cart` prices are ADVISORY — the server re-prices every catalog line from its own reference authority (plus any `declaredDiscounts`, automatic promotions and a presented `couponCode`) and refuses a cart it prices differently. Idempotent by `transactionId`: replaying the same id with the same content is a no-op. Reach for it to ring up a customer at the till. Gotchas: mark a self-priced line (Article libre / gift card) with `custom: true` so it is trusted instead of re-priced; a `registerId` keys the NF525 fiscal chain per till. Side-effects: this operation is IRREVERSIBLE and money-in — a single call decrements on-hand stock for every sold unit, accrues loyalty points for an identified customer, and appends an inalterable entry to the per-register NF525 fiscal signature chain (the ticket de caisse is fiscally sealed and cannot be un-issued). There is no un-finalize: a mistake is corrected by processing a return / avoir, never by deleting the sale. This is why the operation is tier `avoid` — an agent must not trigger it unprompted. Failure conditions: 400 on a malformed body; 403 for a declared discount the principal may not grant (needs `price:override`, or a single-use `x-elevation-token`); 409 when the same `transactionId` was already finalized with DIFFERENT content; 422 on an empty cart, a price/settlement mismatch (beyond the deployment's cash-rounding tolerance) or a SKU the price authority does not carry. ## OpenAPI ````yaml /openapi.json post /v1/checkout/finalize openapi: 3.0.3 info: title: Solya POS API version: 1.0.0 description: >- The Solya POS backend HTTP surface. Every documented operation is agent-ready: it carries an `operationId`, an agent-facing `description`, the `pos.*` scopes it enforces (`x-required-permissions`) and an `x-agent-tier`. Success responses return the payload as raw JSON; failures return the `ErrorResponse` envelope (`{ error: { code, message, statusCode } }`). servers: - url: / description: The backend, relative to its deployed origin. security: [] paths: /v1/checkout/finalize: post: tags: - Checkout summary: Finalize a settled sale (encaissement) description: >- Commits an encaissement: turns a settled cart plus its tenders into one idempotent sale event (vente), booked against the register session, and produces the ticket de caisse / reçu (201). This is the ONLY way to commit a sale. The submitted `cart` prices are ADVISORY — the server re-prices every catalog line from its own reference authority (plus any `declaredDiscounts`, automatic promotions and a presented `couponCode`) and refuses a cart it prices differently. Idempotent by `transactionId`: replaying the same id with the same content is a no-op. Reach for it to ring up a customer at the till. Gotchas: mark a self-priced line (Article libre / gift card) with `custom: true` so it is trusted instead of re-priced; a `registerId` keys the NF525 fiscal chain per till. Side-effects: this operation is IRREVERSIBLE and money-in — a single call decrements on-hand stock for every sold unit, accrues loyalty points for an identified customer, and appends an inalterable entry to the per-register NF525 fiscal signature chain (the ticket de caisse is fiscally sealed and cannot be un-issued). There is no un-finalize: a mistake is corrected by processing a return / avoir, never by deleting the sale. This is why the operation is tier `avoid` — an agent must not trigger it unprompted. Failure conditions: 400 on a malformed body; 403 for a declared discount the principal may not grant (needs `price:override`, or a single-use `x-elevation-token`); 409 when the same `transactionId` was already finalized with DIFFERENT content; 422 on an empty cart, a price/settlement mismatch (beyond the deployment's cash-rounding tolerance) or a SKU the price authority does not carry. operationId: finalizeSale requestBody: required: true content: application/json: schema: type: object properties: transactionId: type: string minLength: 1 number: type: string minLength: 1 storeId: type: string minLength: 1 sellerId: type: string minLength: 1 customerId: nullable: true type: string minLength: 1 sessionId: type: string minLength: 1 registerId: type: string minLength: 1 type: default: sale type: string enum: - sale - rental - repair - return cart: type: object properties: lines: type: array items: type: object properties: id: type: string minLength: 1 skuId: nullable: true type: string pattern: ^[0-9a-f]{64}$ quantity: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 unitPrice: type: integer minimum: 0 maximum: 9007199254740991 vatRate: type: number minimum: 0 maximum: 100 free: type: boolean custom: type: boolean serial: type: object properties: serialNumber: type: string minLength: 1 warrantyMonths: type: integer minimum: 0 maximum: 9007199254740991 required: - serialNumber - warrantyMonths kitId: type: string minLength: 1 required: - id - skuId - quantity - unitPrice - vatRate - free freeLineSequence: type: integer minimum: 0 maximum: 9007199254740991 required: - lines - freeLineSequence declaredDiscounts: default: [] type: array items: oneOf: - type: object properties: id: type: string minLength: 1 scope: type: string enum: - line lineId: type: string minLength: 1 basis: type: string enum: - percent percentBps: type: integer minimum: 1 maximum: 10000 reason: type: string enum: - manual_markdown - promotional - loyalty_reward - damaged_goods - manager_goodwill required: - id - scope - lineId - basis - percentBps - reason - oneOf: - type: object properties: id: type: string minLength: 1 scope: type: string enum: - ticket basis: type: string enum: - percent percentBps: type: integer minimum: 1 maximum: 10000 reason: type: string enum: - manual_markdown - promotional - loyalty_reward - damaged_goods - manager_goodwill required: - id - scope - basis - percentBps - reason - type: object properties: id: type: string minLength: 1 scope: type: string enum: - ticket basis: type: string enum: - amount amountCents: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 reason: type: string enum: - manual_markdown - promotional - loyalty_reward - damaged_goods - manager_goodwill required: - id - scope - basis - amountCents - reason couponCode: type: string minLength: 1 tenders: type: object properties: amountDue: type: integer minimum: 0 maximum: 9007199254740991 tenders: type: array items: type: object properties: id: type: string minLength: 1 method: type: string enum: - card - cash - cheque - meal_voucher - gift_card - credit_note - loyalty - alma applied: type: integer minimum: 0 maximum: 9007199254740991 presented: type: integer minimum: 0 maximum: 9007199254740991 change: type: integer minimum: 0 maximum: 9007199254740991 forfeited: type: integer minimum: 0 maximum: 9007199254740991 required: - id - method - applied - presented - change - forfeited sequence: type: integer minimum: 0 maximum: 9007199254740991 required: - amountDue - tenders - sequence required: - transactionId - number - storeId - sellerId - customerId - sessionId - cart - tenders example: transactionId: txn-ok number: T-100 storeId: store-1 sellerId: seller-1 customerId: cust-1 sessionId: sess-1 registerId: reg-1 type: sale cart: lines: - id: l1 skuId: >- 72474f561163443c1d5c6702bf47b7f83de910cf3cc94212be19a0f882f6da20 quantity: 1 unitPrice: 1800 vatRate: 20 free: false - id: l2 skuId: null quantity: 1 unitPrice: 500 vatRate: 20 free: false custom: true freeLineSequence: 0 declaredDiscounts: - id: disc-1 scope: line lineId: l1 basis: percent percentBps: 1000 reason: manual_markdown couponCode: WELCOME10 tenders: amountDue: 2120 tenders: - id: t1 method: card applied: 2120 presented: 2120 change: 0 forfeited: 0 sequence: 1 responses: '201': description: >- The committed sale event: its transaction, ticket, loyalty, and stock movements. content: application/json: schema: type: object properties: id: type: string registerId: type: string transaction: type: object properties: id: type: string number: type: string storeId: type: string sellerId: type: string customerId: nullable: true type: string status: type: string type: type: string lines: type: array items: type: object properties: skuId: type: string pattern: ^[0-9a-f]{64}$ quantity: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 unitPrice: type: number minimum: 0 serial: type: object properties: serialNumber: type: string minLength: 1 warrantyMonths: type: integer minimum: 0 maximum: 9007199254740991 required: - serialNumber - warrantyMonths additionalProperties: false required: - skuId - quantity - unitPrice additionalProperties: false totals: type: object properties: subtotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 itemCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 lineCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - subtotal - total - itemCount - lineCount additionalProperties: false required: - id - number - storeId - sellerId - customerId - status - type - lines - totals additionalProperties: false ticket: type: object properties: number: type: string storeId: type: string sellerId: type: string customerId: nullable: true type: string subtotalCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 totalCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 itemCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 tenders: type: array items: type: object properties: method: type: string appliedCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - method - appliedCents additionalProperties: false changeCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - number - storeId - sellerId - customerId - subtotalCents - totalCents - itemCount - tenders - changeCents additionalProperties: false loyalty: type: object properties: customerId: nullable: true type: string pointsEarned: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - customerId - pointsEarned additionalProperties: false stockMovements: type: array items: type: object properties: skuId: type: string deltaQuantity: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - skuId - deltaQuantity additionalProperties: false coupon: type: object properties: code: type: string basketCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 discountAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - code - basketCents - discountAmountCents additionalProperties: false emittedAt: type: string required: - id - transaction - ticket - loyalty - stockMovements - emittedAt additionalProperties: false description: >- The committed sale event: its transaction, ticket, loyalty, and stock movements. example: id: txn-ok registerId: reg-1 transaction: id: txn-ok number: T-100 storeId: store-1 sellerId: seller-1 customerId: cust-1 status: completed type: sale lines: - skuId: >- 72474f561163443c1d5c6702bf47b7f83de910cf3cc94212be19a0f882f6da20 quantity: 1 unitPrice: 1800 - skuId: >- 07ae28fbd784733d76896d29b542c41882dea56eb1fa3249d4b861f161d0817c quantity: 1 unitPrice: 500 totals: subtotal: 2300 total: 2120 itemCount: 2 lineCount: 2 ticket: number: T-100 storeId: store-1 sellerId: seller-1 customerId: cust-1 subtotalCents: 2300 totalCents: 2120 itemCount: 2 tenders: - method: card appliedCents: 2120 changeCents: 0 loyalty: customerId: cust-1 pointsEarned: 21 stockMovements: - skuId: >- 72474f561163443c1d5c6702bf47b7f83de910cf3cc94212be19a0f882f6da20 deltaQuantity: -1 coupon: code: WELCOME10 basketCents: 2120 discountAmountCents: 0 emittedAt: '2026-07-28T10:00:00.000Z' '400': description: >- The request failed schema validation; `error.fieldErrors` lists the fields. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: No valid credential was presented — send a bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The actor is authenticated but lacks the required `pos.*` scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The request conflicts with current state (duplicate id or stale version). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: The request is well-formed but violates a domain rule. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: An unexpected server error — safe to retry idempotent requests. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: ValidationErrorResponse: type: object required: - error additionalProperties: false description: >- A `VALIDATION_FAILED` envelope carrying the offending fields in `fieldErrors`. properties: error: type: object required: - code - message - statusCode additionalProperties: false properties: code: type: string enum: - VALIDATION_FAILED message: type: string statusCode: type: integer fieldErrors: type: array description: >- One entry per rejected field: the field path and why it was rejected. items: type: object required: - field - message additionalProperties: false properties: field: type: string description: Dot-path of the offending field. message: type: string description: Why the field was rejected. ErrorResponse: type: object required: - error additionalProperties: false description: The uniform failure envelope every non-2xx response returns. properties: error: type: object required: - code - message - statusCode additionalProperties: false properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - BUSINESS_RULE_VIOLATION - INTERNAL_ERROR description: >- Machine-readable kernel `ResultCode` — branch on this, not on `message`. message: type: string description: >- Human-readable explanation. Safe to surface; never leaks server internals. statusCode: type: integer description: >- The HTTP status, mirrored into the body so a client need not read headers. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- `Authorization: Bearer `. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same `pos.*` scope vocabulary the route guards enforce. ````