{"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_delete_conflict","value":{"code":"register_delete_conflict","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":"fiscalization_conflict","value":{"code":"fiscalization_conflict","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":{"200":{"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":"decommission_conflict","value":{"code":"decommission_conflict","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":"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_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_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":"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_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":"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_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":{"patch":{"description":"Finalizes an operation and attaches the typed payment contract used for fiscalization and reconciliation.","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"}]},{"title":"SessionOpenOperation","allOf":[{"$ref":"#/components/schemas/SessionOpenOperation"}]},{"title":"SessionCashAdjustmentOperation","allOf":[{"$ref":"#/components/schemas/SessionCashAdjustmentOperation"}]},{"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_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}}}}}},"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":{"patch":{"description":"Voids an open operation before completion. Use a return operation after completion.","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"}]},{"title":"SessionOpenOperation","allOf":[{"$ref":"#/components/schemas/SessionOpenOperation"}]},{"title":"SessionCashAdjustmentOperation","allOf":[{"$ref":"#/components/schemas/SessionCashAdjustmentOperation"}]},{"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_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}}}}}},"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":{"post":{"description":"Enqueues an asynchronous export job and returns immediately with `202 Accepted` and `status: pending`. Poll `GET /exports/{exportId}` until `status` is `completed` (then `download_url` is set) or `failed`.","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","tags":["Exports"]}},"/v1/exports/{exportId}":{"get":{"description":"Returns the export job. When `status` is `completed`, `download_url` is a signed URL to fetch the artifact. When `status` is `failed`, `error.message` (and optional `error.details`) describe why.","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","tags":["Exports"]}}},"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."}],"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"}},"next_cursor":{"type":"string","nullable":true}},"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."},"request_id":{"type":"string","description":"Stable request trace identifier."},"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"}},"next_cursor":{"type":"string","nullable":true}},"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"}},"next_cursor":{"type":"string","nullable":true}},"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"}}},"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"]},"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":{"title":{"type":"string","example":"Café Latte"},"quantity":{"type":"number","example":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)"},"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","taxes"]},"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."},"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"}]},"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"}},"required":["source","currency","pretax_amount","tax_amount","tip_amount","total_amount","line_items","type"]},"CreateReturnOperationDto":{"type":"object","properties":{"register_id":{"type":"string","example":"reg_abc123","description":"Required for POS, must be null for ONLINE."},"source":{"type":"string","enum":["POS","ONLINE"],"example":"POS"},"currency":{"type":"string","example":"USD","description":"ISO 4217 currency code"},"external_id":{"type":"string","example":"order-12345","description":"Merchant or POS identifier for the upstream order."},"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"}]},"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":["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."},"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"}]},"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":["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"]},"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"},"counted_closing_amount":{"type":"string","example":"127.50","description":"Merchant-counted closing cash balance as a decimal string. Must be ≥ 0."},"discrepancy_note":{"type":"string","example":"Two coins from the day before were unaccounted for."}},"required":["type","register_id","currency","counted_closing_amount"]},"FiscalInformationKassenSichVStartEvent":{"type":"object","properties":{"signed_at":{"type":"string","format":"date-time"}},"required":["signed_at"]},"FiscalInformationKassenSichVEndEvent":{"type":"object","properties":{"signed_at":{"type":"string","format":"date-time"},"transaction_counter":{"type":"number"},"signature":{"type":"string"},"public_key":{"type":"string"},"process_type":{"type":"string"},"process_data":{"type":"string"}},"required":["signed_at","transaction_counter","signature","public_key","process_type","process_data"]},"FiscalInformationKassenSichVVerification":{"type":"object","properties":{"qr_data":{"type":"string"}},"required":["qr_data"]},"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"},"title":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"string"},"total_amount":{"type":"string"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/LineItemTax"}}},"required":["id","title","quantity","unit_price","total_amount","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":["pending","authorized","captured","failed","voided","refunded"]},"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}},"required":["id","payment_id","method","amount","currency","status"]},"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"}},"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"]},"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"]},"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"},"counted_closing_amount":{"type":"string","description":"Merchant-counted closing cash balance as a decimal string."},"discrepancy_note":{"type":"string","nullable":true}},"required":["id","merchant_id","source","status","currency","resource_version","created_at","updated_at","type","counted_closing_amount"]},"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":["pending","authorized","captured","failed","voided","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)"}},"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"]},"ExportType":{"type":"string","enum":["dsfinvk"],"description":"Country-specific fiscal export type."},"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"]},"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"]},"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"}]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","type","status","from","to","created_at"]}}}}