{"openapi":"3.0.0","paths":{"/v1/merchants":{"get":{"operationId":"MerchantsController_list","parameters":[],"responses":{"200":{"description":"Merchants returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantListResponse"}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"List merchants","tags":["Merchants"]},"post":{"operationId":"MerchantsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMerchantDto"}}}},"responses":{"201":{"description":"Merchant created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"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}}}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Create merchant","tags":["Merchants"]}},"/v1/merchants/{merchantId}":{"get":{"operationId":"MerchantsController_get","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"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}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Get merchant","tags":["Merchants"]},"patch":{"operationId":"MerchantsController_update","parameters":[{"name":"merchantId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMerchantDto"}}}},"responses":{"200":{"description":"Merchant updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"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}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Update merchant","tags":["Merchants"]}},"/v1/registers":{"get":{"operationId":"RegistersController_list","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Registers returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterListResponse"}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"List registers","tags":["Registers"]},"post":{"operationId":"RegistersController_create","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRegisterDto"}}}},"responses":{"201":{"description":"Register created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Register"}}}},"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}}}}}},"404":{"description":"Location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Create register","tags":["Registers"]}},"/v1/registers/{registerId}":{"get":{"operationId":"RegistersController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"registerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Register returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Register"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Get register","tags":["Registers"]},"patch":{"operationId":"RegistersController_update","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"registerId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRegisterDto"}}}},"responses":{"200":{"description":"Register updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Register"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Update register","tags":["Registers"]},"delete":{"operationId":"RegistersController_delete","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"registerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Register deleted"},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Register has operations or is fiscalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"register_has_dependencies","value":{"code":"register_has_dependencies","message":"Cannot delete a register that has operations or is fiscalized.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Delete register","tags":["Registers"]}},"/v1/registers/{registerId}/fiscalize":{"post":{"description":"Enqueues fiscalization for the register and returns immediately with `202 Accepted`. Fiscalization happens asynchronously in the background.\n\nThe register transitions through `fiscalization_status`: `pending` → `fiscalized` (or `failed`). Poll `GET /registers/{registerId}` until `fiscalization_status` is `fiscalized` before sending operations to the register.","operationId":"RegistersController_fiscalize","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"registerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"202":{"description":"Fiscalization enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Register"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Already fiscalized or in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"register_already_fiscalized","value":{"code":"register_already_fiscalized","message":"Register is already fiscalized or a fiscalization is in progress.","retryable":false}}}}}},"422":{"description":"Fiscalization not supported for this register","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Fiscalize register","tags":["Registers"]}},"/v1/registers/{registerId}/decommission":{"post":{"operationId":"RegistersController_decommission","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"registerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Register decommissioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Register"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Register is not fiscalized or already decommissioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"register_invalid_fiscal_state","value":{"code":"register_invalid_fiscal_state","message":"Register is not fiscalized or has already been decommissioned.","retryable":false}}}}}},"422":{"description":"Decommission not supported for this register","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Decommission register","tags":["Registers"]}},"/v1/locations":{"get":{"operationId":"LocationsController_list","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Locations returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationListResponse"}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"List locations","tags":["Locations"]},"post":{"operationId":"LocationsController_create","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLocationDto"}}}},"responses":{"201":{"description":"Location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"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}}}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Create location","tags":["Locations"]}},"/v1/locations/{locationId}":{"get":{"operationId":"LocationsController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"locationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Location returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"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}}}}}},"404":{"description":"Location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Get location","tags":["Locations"]},"patch":{"operationId":"LocationsController_update","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"locationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLocationDto"}}}},"responses":{"200":{"description":"Location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"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}}}}}},"404":{"description":"Location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Update location","tags":["Locations"]},"delete":{"operationId":"LocationsController_delete","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"locationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Location deleted"},"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}}}}}},"404":{"description":"Location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Location has registers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"location_has_registers","value":{"code":"location_has_registers","message":"Cannot delete a location that has registers.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Delete location","tags":["Locations"]}},"/v1/operations/{operationId}":{"get":{"description":"Returns a single operation. The response is a discriminated union on `type`: goods movement (sale / return / exchange) or session lifecycle (session_open / session_cash_adjustment / session_close).","operationId":"OperationsController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"operationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Operation returned","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":"#/components/schemas/SaleOperation","return":"#/components/schemas/ReturnOperation","exchange":"#/components/schemas/ExchangeOperation","session_open":"#/components/schemas/SessionOpenOperation","session_cash_adjustment":"#/components/schemas/SessionCashAdjustmentOperation","session_cash_count":"#/components/schemas/SessionCashCountOperation","session_close":"#/components/schemas/SessionCloseOperation"}}}}}},"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}}}}}},"404":{"description":"Operation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Get operation","tags":["Operations"]}},"/v1/operations":{"post":{"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":"#/components/schemas/CreateSaleOperationDto","return":"#/components/schemas/CreateReturnOperationDto","exchange":"#/components/schemas/CreateExchangeOperationDto","session_open":"#/components/schemas/CreateSessionOpenOperationDto","session_cash_adjustment":"#/components/schemas/CreateSessionCashAdjustmentOperationDto","session_cash_count":"#/components/schemas/CreateSessionCashCountOperationDto","session_close":"#/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":"#/components/schemas/SaleOperation","return":"#/components/schemas/ReturnOperation","exchange":"#/components/schemas/ExchangeOperation","session_open":"#/components/schemas/SessionOpenOperation","session_cash_adjustment":"#/components/schemas/SessionCashAdjustmentOperation","session_cash_count":"#/components/schemas/SessionCashCountOperation","session_close":"#/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":[]}],"summary":"Create operation","tags":["Operations"]}},"/v1/operations/{operationId}/complete":{"post":{"description":"Finalizes a goods-movement operation (`sale` / `return` / `exchange`) and attaches the typed payment contract used for fiscalization and reconciliation. Session-lifecycle operations (`session_open`, `session_cash_adjustment`, `session_cash_count`, `session_close`) auto-complete on `POST /operations` and must not be sent here — they will return `409 operation_invalid_state` because they are never in OPEN status.","operationId":"OperationsController_complete","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"operationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"If-Match","required":true,"in":"header","description":"Latest operation `ETag` returned by OpenFiskal. Replace it after every successful mutation.","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,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteOperationDto"}}}},"responses":{"200":{"description":"Operation completed","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"}]}],"discriminator":{"propertyName":"type","mapping":{"sale":"#/components/schemas/SaleOperation","return":"#/components/schemas/ReturnOperation","exchange":"#/components/schemas/ExchangeOperation"}}}}}},"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}}}}}},"404":{"description":"Operation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Operation not in OPEN status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"operation_invalid_state","value":{"code":"operation_invalid_state","message":"Only OPEN operations can be completed.","retryable":false}}}}}},"412":{"description":"Stale `If-Match` header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"precondition_failed","value":{"code":"precondition_failed","message":"Resource version mismatch.","retryable":true,"details":{"expected_resource_version":1,"current_resource_version":2}}}}}}},"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}}}}}},"428":{"description":"Missing `If-Match` header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"precondition_required","value":{"code":"precondition_required","message":"This operation requires an If-Match header.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Complete operation","tags":["Operations"]}},"/v1/operations/{operationId}/void":{"post":{"description":"Voids an open goods-movement operation (`sale` / `return` / `exchange`) before completion. Use a return operation after completion. Session-lifecycle operations auto-complete on create and cannot be voided — they will return `409 operation_invalid_state`.","operationId":"OperationsController_voidOperation","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"operationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"If-Match","required":true,"in":"header","description":"Latest operation `ETag` returned by OpenFiskal. Replace it after every successful mutation.","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,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidOperationDto"}}}},"responses":{"200":{"description":"Operation voided","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"}]}],"discriminator":{"propertyName":"type","mapping":{"sale":"#/components/schemas/SaleOperation","return":"#/components/schemas/ReturnOperation","exchange":"#/components/schemas/ExchangeOperation"}}}}}},"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}}}}}},"404":{"description":"Operation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Operation not in OPEN status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"operation_invalid_state","value":{"code":"operation_invalid_state","message":"Only OPEN operations can be voided.","retryable":false}}}}}},"412":{"description":"Stale `If-Match` header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"precondition_failed","value":{"code":"precondition_failed","message":"Resource version mismatch.","retryable":true,"details":{"expected_resource_version":1,"current_resource_version":2}}}}}}},"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}}}}}},"428":{"description":"Missing `If-Match` header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"precondition_required","value":{"code":"precondition_required","message":"This operation requires an If-Match header.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Void operation","tags":["Operations"]}},"/v1/exports/dsfinvk":{"post":{"description":"Germany (KassenSichV). Produces the DSFinV-K archive: the mandated CSV files, `index.xml` and the GDPdU DTD for one register over a time window.\n\nAsynchronous: returns `202 Accepted` with `status: pending`. Poll `GET /exports/{exportId}` until `status` is `completed` (then `download_url` is set) or `failed`.\n\nThe window is silently clamped to the period the register was live. Sessions still open in the window are skipped; a closed session whose DSFinV-K closing has not been built yet is rejected rather than omitted.","operationId":"ExportsController_createDsfinvk","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDsfinvkExportDto"}}}},"responses":{"202":{"description":"Export job enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"422":{"description":"No closed sessions in the window (`export_dsfinvk_no_closed_sessions`), a closed session is not built yet (`export_dsfinvk_build_pending`), or the register is not on the KassenSichV regime (`validation_error`).","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Create a DSFinV-K export","tags":["Exports"]}},"/v1/exports/tse":{"post":{"description":"Germany (KassenSichV). Produces the TSE export: the signed Log Messages themselves, per BSI TR-03151. This is the second artefact a Kassennachschau asks for, alongside DSFinV-K, and it describes the security device rather than the cash register.\n\nAsynchronous: returns `202 Accepted` with `status: pending`. Poll `GET /exports/{exportId}` until `status` is `completed` (then `download_url` is set) or `failed`.\n\n**Scope is the device, not the register.** A Swissbit TSE serves every register at the same business premises and offers no filtered export, so the archive contains their log messages too. Each `.log` entry is reproduced exactly as the device wrote it, under the filename the device gave it; only the containing archive is assembled by OpenFiskal, because a vendor export is incremental and no single one spans a requested period.","operationId":"ExportsController_createTse","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTseExportDto"}}}},"responses":{"202":{"description":"Export job enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"422":{"description":"The register was on no TSE in the window (`export_tse_no_device_in_window`), no log messages are archived for it yet (`export_tse_archive_pending`), or the register is not on the KassenSichV regime (`validation_error`).","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Create a TSE export","tags":["Exports"]}},"/v1/exports":{"post":{"deprecated":true,"description":"Deprecated. Use the type-specific routes instead: `POST /exports/dsfinvk`, `POST /exports/tse`. They document their own parameters, scoping rules and error codes, which this endpoint cannot because its body depends on `type`. Behaviour is otherwise identical; this route will be removed in a future release.","operationId":"ExportsController_create","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExportDto"}}}},"responses":{"202":{"description":"Export job enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Trigger an export (deprecated)","tags":["Exports"]}},"/v1/exports/dsfinvk/{exportId}":{"get":{"description":"Returns the DSFinV-K export job. When `status` is `completed`, `download_url` is a signed URL to fetch the TAR archive, valid for 7 days from `completed_at`. When `status` is `failed`, `error.message` (and optional `error.details`) describe why.\n\nAn id that names an export of a different type returns `404`: the path asserts what you believe you are reading, so a mismatch is an error rather than a differently-shaped response.","operationId":"ExportsController_getDsfinvk","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Export job returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"No DSFinV-K export with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Retrieve a DSFinV-K export","tags":["Exports"]}},"/v1/exports/tse/{exportId}":{"get":{"description":"Returns the TSE export job. When `status` is `completed`, `download_url` is a signed URL to fetch the TAR archive, valid for 7 days from `completed_at`. When `status` is `failed`, `error.message` (and optional `error.details`) describe why.\n\nAn id that names an export of a different type returns `404`: the path asserts what you believe you are reading, so a mismatch is an error rather than a differently-shaped response.","operationId":"ExportsController_getTse","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Export job returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"No TSE export with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Retrieve a TSE export","tags":["Exports"]}},"/v1/exports/{exportId}":{"get":{"deprecated":true,"description":"Deprecated. Use the type-specific routes instead: `GET /exports/dsfinvk/{exportId}`, `GET /exports/tse/{exportId}`. Behaviour is otherwise identical, except that this route does not check the export's type against the path. It will be removed in a future release.","operationId":"ExportsController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"exportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Export job returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Export"}}}},"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}}}}}},"404":{"description":"Export not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Retrieve an export (deprecated)","tags":["Exports"]}},"/v1/cloud-print/print-jobs":{"post":{"description":"Enqueues client-rendered content for printing. The bytes are stored verbatim and served to the printer as-is. Returns the job with `status: ready`; poll `GET /v1/cloud-print/print-jobs/{id}` until `done`.","operationId":"PrintJobsController_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":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrintJobDto"}}}},"responses":{"201":{"description":"Print job enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrintJob"}}}},"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}}}}}},"404":{"description":"Register not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Enqueue a print job","tags":["Cloud Printing"]},"get":{"description":"Returns the merchant’s print jobs, newest first.","operationId":"PrintJobsController_list","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max results (default 50, max 100).","schema":{"type":"string"}},{"name":"register_id","required":false,"in":"query","description":"Filter to a single register.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["ready","in_flight","done","cancelled"],"type":"string"}}],"responses":{"200":{"description":"Print jobs returned","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PrintJob"}}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"List print jobs","tags":["Cloud Printing"]}},"/v1/cloud-print/print-jobs/{printJobId}":{"get":{"operationId":"PrintJobsController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"printJobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Print job returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrintJob"}}}},"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}}}}}},"404":{"description":"Print job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Retrieve a print job","tags":["Cloud Printing"]},"delete":{"description":"Cancels a job that has not yet been claimed by a printer. Only valid while `status` is `ready`.","operationId":"PrintJobsController_cancel","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"printJobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Print job cancelled"},"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}}}}}},"404":{"description":"Print job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}},"409":{"description":"Job already in-flight or printed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"print_job_not_cancellable","value":{"code":"print_job_not_cancellable","message":"Job already in-flight or printed","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Cancel a print job","tags":["Cloud Printing"]}},"/v1/cloud-print/printer-credentials":{"get":{"description":"Returns the merchant’s CloudPRNT login (username + secret) and the endpoint URL to configure. The secret is generated by the platform on first access, so this always returns credentials.","operationId":"PrinterCredentialsController_get","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printer credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrinterCredentials"}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Get printer credentials","tags":["Cloud Printing"]},"put":{"description":"Sets a friendly Basic-auth username (e.g. the shop domain) for the printer login. The platform-owned secret is unchanged. Returns the full credentials.","operationId":"PrinterCredentialsController_setUsername","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPrinterUsernameDto"}}}},"responses":{"200":{"description":"Printer credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrinterCredentials"}}}},"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":"Printer username already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"resource_conflict","value":{"code":"resource_conflict","message":"Printer username already in use","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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Set the printer username","tags":["Cloud Printing"]}},"/v1/cloud-print/printer-credentials/rotate":{"post":{"description":"Generates a new secret. Any printer still configured with the old one must be reconfigured.","operationId":"PrinterCredentialsController_rotate","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printer credentials with the new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrinterCredentials"}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Rotate the printer secret","tags":["Cloud Printing"]}},"/v1/cloud-print/printers":{"get":{"description":"Returns the printers the platform has seen for the merchant, most-recently-active first. A printer appears once it has polled the CloudPRNT endpoint at least once; health and telemetry reflect its latest poll.","operationId":"PrintersController_list","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Printers returned","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Printer"}}}}},"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}}}}}}},"security":[{"BearerAuth":[]}],"summary":"List printers","tags":["Cloud Printing"]}},"/v1/cloud-print/printers/{printerId}":{"patch":{"description":"Partial update of a printer — currently the operator-assigned nickname. A null or empty `name` clears it (display falls back to the MAC address). Register mapping is not settable here yet.","operationId":"PrintersController_update","parameters":[{"name":"X-OpenFiskal-Merchant","in":"header","description":"Merchant identifier returned by the merchants resource.","required":true,"schema":{"type":"string"}},{"name":"printerId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrinterDto"}}}},"responses":{"200":{"description":"Updated printer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Printer"}}}},"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}}}}}},"404":{"description":"Printer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"},"examples":{"default":{"summary":"not_found","value":{"code":"not_found","message":"The requested resource does not exist.","retryable":false}}}}}}},"security":[{"BearerAuth":[]}],"summary":"Update a printer","tags":["Cloud Printing"]}}},"info":{"title":"OpenFiskal API","description":"Complete server-to-server API surface served by the OpenFiskal api process.\n\nThe docs site splits this into per-tab specs (Fiscalization API and Reporting\nAPI) for navigation; this variant lists every path served by the running api\nand is the canonical source for client code generators.","version":"1.1.0","contact":{},"license":{"name":"Proprietary"}},"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."},{"name":"Exports","description":"Create and inspect asynchronous fiscal export jobs."},{"name":"Cloud Printing","description":"Star CloudPRNT cloud printing.\n\nConsumer: the integrator (server-to-server, merchant-scoped via the\n`X-OpenFiskal-Merchant` header). The physical printer is a *separate* consumer —\nit polls the unversioned `/cloud-print/star` endpoint using the CloudPRNT wire\nprotocol and is intentionally not part of this REST API."}],"servers":[{"url":"https://api.openfiskal.com/v1","description":"Production"},{"url":"https://sandbox.api.openfiskal.com/v1","description":"Sandbox"}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","bearerFormat":"API key","type":"http"}},"schemas":{"FiscalIdentityDeuDto":{"type":"object","properties":{"country_code":{"type":"string","enum":["DEU"],"example":"DEU"},"tax_number":{"type":"string","example":"21/815/08150","description":"Steuernummer"},"vat_id":{"type":"string","example":"DE123456789","description":"USt-IdNr"}},"required":["country_code","tax_number","vat_id"]},"FiscalIdentityAutDto":{"type":"object","properties":{"country_code":{"type":"string","enum":["AUT"],"example":"AUT"},"vat_id":{"type":"string","example":"ATU12345678"},"tax_number":{"type":"string"},"legal_entity_id_type":{"type":"string","enum":["VAT_ID","TAX_ID","GLN"],"example":"VAT_ID"},"gln":{"type":"string","description":"13-digit Global Location Number, required when legal_entity_id_type is GLN"}},"required":["country_code","legal_entity_id_type"]},"FiscalIdentityItaDto":{"type":"object","properties":{"country_code":{"type":"string","enum":["ITA"],"example":"ITA"},"tax_number":{"type":"string","example":"12345678901","description":"Tax number (Codice Fiscale). 11 numeric digits or 16 alphanumeric characters. Example: 12345678901 or RSSMRA85T10A562S. For companies, this may be identical to the VAT number."},"vat_number":{"type":"string","example":"IT12345678901","description":"VAT number (Partita IVA)"},"legal_entity_type":{"type":"string","enum":["COMPANY","INDIVIDUAL"],"example":"COMPANY","description":"Select whether your organization is a company (Societa) or an individual (Persona fisica)."},"fisconline_password":{"type":"string","description":"Fisconline Password"},"fisconline_pin":{"type":"string","description":"Fisconline PIN"},"fisconline_user":{"type":"string","description":"Fisconline User - The Codice Fiscale of the person authorized to access the Agenzia delle Entrate portal on behalf of the business."}},"required":["country_code","tax_number","vat_number","legal_entity_type","fisconline_password","fisconline_pin","fisconline_user"]},"AddressResponse":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string","nullable":true},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-3 country code.","minLength":3,"maxLength":3,"example":"DEU"}},"required":["line1","city","postal_code","country_code"]},"Merchant":{"type":"object","properties":{"id":{"type":"string"},"legal_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-3 country code for the legal entity.","minLength":3,"maxLength":3,"example":"DEU"},"status":{"type":"string","enum":["active","inactive"]},"address":{"$ref":"#/components/schemas/AddressResponse"},"fiscal_identities":{"type":"array","description":"Country-specific fiscal identities.","items":{"oneOf":[{"title":"FiscalIdentityDEU","allOf":[{"$ref":"#/components/schemas/FiscalIdentityDeuDto"}]},{"title":"FiscalIdentityAUT","allOf":[{"$ref":"#/components/schemas/FiscalIdentityAutDto"}]},{"title":"FiscalIdentityITA","allOf":[{"$ref":"#/components/schemas/FiscalIdentityItaDto"}]}],"discriminator":{"propertyName":"country_code","mapping":{"DEU":"#/components/schemas/FiscalIdentityDeuDto","AUT":"#/components/schemas/FiscalIdentityAutDto","ITA":"#/components/schemas/FiscalIdentityItaDto"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","legal_name","country_code","status","address","fiscal_identities","created_at","updated_at"]},"MerchantListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}},"required":["data"]},"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"]},"AddressDto":{"type":"object","properties":{"line1":{"type":"string","example":"Musterstr. 1"},"line2":{"type":"string","example":"Apt 4","nullable":true},"city":{"type":"string","example":"Berlin"},"postal_code":{"type":"string","example":"10115"},"country_code":{"type":"string","example":"DEU","minLength":3,"maxLength":3,"description":"ISO 3166-1 alpha-3 (uppercase)"}},"required":["line1","city","postal_code","country_code"]},"CreateMerchantDto":{"type":"object","properties":{"legal_name":{"type":"string","example":"Test GmbH"},"country_code":{"type":"string","example":"DEU","minLength":3,"maxLength":3,"description":"ISO 3166-1 alpha-3 country code for the legal entity (uppercase)"},"address":{"$ref":"#/components/schemas/AddressDto"},"fiscal_identities":{"type":"array","description":"Country-specific fiscal identities","items":{"oneOf":[{"title":"FiscalIdentityDEU","allOf":[{"$ref":"#/components/schemas/FiscalIdentityDeuDto"}]},{"title":"FiscalIdentityAUT","allOf":[{"$ref":"#/components/schemas/FiscalIdentityAutDto"}]},{"title":"FiscalIdentityITA","allOf":[{"$ref":"#/components/schemas/FiscalIdentityItaDto"}]}],"discriminator":{"propertyName":"country_code","mapping":{"DEU":"#/components/schemas/FiscalIdentityDeuDto","AUT":"#/components/schemas/FiscalIdentityAutDto","ITA":"#/components/schemas/FiscalIdentityItaDto"}}}}},"required":["legal_name","country_code","address"]},"UpdateMerchantDto":{"type":"object","properties":{"legal_name":{"type":"string","example":"Updated GmbH"},"status":{"type":"string","enum":["active","inactive"],"example":"inactive"},"address":{"$ref":"#/components/schemas/AddressDto"},"fiscal_identities":{"type":"array","description":"Country-specific fiscal identities (merge by country key)","items":{"oneOf":[{"title":"FiscalIdentityDEU","allOf":[{"$ref":"#/components/schemas/FiscalIdentityDeuDto"}]},{"title":"FiscalIdentityAUT","allOf":[{"$ref":"#/components/schemas/FiscalIdentityAutDto"}]},{"title":"FiscalIdentityITA","allOf":[{"$ref":"#/components/schemas/FiscalIdentityItaDto"}]}],"discriminator":{"propertyName":"country_code","mapping":{"DEU":"#/components/schemas/FiscalIdentityDeuDto","AUT":"#/components/schemas/FiscalIdentityAutDto","ITA":"#/components/schemas/FiscalIdentityItaDto"}}}}}},"RegisterFiscalization":{"type":"object","properties":{"regime":{"type":"string"},"fiscalized_at":{"type":"string","format":"date-time","nullable":true},"tse_serial":{"type":"string","nullable":true},"client_id":{"type":"string","nullable":true}},"required":["regime"]},"Register":{"type":"object","properties":{"id":{"type":"string"},"merchant_id":{"type":"string"},"location_id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","inactive"]},"fiscalization_status":{"type":"string","enum":["not_fiscalized","pending","failed","fiscalized","decommissioned"]},"fiscalization":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RegisterFiscalization"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","merchant_id","location_id","name","status","fiscalization_status","created_at"]},"RegisterListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Register"}}},"required":["data"]},"CreateRegisterDto":{"type":"object","properties":{"location_id":{"type":"string","example":"loc_abc123","description":"ID of the location this register belongs to"},"name":{"type":"string","example":"Register 1"},"external_id":{"type":"string","example":"POS-001","description":"Your own identifier for this register"}},"required":["location_id","name"]},"UpdateRegisterDto":{"type":"object","properties":{"name":{"type":"string","example":"Register 1"},"external_id":{"type":"string","example":"POS-001","description":"Your own identifier for this register"},"status":{"type":"string","enum":["active","inactive"],"example":"active"}}},"Location":{"type":"object","properties":{"id":{"type":"string"},"merchant_id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"address":{"$ref":"#/components/schemas/AddressResponse"},"created_at":{"type":"string","format":"date-time"}},"required":["id","merchant_id","name","address","created_at"]},"LocationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["data"]},"CreateLocationDto":{"type":"object","properties":{"name":{"type":"string","example":"Main Store"},"external_id":{"type":"string","example":"loc-001"},"address":{"$ref":"#/components/schemas/AddressDto"},"timezone":{"type":"string","example":"Europe/Berlin"}},"required":["name","address","timezone"]},"UpdateLocationDto":{"type":"object","properties":{"name":{"type":"string","example":"Updated Store Name"},"external_id":{"type":"string","example":"loc-002"},"address":{"$ref":"#/components/schemas/AddressDto"},"timezone":{"type":"string","example":"Europe/Vienna"}}},"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"]},"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"]},"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"]},"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"]},"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-04","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"]},"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"]},"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"]},"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"]},"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"]},"FiscalInformationRTSignature":{"type":"object","properties":{"signed_at":{"type":"string","format":"date-time"},"signature":{"type":"string"}},"required":["signed_at","signature"]},"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"]},"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"]},"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"]},"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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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"]},"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"]},"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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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":"#/components/schemas/FiscalInformationKassenSichV","RKSV":"#/components/schemas/FiscalInformationRKSV","RT":"#/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"]},"PaymentDto":{"type":"object","properties":{"payment_id":{"type":"string","example":"pay_1001_card","description":"Integrator payment ID"},"method":{"type":"string","enum":["cash","card","voucher","gift_card","bank_transfer","digital_wallet","store_credit","other"],"example":"card"},"amount":{"type":"string","example":"47.50","description":"Payment amount as decimal string"},"currency":{"type":"string","example":"EUR","description":"ISO 4217 3-char currency code"},"status":{"type":"string","enum":["captured","refunded"],"example":"captured"},"processor":{"type":"string","example":"sumup","description":"Payment processor name"},"card_brand":{"type":"string","example":"visa","description":"Card brand if method is card"},"processor_reference":{"type":"string","example":"ch_123","description":"Processor reference ID"},"processed_at":{"type":"string","example":"2026-02-26T12:05:00Z","description":"When the payment was processed (ISO 8601)"},"gift_card_id":{"type":"string","example":"gc_abc123","description":"Integrator-supplied gift card identifier. Only meaningful when method is \"gift_card\". Flows through to DSFinV-K voucher_id on MehrzweckgutscheinEinloesung lines."}},"required":["payment_id","method","amount","currency","status"]},"CompleteOperationDto":{"type":"object","properties":{"payments":{"description":"Payments tendered for this operation","type":"array","items":{"$ref":"#/components/schemas/PaymentDto"}},"completed_at":{"type":"string","example":"2026-02-26T12:05:00Z","description":"Completion timestamp (ISO 8601), defaults to now"}},"required":["payments"]},"VoidOperationDto":{"type":"object","properties":{"reason":{"type":"string","enum":["void_before_completion","customer_abandoned_checkout","operator_cancelled","payment_failed"],"example":"customer_abandoned_checkout","description":"Reason for voiding the operation"}},"required":["reason"]},"CreateDsfinvkExportDto":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2026-03-01T00:00:00Z"},"to":{"type":"string","format":"date-time","example":"2026-03-31T23:59:59Z"},"register_id":{"type":"string","example":"reg_01HABC","description":"Register to export. DSFinV-K is per-register: the archive covers exactly this register, and it must be on the KassenSichV regime. The window is silently clamped to the period the register was live."}},"required":["from","to","register_id"]},"ExportType":{"type":"string","enum":["dsfinvk","tse"]},"ExportError":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable failure description."},"details":{"type":"object","nullable":true,"description":"Structured error payload (e.g. provider error response). Shape varies by export type."}},"required":["message"]},"TseExportFreshDrain":{"type":"string","enum":["not_needed","completed","timed_out","failed"],"description":"What draining was attempted when the archive was compiled. `not_needed` means the window closed before the data we already held, so the device was never contacted."},"TseExportCoverageDto":{"type":"object","properties":{"tse_serial_numbers":{"description":"Every security device that contributed. More than one when the window spans a device swap. A Swissbit TSE serves every till at a location, so an archive scoped to one register contains its neighbours at the same premises.","type":"array","items":{"type":"string"}},"signature_counter_first":{"type":"number","nullable":true,"description":"Lowest signature counter present."},"signature_counter_last":{"type":"number","nullable":true,"description":"Highest signature counter present."},"log_message_count":{"type":"number","description":"How many log messages the archive contains."},"covered_from":{"type":"string","format":"date-time","nullable":true,"description":"Log time of the earliest message inside, not the requested window start."},"covered_to":{"type":"string","format":"date-time","nullable":true,"description":"Log time of the latest message inside, not the requested window end."},"covers_requested_window":{"type":"boolean","description":"Whether coverage reached the requested end of the window. False means the archive stops early because the security device could not be drained in time. It does NOT mean the window was empty: a quiet period legitimately contains no messages while still being fully covered."},"last_drained_at":{"type":"string","format":"date-time","nullable":true,"description":"When log messages were last drained off the device, i.e. how current this archive is."},"fresh_drain":{"description":"What draining was attempted when the archive was compiled. `not_needed` means the window closed before the data we already held, so the device was never contacted.","allOf":[{"$ref":"#/components/schemas/TseExportFreshDrain"}]},"gapless":{"type":"boolean","description":"Whether the signature counters present form an unbroken run. A gap means a drain was lost, and because a vendor export is destructive it cannot be recovered."}},"required":["tse_serial_numbers","log_message_count","covers_requested_window","fresh_drain","gapless"]},"Export":{"type":"object","properties":{"id":{"type":"string"},"type":{"allOf":[{"$ref":"#/components/schemas/ExportType"}]},"status":{"type":"string","enum":["pending","completed","failed"]},"register_id":{"type":"string","nullable":true},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"download_url":{"type":"string","nullable":true,"description":"Signed URL to download the export artifact. Present only when status is `completed`."},"error":{"nullable":true,"description":"Failure information. Present only when status is `failed`.","allOf":[{"$ref":"#/components/schemas/ExportError"}]},"coverage":{"nullable":true,"description":"What the artifact covers. TSE exports only, and only once `completed`. Absent for other export types and while the export is still pending.","allOf":[{"$ref":"#/components/schemas/TseExportCoverageDto"}]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","type","status","from","to","created_at"]},"CreateTseExportDto":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2026-03-01T00:00:00Z"},"to":{"type":"string","format":"date-time","example":"2026-03-31T23:59:59Z"},"register_id":{"type":"string","example":"reg_01HABC","description":"Register whose signing device to export. NOT the scope: the register resolves to the TSE(s) it signed on during the window, and the archive covers those devices in full. A Swissbit TSE is shared by every register at the same business premises and offers no filtered export, so the archive contains their log messages too. A window spanning a device change resolves to both devices."}},"required":["from","to","register_id"]},"CreateExportDto":{"type":"object","properties":{"type":{"example":"dsfinvk","description":"Country-specific fiscal export type.","allOf":[{"$ref":"#/components/schemas/ExportType"}]},"register_id":{"type":"string","example":"reg_01HABC","description":"Optional register to scope the export to. When omitted, the export covers all eligible registers for the merchant under the matching fiscal regime."},"from":{"type":"string","format":"date-time","example":"2026-03-01T00:00:00Z"},"to":{"type":"string","format":"date-time","example":"2026-03-31T23:59:59Z"}},"required":["type","from","to"]},"CreatePrintJobDto":{"type":"object","properties":{"media_type":{"type":"string","enum":["application/vnd.star.starprnt","application/vnd.star.line","image/vnd.star.png","image/png","text/vnd.star.markup","text/plain"],"example":"text/plain","description":"CloudPRNT content media type the bytes are encoded as."},"content_base64":{"type":"string","description":"The print job content, base64-encoded. Decoded and stored verbatim; served to the printer as-is.","example":"SGVsbG8gcHJpbnRlcg=="},"register_id":{"type":"string","example":"reg_01HABC","description":"Target register. A printer mapped to this register prints the job; when omitted the job is merchant-wide."},"printer_id":{"type":"string","example":"kp_01HABC","description":"Target printer (a printer id from the printers resource). When set, ONLY that printer prints the job — the client owns the routing decision, no register mapping needed. Takes precedence over `register_id`."},"operation_id":{"type":"string","example":"op_01HABC","description":"Optional print-once handle. Reusing the same value returns the existing job instead of creating a duplicate."}},"required":["media_type","content_base64"]},"PrintJob":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","in_flight","done","cancelled"]},"media_type":{"type":"string","description":"CloudPRNT content media type of the stored bytes."},"byte_size":{"type":"number","description":"Size of the stored content in bytes."},"register_id":{"type":"string","nullable":true,"description":"Target register, or null for a merchant-wide job."},"operation_id":{"type":"string","nullable":true,"description":"Print-once handle supplied on creation, if any."},"cancellation_reason":{"type":"string","nullable":true,"description":"Why a cancelled job was cancelled (BY_USER, TOO_OLD); null unless status is cancelled."},"label":{"type":"string","description":"Human-readable label shown in the console queue view."},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","media_type","byte_size","label","created_at"]},"PrinterCredentials":{"type":"object","properties":{"cloudprnt_url":{"type":"string","description":"The CloudPRNT endpoint URL to configure on the printer.","example":"https://api.openfiskal.com/cloud-print/star"},"username":{"type":"string","description":"Basic-auth username.","example":"demo-store.myshopify.com"},"secret":{"type":"string","description":"Basic-auth secret (password)."}},"required":["cloudprnt_url","username","secret"]},"SetPrinterUsernameDto":{"type":"object","properties":{"username":{"type":"string","description":"CloudPRNT Basic-auth username the printer is configured with. Unique per environment.","example":"demo-store.myshopify.com","maxLength":255}},"required":["username"]},"Printer":{"type":"object","properties":{"id":{"type":"string"},"mac_address":{"type":"string","description":"Printer MAC address — the stable device identity."},"name":{"type":"string","nullable":true,"description":"Operator-assigned nickname (set in the console)."},"model":{"type":"string","nullable":true,"description":"Printer model, best-effort from the poll `clientType` (not every firmware reports it)."},"health_state":{"type":"string","enum":["OK","PAPER_LOW","PAPER_EMPTY","COVER_OPEN","ERROR","UNKNOWN"],"description":"Device health derived from the last poll’s Star ASB status."},"last_status_code":{"type":"string","nullable":true,"description":"Decoded status code from the last poll, e.g. \"200 OK\"."},"register_id":{"type":"string","nullable":true,"description":"The POS register this printer is mapped to, or null when it serves merchant-wide jobs."},"register_name":{"type":"string","nullable":true,"description":"Name of the mapped register, for display."},"last_seen_at":{"type":"string","format":"date-time","description":"When the platform last received a poll from this printer."}},"required":["id","mac_address","health_state","last_seen_at"]},"UpdatePrinterDto":{"type":"object","properties":{"name":{"type":"string","nullable":true,"maxLength":255,"description":"Operator-assigned nickname. Null or empty clears it (falls back to the MAC).","example":"Front counter"}}}}}}