{"info":{"title":"Click2Check API","version":"0.0.0","description":"REST API каси Click2Check: товари, каси, зміни, чеки й звіти. Специфікація OpenAPI 3.2, доступ за API-токеном."},"externalDocs":{"url":"https://click2check.com.ua/docs"},"servers":[{"url":"https://api.click2check.com.ua/api"}],"components":{"securitySchemes":{"apiToken":{"type":"http","scheme":"bearer","description":"An API token: 36 base62 characters."},"session":{"type":"apiKey","in":"cookie","name":"__Host-session","description":"The session cookie a sign-in sets, sent by the frontend's origin only."}},"schemas":{"UndefinedError":{"title":"UndefinedError","type":"object","properties":{"defined":{"const":false},"code":{"type":"string"},"message":{"type":"string"},"data":{}},"required":["defined","code","message"]},"ServiceUnavailable":{"title":"SERVICE_UNAVAILABLE","type":"object","properties":{"defined":{"const":true},"code":{"const":"SERVICE_UNAVAILABLE"},"message":{"type":"string"},"data":{"type":"object","properties":{"status":{"type":"string","const":"FAILURE"}},"required":["status"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Unauthorized":{"title":"UNAUTHORIZED","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNAUTHORIZED"},"message":{"type":"string"},"data":{"oneOf":[{"type":"object","properties":{"reason":{"type":"string","const":"UNAUTHENTICATED","description":"No valid credentials: an API token (`Authorization: Bearer <token>`) or a session cookie from the frontend's origin."}},"required":["reason"],"additionalProperties":false},{"type":"object","properties":{"reason":{"type":"string","const":"SECOND_FACTOR_REQUIRED","description":"The session still waits for the second factor (a TOTP code)."},"email":{"description":"Email of the account being signed in to, as GET /me returns it, for the TOTP step to show.","examples":["user@example.com"],"type":["string","null"]}},"required":["reason","email"],"additionalProperties":false}]}},"required":["defined","code","message","data"]},"NotFound":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_NOT_FOUND"],"description":"Unknown to the fiscal server, not one of the team's cash registers (added by the DPS sync, POST /cash-registers), or not assigned by an admin to the signed-in cashier."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_ACCESS_DENIED"],"description":"CASH_REGISTER_ACCESS_DENIED: the cash register's key has no access to the cash register."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["KEP_NOT_UPLOADED"],"description":"KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"BadGateway":{"title":"BAD_GATEWAY","type":"object","properties":{"defined":{"const":true},"code":{"const":"BAD_GATEWAY"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["KEP_REJECTED"],"description":"The fiscal server refused the request's KEP (the cash register's, or the organization's for the team's own commands) as an invalid key or signature; or DepositSign refused to sign with it, e.g. its password changed, the key was locked, or the stored key token is no longer accepted (another was taken elsewhere, or the certificate expired). An admin connects or binds the key again."},"source":{"type":"string","enum":["FISCAL_SERVER","DEPOSITSIGN","KEY_FILE"],"description":"FISCAL_SERVER: the fiscal server refused the signed request. DEPOSITSIGN: DepositSign refused to sign it, so nothing reached the fiscal server. KEY_FILE: the stored key file's password no longer opens it, or its certificate is out of date, revoked or blocked, so nothing reached the fiscal server."},"message":{"type":"string","description":"FISCAL_SERVER: the server's text. DEPOSITSIGN: DepositSign's text prefixed with «DepositSign: », or, for a rejected stored token, the backend's text in Ukrainian. KEY_FILE: the backend's text in Ukrainian.","examples":["Повідомлення не є коректним блоком даних кваліфікованого електронного підпису"]}},"required":["reason","source","message"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden2":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_ACCESS_DENIED","READ_ONLY"],"description":"CASH_REGISTER_ACCESS_DENIED: the cash register's key has no access to the cash register. READ_ONLY: the signed-in user is an accountant: sees every cash register and its data, changes nothing."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict2":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_IN_USE","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED"],"description":"CASH_REGISTER_IN_USE: another device holds the cash register, `force` takes it over. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["IDEMPOTENCY_KEY_REUSED"],"description":"The key was used for a different request."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"ServiceUnavailable2":{"title":"SERVICE_UNAVAILABLE","type":"object","properties":{"defined":{"const":true},"code":{"const":"SERVICE_UNAVAILABLE"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["FISCAL_SERVER_UNREACHABLE"],"description":"The fiscal server didn't answer, and the cash register couldn't switch to offline mode: a document a cash register with offline mode registers while the server fails switches it automatically, answered with an offline fiscal number."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden3":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_ACCESS_DENIED","OFFLINE_LIMIT_EXCEEDED","READ_ONLY"],"description":"CASH_REGISTER_ACCESS_DENIED: the cash register's key has no access to it. OFFLINE_LIMIT_EXCEEDED: offline beyond 36 hours per session or 168 per month, refused only when the backend enforces these limits (GET /cash-registers/{num}/offline, `limits`); works again once online. READ_ONLY: the signed-in user is an accountant: sees every cash register and its data, changes nothing."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict3":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"oneOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED"],"description":"CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."}},"required":["reason"],"additionalProperties":false},{"type":"object","properties":{"reason":{"type":"string","const":"SHIFT_ALREADY_OPEN","description":"A shift is open already: on this cash register, or, as the fiscal server refuses too, on another one by the cash register key's owner, who may work one shift at a time."},"message":{"description":"The fiscal server's text when it refused the opening, which names the cash register the shift is open on; null when this cash register's state showed its open shift before sending.","examples":["Особою Іван Іванович Іванов наразі відкрито зміну на ПРРО з фіскальним номером 4000002411"],"type":["string","null"]}},"required":["reason","message"],"additionalProperties":false}]}},"required":["defined","code","message","data"]},"UnprocessableContent2":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["DOCUMENT_REJECTED","IDEMPOTENCY_KEY_REUSED"],"description":"DOCUMENT_REJECTED: the fiscal server rejected the document. IDEMPOTENCY_KEY_REUSED: the key was used for a different request."},"message":{"description":"Error text from the fiscal server, for DOCUMENT_REJECTED.","examples":["Помилка валідації документа"],"type":"string"}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"ServiceUnavailable3":{"title":"SERVICE_UNAVAILABLE","type":"object","properties":{"defined":{"const":true},"code":{"const":"SERVICE_UNAVAILABLE"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["FISCAL_SERVER_UNREACHABLE","DEPOSITSIGN_UNREACHABLE","EUSIGN_UNAVAILABLE"],"description":"FISCAL_SERVER_UNREACHABLE: the fiscal server didn't answer, and the cash register couldn't switch to offline mode: a document a cash register with offline mode registers while the server fails switches it automatically, answered with an offline fiscal number. DEPOSITSIGN_UNREACHABLE: DepositSign didn't sign with the cash register's key, or not in time. EUSIGN_UNAVAILABLE: EUSign couldn't sign with the cash register's key file, or not in time. Either way the cash register stays in its mode; retry with the same idempotency key."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound2":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_FOUND"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict4":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound3":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_FOUND","CASH_REGISTER_NOT_FOUND"],"description":"CASH_REGISTER_NOT_FOUND: the fiscal server no longer has the shift's cash register."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden4":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_ACCESS_DENIED","SHIFT_OPENED_BY_ANOTHER_CASHIER","OFFLINE_LIMIT_EXCEEDED","READ_ONLY"],"description":"CASH_REGISTER_ACCESS_DENIED: the cash register's key has no access to it. SHIFT_OPENED_BY_ANOTHER_CASHIER: only that cashier or a chief cashier may close it. OFFLINE_LIMIT_EXCEEDED: offline beyond 36 hours per session or 168 per month, refused only when the backend enforces these limits (GET /cash-registers/{num}/offline, `limits`); works again once online. READ_ONLY: the signed-in user is an accountant: sees every cash register and its data, changes nothing."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict5":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"oneOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_ALREADY_CLOSED","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED"],"description":"CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."}},"required":["reason"],"additionalProperties":false},{"type":"object","properties":{"reason":{"type":"string","const":"Z_REPORT_TOTALS_MISMATCH","description":"The fiscal server's shift totals (LastShiftTotals) differ from the Z-report's, so nothing was filed and the shift stays open. Storned receipts match whether the server counts them or not."},"local":{"type":"object","properties":{"sales":{"type":"object","properties":{"sum":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[42]}},"required":["sum","receipts"],"additionalProperties":false},"refunds":{"type":"object","properties":{"sum":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[42]}},"required":["sum","receipts"],"additionalProperties":false},"serviceDeposit":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["500.00"]},"serviceWithdrawal":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["12000.00"]}},"required":["sales","refunds","serviceDeposit","serviceWithdrawal"],"additionalProperties":false,"description":"The totals the Z-report would file."},"server":{"type":"object","properties":{"sales":{"type":"object","properties":{"sum":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[42]}},"required":["sum","receipts"],"additionalProperties":false},"refunds":{"type":"object","properties":{"sum":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[42]}},"required":["sum","receipts"],"additionalProperties":false},"serviceDeposit":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["500.00"]},"serviceWithdrawal":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["12000.00"]}},"required":["sales","refunds","serviceDeposit","serviceWithdrawal"],"additionalProperties":false,"description":"The fiscal server's totals of the shift."}},"required":["reason","local","server"],"additionalProperties":false}]}},"required":["defined","code","message","data"]},"NotFound4":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["Z_REPORT_NOT_FOUND"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden5":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CASH_REGISTER_ACCESS_DENIED","SHIFT_OPENED_BY_ANOTHER_CASHIER","OFFLINE_LIMIT_EXCEEDED","READ_ONLY"],"description":"CASH_REGISTER_ACCESS_DENIED: the cash register's key has no access to it. SHIFT_OPENED_BY_ANOTHER_CASHIER: only that cashier or a chief cashier may work in the open shift. OFFLINE_LIMIT_EXCEEDED: offline beyond 36 hours per session or 168 per month, refused only when the backend enforces these limits (GET /cash-registers/{num}/offline, `limits`); works again once online. READ_ONLY: the signed-in user is an accountant: sees every cash register and its data, changes nothing."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict6":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN","SHIFT_ALREADY_OPEN","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED","TAX_RATES_CHANGED","CHAIN_CHANGED"],"description":"The receipt opens a fiscal shift itself if the cash register's is closed, and leaves it open; the opening's failures come as the receipt's, and tell the team's admins (SHIFT_AUTO_OPEN_FAILED in GET /notifications). SHIFT_NOT_OPEN: the open shift's Z-report is registered, or its closing is still being sent, so no receipt nor new shift may follow yet; or the shift opened for the receipt was closed before it. SHIFT_ALREADY_OPEN: opening the shift was refused, as the cash register key's owner has a shift open on another cash register. CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry. TAX_RATES_CHANGED: a rate the items' letters name was edited while the receipt was being registered; nothing was registered, and a retry is calculated at the rates now in force (GET /tax-rates). CHAIN_CHANGED: another receipt of the instalment's chain was stored, storned or returned while it was being registered, so its «Залишок до сплати» no longer holds; nothing was registered, and a retry counts it anew."},"message":{"description":"SHIFT_ALREADY_OPEN only: the fiscal server's text, which names the cash register the shift is open on; null when the cash register's state showed the open shift before sending.","examples":["Особою Іван Іванович Іванов наразі відкрито зміну на ПРРО з фіскальним номером 4000002411"],"type":["string","null"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent3":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["DOCUMENT_REJECTED","IDEMPOTENCY_KEY_REUSED","PAYMENT_MISMATCH","DISCOUNT_TOO_LARGE","UNKNOWN_TAX_LETTER","AMOUNT_TOO_LARGE","PART_PAYMENT_TOO_LARGE","PART_PAYMENT_ADDED_TAX","PREPAYMENT_OF_ANOTHER_MODE","CHAIN_REFUNDED"],"description":"DOCUMENT_REJECTED: the fiscal server rejected the document. IDEMPOTENCY_KEY_REUSED: the key was used for a different request. PAYMENT_MISMATCH: the payments don't add up to the amount to pay (the total, or `partPayment.amount`), or the cash part isn't that amount rounded to 0.50 UAH (`message` names the expected amounts). DISCOUNT_TOO_LARGE: a discount is more than the amount it's taken from. UNKNOWN_TAX_LETTER: an item's letter names no rate the receipt may use: for a sale, the team's rates; for a refund of a sale the backend registered, that sale's rates; for a refund of a receipt it doesn't have, the team's rates. AMOUNT_TOO_LARGE: an amount of the receipt exceeds 9999999999999.99. PART_PAYMENT_TOO_LARGE: `partPayment.amount` is the receipt's whole total or more for a PREPAYMENT or INSTALMENT (a payment of all of it isn't partial), or more than it for a FINAL. PART_PAYMENT_ADDED_TAX: an item of a partial payment carries a tax charged on top of the price (SIGN), whose share of the part paid no source defines. PREPAYMENT_OF_ANOTHER_MODE: `partPayment.prepayment` names the team's prepayment, but only a test one in a fiscal shift or a fiscal one in a test shift: test documents aren't fiscal, so they make no chain with fiscal ones. CHAIN_REFUNDED: `partPayment.prepayment` names the team's prepayment that is returned (POST /cash-registers/{num}/refunds/chain), which annuls its chain: it takes no more payments."},"message":{"description":"Error text from the fiscal server for DOCUMENT_REJECTED, or what's wrong with the receipt.","examples":["Помилка валідації документа"],"type":"string"}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict7":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN","SHIFT_ALREADY_OPEN","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED","TAX_RATES_CHANGED"],"description":"The receipt opens a fiscal shift itself if the cash register's is closed, and leaves it open; the opening's failures come as the receipt's, and tell the team's admins (SHIFT_AUTO_OPEN_FAILED in GET /notifications). SHIFT_NOT_OPEN: the open shift's Z-report is registered, or its closing is still being sent, so no receipt nor new shift may follow yet; or the shift opened for the receipt was closed before it. SHIFT_ALREADY_OPEN: opening the shift was refused, as the cash register key's owner has a shift open on another cash register. CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry. TAX_RATES_CHANGED: a rate the items' letters name was edited while the receipt was being registered; nothing was registered, and a retry is calculated at the rates now in force (GET /tax-rates)."},"message":{"description":"SHIFT_ALREADY_OPEN only: the fiscal server's text, which names the cash register the shift is open on; null when the cash register's state showed the open shift before sending.","examples":["Особою Іван Іванович Іванов наразі відкрито зміну на ПРРО з фіскальним номером 4000002411"],"type":["string","null"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent4":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["DOCUMENT_REJECTED","IDEMPOTENCY_KEY_REUSED","PAYMENT_MISMATCH","DISCOUNT_TOO_LARGE","UNKNOWN_TAX_LETTER","AMOUNT_TOO_LARGE","PART_PAYMENT_TOO_LARGE","PART_PAYMENT_ADDED_TAX","ORIGINAL_NOT_FOUND","ORIGINAL_UNKNOWN_OFFLINE","EXCEEDS_ORIGINAL","PART_PAYMENT_ORIGINAL"],"description":"DOCUMENT_REJECTED: the fiscal server rejected the document. IDEMPOTENCY_KEY_REUSED: the key was used for a different request. PAYMENT_MISMATCH: the payments don't add up to the amount to pay (the total, or `partPayment.amount`), or the cash part isn't that amount rounded to 0.50 UAH (`message` names the expected amounts). DISCOUNT_TOO_LARGE: a discount is more than the amount it's taken from. UNKNOWN_TAX_LETTER: an item's letter names no rate the receipt may use: for a sale, the team's rates; for a refund of a sale the backend registered, that sale's rates; for a refund of a receipt it doesn't have, the team's rates. AMOUNT_TOO_LARGE: an amount of the receipt exceeds 9999999999999.99. PART_PAYMENT_TOO_LARGE: `partPayment.amount` is the receipt's whole total or more for a PREPAYMENT or INSTALMENT (a payment of all of it isn't partial), or more than it for a FINAL. PART_PAYMENT_ADDED_TAX: an item of a partial payment carries a tax charged on top of the price (SIGN), whose share of the part paid no source defines. ORIGINAL_NOT_FOUND: the team's cash registers the caller sees have no such sale, nor has this one on the fiscal server, or a storno cancelled it or is cancelling it, or an offline session revoked it (`message` says which). ORIGINAL_UNKNOWN_OFFLINE: the cash register is offline and the backend lacks the receipt; the fiscal server can't be asked until back online. EXCEEDS_ORIGINAL: with earlier refunds, more is returned than the sale sold (`message` names the goods or amounts). PART_PAYMENT_ORIGINAL: the receipt is a partial payment, whose chain is returned whole by POST /cash-registers/{num}/refunds/chain."},"message":{"description":"Error text from the fiscal server for DOCUMENT_REJECTED, or what's wrong with the receipt.","examples":["Помилка валідації документа"],"type":"string"}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict8":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN","SHIFT_ALREADY_OPEN","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED","CHAIN_INCOMPLETE"],"description":"The receipt opens a fiscal shift itself if the cash register's is closed, and leaves it open; the opening's failures come as the receipt's, and tell the team's admins (SHIFT_AUTO_OPEN_FAILED in GET /notifications). SHIFT_NOT_OPEN: the open shift's Z-report is registered, or its closing is still being sent, so no receipt nor new shift may follow yet; or the shift opened for the receipt was closed before it. SHIFT_ALREADY_OPEN: opening the shift was refused, as the cash register key's owner has a shift open on another cash register. CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry. CHAIN_INCOMPLETE: `returned` links are returned under the key, and more are left: a request registers one new return at most, or a link's return failed after others went through, or a receipt of the chain was stored while the prepayment's return was being registered (`message` says why). Retry with the same key: it answers with the returns already registered and goes on."},"returned":{"description":"CHAIN_INCOMPLETE: the returns the key registered.","type":"integer","minimum":0,"maximum":9007199254740991},"message":{"anyOf":[{"description":"Error text from the fiscal server for DOCUMENT_REJECTED, or what's wrong with the receipt.","examples":["Помилка валідації документа"],"type":"string"},{"type":"null"}]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent5":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["DOCUMENT_REJECTED","IDEMPOTENCY_KEY_REUSED","PAYMENT_MISMATCH","DISCOUNT_TOO_LARGE","UNKNOWN_TAX_LETTER","AMOUNT_TOO_LARGE","PART_PAYMENT_TOO_LARGE","PART_PAYMENT_ADDED_TAX","ORIGINAL_NOT_FOUND","ORIGINAL_PAID_IN_FULL","ALREADY_REFUNDED"],"description":"DOCUMENT_REJECTED: the fiscal server rejected the first link's return (a later one's is CONFLICT CHAIN_INCOMPLETE). IDEMPOTENCY_KEY_REUSED: the key was used for a different request. PAYMENT_MISMATCH: the payments don't add up to the amount to pay (the total, or `partPayment.amount`), or the cash part isn't that amount rounded to 0.50 UAH (`message` names the expected amounts). DISCOUNT_TOO_LARGE: a discount is more than the amount it's taken from. UNKNOWN_TAX_LETTER: an item's letter names no rate the receipt may use: for a sale, the team's rates; for a refund of a sale the backend registered, that sale's rates; for a refund of a receipt it doesn't have, the team's rates. AMOUNT_TOO_LARGE: an amount of the receipt exceeds 9999999999999.99. PART_PAYMENT_TOO_LARGE: `partPayment.amount` is the receipt's whole total or more for a PREPAYMENT or INSTALMENT (a payment of all of it isn't partial), or more than it for a FINAL. PART_PAYMENT_ADDED_TAX: an item of a partial payment carries a tax charged on top of the price (SIGN), whose share of the part paid no source defines. ORIGINAL_NOT_FOUND: the team has no such receipt on the cash registers the caller sees, or a storno cancelled it, or an offline session revoked it, or it's a test receipt in a fiscal shift or the other way round (`message` says which). ORIGINAL_PAID_IN_FULL: the receipt isn't a partial payment (POST /cash-registers/{num}/refunds returns it). ALREADY_REFUNDED: every link of the chain is returned already."},"message":{"description":"Error text from the fiscal server for DOCUMENT_REJECTED, or what's wrong with the receipt.","examples":["Помилка валідації документа"],"type":"string"}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound5":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["RECEIPT_NOT_FOUND","CASH_REGISTER_NOT_FOUND"],"description":"RECEIPT_NOT_FOUND: no such registered receipt. CASH_REGISTER_NOT_FOUND: the fiscal server doesn't know the receipt's cash register."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict9":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","NOT_LAST_RECEIPT","ALREADY_STORNED","RECEIPT_IS_STORNO","RECEIPT_REFUNDED","KEP_NOT_UPLOADED"],"description":"Only the last receipt of the cash register can be cancelled, once: a sale, a refund, or a service deposit or withdrawal. RECEIPT_IS_STORNO: the receipt is a storno itself, which can't be cancelled. RECEIPT_REFUNDED: a refund, on any of the team's cash registers, returns the sale (storno that refund first). SHIFT_NOT_OPEN: the receipt's shift isn't the open one, or its Z-report is registered. NOT_LAST_RECEIPT: a document came after it. CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict10":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_NOT_OPEN","SHIFT_ALREADY_OPEN","CASH_REGISTER_IN_USE","CASH_REGISTER_INACTIVE","CASH_REGISTER_BUSY","REQUEST_IN_PROGRESS","KEP_NOT_UPLOADED"],"description":"The receipt opens a fiscal shift itself if the cash register's is closed, and leaves it open; the opening's failures come as the receipt's, and tell the team's admins (SHIFT_AUTO_OPEN_FAILED in GET /notifications). SHIFT_NOT_OPEN: the open shift's Z-report is registered, or its closing is still being sent, so no receipt nor new shift may follow yet; or the shift opened for the receipt was closed before it. SHIFT_ALREADY_OPEN: opening the shift was refused, as the cash register key's owner has a shift open on another cash register. CASH_REGISTER_INACTIVE: the team's last DPS sync didn't find the cash register among those its organization KEP may use; an admin syncs again in the app. CASH_REGISTER_IN_USE: another device holds the cash register. CASH_REGISTER_BUSY: another request is registering a document for it; retry shortly. REQUEST_IN_PROGRESS: a request with this idempotency key is still running. KEP_NOT_UPLOADED: no KEP is bound to the cash register yet; an admin binds one from DepositSign in the app (PUT /cash-registers/{num}/kep), then retry."},"message":{"description":"SHIFT_ALREADY_OPEN only: the fiscal server's text, which names the cash register the shift is open on; null when the cash register's state showed the open shift before sending.","examples":["Особою Іван Іванович Іванов наразі відкрито зміну на ПРРО з фіскальним номером 4000002411"],"type":["string","null"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent6":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["DOCUMENT_REJECTED","IDEMPOTENCY_KEY_REUSED","EXCEEDS_TILL"],"description":"DOCUMENT_REJECTED: the fiscal server rejected the document. IDEMPOTENCY_KEY_REUSED: the key was used for a different request. EXCEEDS_TILL: the withdrawal is more than the till holds by the shift's totals (`message` gives both amounts)."},"message":{"description":"Error text from the fiscal server for DOCUMENT_REJECTED, or what's wrong with the receipt.","examples":["Помилка валідації документа"],"type":"string"}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound6":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["RECEIPT_NOT_FOUND"]}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden6":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["READ_ONLY"],"description":"READ_ONLY: the signed-in user is an accountant: sees every cash register and its data, changes nothing."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict11":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["NOT_ON_FISCAL_SERVER","REQUEST_IN_PROGRESS"],"description":"NOT_ON_FISCAL_SERVER: the fiscal server has no e-cabinet link for the receipt yet (it's unreachable, or an offline receipt isn't delivered yet); retry later. REQUEST_IN_PROGRESS: a request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"TooManyRequests":{"title":"TOO_MANY_REQUESTS","type":"object","properties":{"defined":{"const":true},"code":{"const":"TOO_MANY_REQUESTS"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["RECEIPT_DELIVERY_LIMIT","TEAM_DELIVERY_LIMIT"],"description":"RECEIPT_DELIVERY_LIMIT: too many emails of this receipt, by any member or token; it may be emailed up to 3 times at once, then once more every 3600s. TEAM_DELIVERY_LIMIT: too many receipt emails of the team; it may send up to 200 at once, then one more every 18s. Nothing is emailed; retry after `retryAfterSeconds`."},"retryAfterSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Seconds until the request would be let through, rounded up; others spending the same bucket meanwhile may push it further."}},"required":["reason","retryAfterSeconds"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Forbidden7":{"title":"FORBIDDEN","type":"object","properties":{"defined":{"const":true},"code":{"const":"FORBIDDEN"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["ADMIN_ONLY"],"description":"ADMIN_ONLY: team admins only; the signed-in user is a cashier or an accountant."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict12":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CATEGORY_NAME_TAKEN","REQUEST_IN_PROGRESS"],"description":"CATEGORY_NAME_TAKEN: another category of the team has the name, ignoring letter case. REQUEST_IN_PROGRESS: a request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound7":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["CATEGORY_NOT_FOUND"],"description":"No such category in the team."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound8":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["PRODUCT_NOT_FOUND","CATEGORY_NOT_FOUND","TAX_RATE_NOT_FOUND"],"description":"PRODUCT_NOT_FOUND: no such product in the team. CATEGORY_NOT_FOUND: no such category in the team for `categoryId`. TAX_RATE_NOT_FOUND: a letter of `taxLetters` names no rate of the team."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict13":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["PRODUCT_CODE_TAKEN","BARCODE_TAKEN","REQUEST_IN_PROGRESS"],"description":"PRODUCT_CODE_TAKEN: another team product has the code, or, with no code given, the next number would exceed 64 characters (the team has a code of 64 nines), so give one. BARCODE_TAKEN: another team product has the barcode. REQUEST_IN_PROGRESS: a request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"UnprocessableContent7":{"title":"UNPROCESSABLE_CONTENT","type":"object","properties":{"defined":{"const":true},"code":{"const":"UNPROCESSABLE_CONTENT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["IDEMPOTENCY_KEY_REUSED","TAX_TYPE_REPEATED"],"description":"IDEMPOTENCY_KEY_REUSED: the key was used for a different request. TAX_TYPE_REPEATED: two of the letters are rates of one type (two VATs)."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound9":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["PRODUCT_NOT_FOUND"],"description":"No such product in the team."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict14":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["REQUEST_IN_PROGRESS"],"description":"A request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict15":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["TAX_LETTER_TAKEN","REQUEST_IN_PROGRESS"],"description":"TAX_LETTER_TAKEN: a rate of the team has the letter. REQUEST_IN_PROGRESS: a request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"NotFound10":{"title":"NOT_FOUND","type":"object","properties":{"defined":{"const":true},"code":{"const":"NOT_FOUND"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["TAX_RATE_NOT_FOUND"],"description":"No such tax rate in the team."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]},"Conflict16":{"title":"CONFLICT","type":"object","properties":{"defined":{"const":true},"code":{"const":"CONFLICT"},"message":{"type":"string"},"data":{"type":"object","properties":{"reason":{"type":"string","enum":["SHIFT_OPEN","REQUEST_IN_PROGRESS"],"description":"SHIFT_OPEN: a team shift isn't closed and the rate is in use (a product refers to it, or a receipt of such a shift carries its letter); close the shifts, or add a rate with another letter. REQUEST_IN_PROGRESS: a request with this idempotency key is still running."}},"required":["reason"],"additionalProperties":false}},"required":["defined","code","message","data"]}}},"security":[{"apiToken":[]},{"session":[]}],"openapi":"3.2.0","paths":{"/health":{"get":{"operationId":"health","summary":"Service health","description":"200 `OK`: everything works. 200 `PARTIAL_FAILURE`: requests are served, but a non-essential dependency is down. 503 `FAILURE`: requests can't be served.","tags":["Service"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["OK","PARTIAL_FAILURE"]}},"required":["status"],"additionalProperties":false}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}},"security":[]}},"/business-units":{"get":{"operationId":"businessUnits.list","summary":"List business units","description":"The team's business units (created and refreshed by its DPS sync), each with its added cash registers. A cashier gets only units and cash registers an admin assigned them. Read from the service's records, not the fiscal server.","tags":["Business units"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"businessUnits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f6c3b1a-7d4e-4a9b-8c2d-5e6f7a8b9c0d"]},"entity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","description":"Its name in the DPS's register (TaxObject Name), as documents print it; the DPS sync keeps it current.","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","description":"Its address in the DPS's register (TaxObject Address), as documents print it; the DPS sync keeps it current.","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"cashRegisters":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"description":"Fiscal numbers of its cash registers the team added (GET /cash-registers) and the caller may see.","examples":[[4000002411]]}},"required":["id","entity","name","address","cashRegisters"],"additionalProperties":false}}},"required":["businessUnits"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers":{"get":{"operationId":"cashRegisters.list","summary":"List cash registers","description":"The team's cash registers added from its DPS sync, with business units, keys, whether a shift isn't closed, and since when each is missing from the DPS; for a cashier, only those an admin chose for them. From the service's records; the fiscal server isn't asked.","tags":["Cash registers"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"cashRegisters":{"type":"array","items":{"type":"object","properties":{"fiscalNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"localNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Local number of the cash register, given by the business in its registration (CASHDESKNUM).","examples":[10]},"name":{"type":"string","examples":["Каса 1"]},"closed":{"type":"boolean","description":"Whether the registration was cancelled while a shift is still open; only closing that shift is allowed.","examples":[false]},"chiefCashier":{"type":"boolean","description":"Whether the cash register key's owner is a chief cashier of the business unit, who may close shifts opened by others.","examples":[false]},"businessUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f6c3b1a-7d4e-4a9b-8c2d-5e6f7a8b9c0d"]},"entity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","description":"Its name in the DPS's register (TaxObject Name), as documents print it; the DPS sync keeps it current.","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","description":"Its address in the DPS's register (TaxObject Address), as documents print it; the DPS sync keeps it current.","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","entity","name","address","team"],"additionalProperties":false,"description":"The business unit (торгова точка) the cash register is registered in (GET /business-units), with whom its documents are issued for."},"inactiveSince":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the team's DPS sync (run by an admin in the app) first missed the cash register among those its organization KEP may use (Objects); null while found. Documents are refused with CASH_REGISTER_INACTIVE until a sync finds it again.","examples":[null]},"kep":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["DEPOSITSIGN","KEY_FILE"],"description":"Where the key is: DEPOSITSIGN, its cabinet; KEY_FILE, a key file the backend keeps (GET /cash-registers/{num}/kep)."},"keyName":{"description":"DEPOSITSIGN: the key's KeyName in the cabinet. KEY_FILE: null, as a key file's name isn't kept.","examples":["0bddd14b-7d12-4c79-afbf-b8f826807b26",null],"type":["string","null"]},"owner":{"type":"string","description":"The key's owner, named as the cashier on its documents.","examples":["Іван Іванович Іванов"]},"validUntil":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["source","keyName","owner","validUntil"],"additionalProperties":false},{"type":"null"}],"description":"The bound key (details in GET /cash-registers/{num}/kep); null while none is, and documents are refused with KEP_NOT_UPLOADED."},"shiftOpen":{"type":"boolean","description":"Whether a shift isn't closed (opening, open or closing); meanwhile binding or unbinding the key is refused with SHIFT_OPEN.","examples":[false]}},"required":["fiscalNumber","localNumber","name","closed","chiefCashier","businessUnit","inactiveSince","kep","shiftOpen"],"additionalProperties":false}}},"required":["cashRegisters"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}":{"get":{"operationId":"cashRegisters.find","summary":"Get a cash register","description":"The cash register with its mode, open shift, next local number, since when it's missing from the DPS, and any offline delivery refusal, read signed with its own key. While the fiscal server doesn't answer, as last seen; offline, from the service's records without asking the server.","tags":["Cash registers"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"fiscalNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"localNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Local number of the cash register, given by the business in its registration (CASHDESKNUM).","examples":[10]},"name":{"type":"string","examples":["Каса 1"]},"closed":{"type":"boolean","description":"Whether the registration was cancelled while a shift is still open; only closing that shift is allowed.","examples":[false]},"chiefCashier":{"type":"boolean","description":"Whether the cash register key's owner is a chief cashier of the business unit, who may close shifts opened by others.","examples":[false]},"businessUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f6c3b1a-7d4e-4a9b-8c2d-5e6f7a8b9c0d"]},"entity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","description":"Its name in the DPS's register (TaxObject Name), as documents print it; the DPS sync keeps it current.","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","description":"Its address in the DPS's register (TaxObject Address), as documents print it; the DPS sync keeps it current.","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","entity","name","address","team"],"additionalProperties":false,"description":"The business unit (торгова точка) the cash register is registered in (GET /business-units), with whom its documents are issued for."},"inactiveSince":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the team's DPS sync (run by an admin in the app) first missed the cash register among those its organization KEP may use (Objects); null while found. Documents are refused with CASH_REGISTER_INACTIVE until a sync finds it again.","examples":[null]},"mode":{"type":"string","enum":["ONLINE","OFFLINE"],"examples":["ONLINE"]},"shift":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false},{"type":"null"}],"description":"The open shift, if any."},"nextLocalNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number the next document will get.","examples":[9538]},"nextShiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The `number` the next shift opened on it will get.","examples":[43]},"deliveryRefusal":{"anyOf":[{"type":"object","properties":{"refused":{"type":"string","enum":["PACKAGE","DOCUMENT"],"description":"PACKAGE: a package of offline documents (SendOflPackage). DOCUMENT: the online document left unanswered when the cash register went offline, resent ahead of the offline session. Either way the cash register stays offline, still taking documents, until accepted.","examples":["PACKAGE"]},"since":{"type":"string","format":"date-time","x-native-type":"date","description":"When the fiscal server first refused it; kept while every retry is refused."},"httpStatus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[400]},"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The server's error code («Коди помилок»); null when it gave none.","examples":[9]},"message":{"type":"string","description":"The server's text, as it gave it.","examples":["Офлайн сесію відхилено"]}},"required":["refused","since","httpStatus","code","message"],"additionalProperties":false},{"type":"null"}],"description":"The fiscal server's refusal blocking delivery of offline documents, retried automatically every 15 minutes; null when none. An admin resends it from the app, signed with the cash register's key."}},"required":["fiscalNumber","localNumber","name","closed","chiefCashier","businessUnit","inactiveSince","mode","shift","nextLocalNumber","nextShiftNumber","deliveryRefusal"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/device":{"put":{"operationId":"cashRegisters.registerDevice","summary":"Use the cash register from this service","description":"Registers this service as the only device using a team cash register (DeviceRegister), signed with its key: documents from two devices would break its local numbering. Adding a cash register already registers it; this takes it back, or over with `force`, from another device. An admin, a cashier on a cash register chosen for them, or an API token.","tags":["Cash registers"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"default":false,"description":"Take the cash register over from another device.","examples":[false],"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"fiscalNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"localNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Local number of the cash register, given by the business in its registration (CASHDESKNUM).","examples":[10]},"name":{"type":"string","examples":["Каса 1"]},"closed":{"type":"boolean","description":"Whether the registration was cancelled while a shift is still open; only closing that shift is allowed.","examples":[false]},"chiefCashier":{"type":"boolean","description":"Whether the cash register key's owner is a chief cashier of the business unit, who may close shifts opened by others.","examples":[false]},"businessUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f6c3b1a-7d4e-4a9b-8c2d-5e6f7a8b9c0d"]},"entity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","description":"Its name in the DPS's register (TaxObject Name), as documents print it; the DPS sync keeps it current.","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","description":"Its address in the DPS's register (TaxObject Address), as documents print it; the DPS sync keeps it current.","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","entity","name","address","team"],"additionalProperties":false,"description":"The business unit (торгова точка) the cash register is registered in (GET /business-units), with whom its documents are issued for."},"inactiveSince":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the team's DPS sync (run by an admin in the app) first missed the cash register among those its organization KEP may use (Objects); null while found. Documents are refused with CASH_REGISTER_INACTIVE until a sync finds it again.","examples":[null]},"mode":{"type":"string","enum":["ONLINE","OFFLINE"],"examples":["ONLINE"]},"shift":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false},{"type":"null"}],"description":"The open shift, if any."},"nextLocalNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number the next document will get.","examples":[9538]},"nextShiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The `number` the next shift opened on it will get.","examples":[43]},"deliveryRefusal":{"anyOf":[{"type":"object","properties":{"refused":{"type":"string","enum":["PACKAGE","DOCUMENT"],"description":"PACKAGE: a package of offline documents (SendOflPackage). DOCUMENT: the online document left unanswered when the cash register went offline, resent ahead of the offline session. Either way the cash register stays offline, still taking documents, until accepted.","examples":["PACKAGE"]},"since":{"type":"string","format":"date-time","x-native-type":"date","description":"When the fiscal server first refused it; kept while every retry is refused."},"httpStatus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[400]},"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The server's error code («Коди помилок»); null when it gave none.","examples":[9]},"message":{"type":"string","description":"The server's text, as it gave it.","examples":["Офлайн сесію відхилено"]}},"required":["refused","since","httpStatus","code","message"],"additionalProperties":false},{"type":"null"}],"description":"The fiscal server's refusal blocking delivery of offline documents, retried automatically every 15 minutes; null when none. An admin resends it from the app, signed with the cash register's key."}},"required":["fiscalNumber","localNumber","name","closed","chiefCashier","businessUnit","inactiveSince","mode","shift","nextLocalNumber","nextShiftNumber","deliveryRefusal"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/shifts":{"post":{"operationId":"shifts.open","summary":"Open a shift","description":"Registers a shift opening document; the previous shift must be closed. The offline session id and secret from the fiscal server stay on the backend. Offline, the opening is numbered from the offline session and the shift opens at once. A shift whose closing was sent before going offline and is still unanswered counts as closed but blocks a new opening until the delivery settles it (SHIFT_ALREADY_OPEN).","tags":["Shifts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"testing":{"default":false,"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]}}}}}},"responses":{"201":{"description":"The opened shift.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}},"get":{"operationId":"shifts.list","summary":"List shifts","description":"Shifts opened in the period, newest first.","tags":["Shifts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"query","name":"from","schema":{"examples":["2026-10-01T00:00:00+03:00"],"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"allowEmptyValue":true,"allowReserved":true,"required":true,"example":"2026-10-01T00:00:00+03:00"},{"in":"query","name":"to","schema":{"examples":["2026-10-09T23:59:59+03:00"],"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"allowEmptyValue":true,"allowReserved":true,"required":true,"example":"2026-10-09T23:59:59+03:00"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"shifts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false}}},"required":["shifts"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/shifts/{id}":{"get":{"operationId":"shifts.find","summary":"Get a shift","description":"The shift with every document registered in it.","tags":["Shifts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"kind":{"type":"string","enum":["SHIFT_OPENING","RECEIPT","Z_REPORT","SHIFT_CLOSING","OFFLINE_BEGIN","OFFLINE_END"],"examples":["RECEIPT"]},"receiptType":{"anyOf":[{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},{"type":"null"}]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"offline":{"type":"boolean","examples":[false]},"revoked":{"type":"boolean","description":"Whether the document was revoked as a duplicate of an offline one (REVOKELASTONLINEDOC).","examples":[false]},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled the document.","examples":[false]}},"required":["id","kind","receiptType","fiscalNumber","localNumber","createdAt","offline","revoked","storned"],"additionalProperties":false}}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId","documents"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/shifts/current/totals":{"get":{"operationId":"shifts.currentTotals","summary":"Current shift totals","description":"Running totals of the open shift: the X-report, and the draft of the Z-report that closing the shift registers.","tags":["Shifts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"shift":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false},"totals":{"type":"object","properties":{"sales":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Sales receipts."},"refunds":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Return receipts."},"serviceDeposit":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service deposits and advances received (SERVICEINPUT).","examples":["500.00"]},"serviceWithdrawal":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service withdrawals and encashment (SERVICEOUTPUT).","examples":["12000.00"]}},"required":["sales","refunds","serviceDeposit","serviceWithdrawal"],"additionalProperties":false}},"required":["shift","totals"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict4"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/shifts/{id}/close":{"post":{"operationId":"shifts.close","summary":"Close a shift","description":"Registers the Z-report, then the shift closing document. Only the cashier who opened the shift or a chief cashier may close it. Offline, both are numbered from the offline session and the shift closes at once; a shift whose opening was sent before going offline and is still unanswered can't close until the delivery settles it (SHIFT_NOT_FOUND). Online, the Z-report is first checked against the fiscal server's shift totals: if they differ the shift stays open (Z_REPORT_TOTALS_MISMATCH); if the server gives none it closes anyway. The backend closes 24-hour-old shifts itself, so a later close may get SHIFT_ALREADY_CLOSED.","tags":["Shifts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"shift":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The shift's ordinal on its cash register: 1, 2, 3, … in the order the service opened them. Assigned when the opening is stored; an opening the fiscal server refuses leaves no shift, so the next one takes its number. Shifts opened by other devices or programs aren't counted.","examples":[42]},"status":{"type":"string","enum":["OPEN","CLOSED"],"examples":["OPEN"]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"openedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"A shift lasts 24 hours at most (ЗІР 109.20): 24 hours after this the backend closes it with its Z-report, online or offline as the cash register is; if the fiscal server refuses, it stays open for the cashier to close."},"openedBy":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"openFiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the shift opening document, which is also the fiscal server's number of the shift.","examples":["3408730301"]},"closedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}]},"closedBy":{"anyOf":[{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},{"type":"null"}]},"zReportId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]}},"required":["id","cashRegister","number","status","testing","openedAt","openedBy","openFiscalNumber","closedAt","closedBy","zReportId"],"additionalProperties":false},"zReport":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"offline":{"type":"boolean","description":"Whether the Z-report was created offline (OFFLINE).","examples":[false]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"totals":{"type":"object","properties":{"sales":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Sales receipts."},"refunds":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Return receipts."},"serviceDeposit":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service deposits and advances received (SERVICEINPUT).","examples":["500.00"]},"serviceWithdrawal":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service withdrawals and encashment (SERVICEOUTPUT).","examples":["12000.00"]}},"required":["sales","refunds","serviceDeposit","serviceWithdrawal"],"additionalProperties":false}},"required":["id","shiftId","cashRegister","fiscalNumber","localNumber","createdAt","offline","testing","totals"],"additionalProperties":false}},"required":["shift","zReport"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden4"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/z-reports/{id}":{"get":{"operationId":"zReports.find","summary":"Get a Z-report","tags":["Z-reports"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f"]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"offline":{"type":"boolean","description":"Whether the Z-report was created offline (OFFLINE).","examples":[false]},"testing":{"type":"boolean","description":"Whether the documents are test ones (TESTING): they get fiscal numbers but aren't fiscal. A shift holds either only test or only fiscal documents.","examples":[false]},"totals":{"type":"object","properties":{"sales":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Sales receipts."},"refunds":{"type":"object","properties":{"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["15230.40"]},"receipts":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of receipts.","examples":[42]},"rounding":{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Total cash rounding (RNDSUM).","examples":["-0.12"]},"payments":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Payment form code (PAYFORMCD).","examples":[0]},"name":{"type":"string","description":"Payment form name (PAYFORMNM).","examples":["ГОТІВКА"]},"sum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]}},"required":["code","name","sum"],"additionalProperties":false}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}}},"required":["sum","receipts","rounding","payments","taxes"],"additionalProperties":false,"description":"Return receipts."},"serviceDeposit":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service deposits and advances received (SERVICEINPUT).","examples":["500.00"]},"serviceWithdrawal":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Service withdrawals and encashment (SERVICEOUTPUT).","examples":["12000.00"]}},"required":["sales","refunds","serviceDeposit","serviceWithdrawal"],"additionalProperties":false},"visualization":{"description":"The Z-report as text, rendered by the fiscal server; null until the server provides it (offline Z-report not yet delivered, or server unreachable) and while the team has no KEP to ask with.","type":["string","null"]}},"required":["id","shiftId","cashRegister","fiscalNumber","localNumber","createdAt","offline","testing","totals","visualization"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound4"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/receipts":{"post":{"operationId":"receipts.sell","summary":"Register a sale","description":"Registers a sales receipt in the open shift. The backend calculates line totals, taxes (from the team's rates by the items' letters, copied into the receipt) and cash rounding. With `partPayment` it's a partial payment receipt (prepayment, instalment or final settlement): the goods at full price, a part of it paid, taxes on that part.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"]},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"]},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}}},"required":["name","unit","quantity","price","taxLetters"],"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А"},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"]}]}},"discount":{"description":"Discount on the whole receipt.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"]},"payments":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"}},"required":["method","amount"]},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}}}},"required":["method","amount"]},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"]}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]},"description":"How the buyer paid; the amounts add up to the amount to pay (the total, or `partPayment.amount`), the cash part rounded to 0.50 UAH."},"partPayment":{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"The part paid now, before cash rounding (NORNDSUM); the lines' shares of it (PARTPAYSUM) add up to it. `payments` cover it as they cover a whole receipt's total: the cash part rounded to 0.50 UAH, the rest exact. Less than the receipt's total for PREPAYMENT and INSTALMENT, at most that for FINAL. The backend doesn't track what earlier payments of the same goods paid.","examples":["15.00"]},"prepayment":{"description":"The PREPAYMENT receipt the payments started with: required for INSTALMENT and FINAL, not allowed for PREPAYMENT.","type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"]}},"required":["type","amount"],"description":"A partial payment (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM): `items` are all the goods paid for, at their full price, of which `amount` is paid now. Taxes are charged on the part paid.","examples":[{"type":"PREPAYMENT","amount":"15.00"},{"type":"INSTALMENT","amount":"15.00","prepayment":{"fiscalNumber":"3408730318"}}]},"comment":{"description":"Comment printed on the receipt (COMMENT).","examples":["Дякуємо за покупку!"],"type":"string"}},"required":["items","payments"],"examples":[{"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А"},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"]}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00"}]},{"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"2","price":"57.50","taxLetters":"А"}],"payments":[{"method":"CARD","amount":"15.00"}],"partPayment":{"type":"PREPAYMENT","amount":"15.00"}}]}}}},"responses":{"201":{"description":"The registered receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict6"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/refunds":{"post":{"operationId":"receipts.refund","summary":"Register a return","description":"Registers a return receipt (видатковий чек) on this cash register for goods from an earlier receipt of any of the team's cash registers the caller sees, as the DPS lets a seller return a sale through another of its РРО; another cash register's sale is named by its cash register and date too (ORDERRETCASHREGNUM, ORDERRETDATE). The money goes out of this cash register, and the return counts in its shift. A sale the backend registered is linked: its non-storned refunds, from any cash register, together may return no more of any goods (matched by code, else barcode, else name, and price) and no more money before cash rounding than it sold. A receipt the backend doesn't have is taken for this cash register's and checked with the fiscal server, so it's refused offline. Taxes come by the items' letters from the linked sale's rates, else from the team's rates. A partial payment receipt (`partPayment`) the backend has is refused: its whole chain is returned by POST /cash-registers/{num}/refunds/chain.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"original":{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the receipt being returned (ORDERRETNUM), one of any of the team's cash registers the caller sees, or one of this cash register the backend doesn't have.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"]},"items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"]},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"]},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}}},"required":["name","unit","quantity","price","taxLetters"],"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А"},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"]}]}},"payments":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"}},"required":["method","amount"]},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}}}},"required":["method","amount"]},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"]}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]},"description":"How the buyer paid; the amounts add up to the amount to pay (the total, or `partPayment.amount`), the cash part rounded to 0.50 UAH."}},"required":["original","items","payments"],"examples":[{"original":{"fiscalNumber":"3408730318"},"items":[{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"1","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"]}],"payments":[{"method":"CASH","amount":"16.50"}]}]}}}},"responses":{"201":{"description":"The registered receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent4"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/refunds/chain":{"post":{"operationId":"receipts.refundChain","summary":"Return goods paid for in parts","description":"Returns goods paid for by partial payment receipts (`partPayment`): DPS has the whole chain annulled («анулюванню підлягає весь ланцюг створених чеків у межах такого продажу», tax.gov.ua, 24.10.2023). `original` names any receipt of the chain, on any of the team's cash registers the caller sees; the chain is its PREPAYMENT and every INSTALMENT and FINAL naming that prepayment, among the team's receipts the backend registered on the cash registers the caller sees, all test or all fiscal as `original` is. This cash register registers a return receipt for each link not returned yet and not storned, the latest first, each naming its own (ORDERRETNUM, and for another cash register's ORDERRETCASHREGNUM and ORDERRETDATE) and copying its goods, rates, partial payment type and prepayment, giving back all it took before cash rounding. One idempotency key covers the chain, and a request registers at most one new return: with more to go it answers CONFLICT CHAIN_INCOMPLETE, and a retry with the same key goes on, answering with every return the key registered.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"original":{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of any partial payment receipt of the chain.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"]},"method":{"description":"How all the money is given back. Without it each link gives back by the payment forms and amounts it was paid with, as DPS recommends returning by the form paid.","examples":["CASH"],"type":"string","enum":["CASH","CARD","CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]}},"required":["original"],"examples":[{"original":{"fiscalNumber":"3408730318"}}]}}}},"responses":{"201":{"description":"The registered return receipts, latest link first.","content":{"application/json":{"schema":{"type":"object","properties":{"receipts":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}},"required":["receipts"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict8"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/receipts/{id}/storno":{"post":{"operationId":"receipts.storno","summary":"Cancel the last receipt","description":"Registers a storno receipt cancelling the cash register's last receipt, e.g. when the buyer refuses or the amount was wrong: a sale, a refund, or a service deposit or withdrawal in the open shift, with no document after it. The fiscal server registers the storno with a zero sum. The cancelled receipt then shows as `storned` and counts in no shift totals; a storned refund no longer counts against its sale.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"responses":{"201":{"description":"The registered storno receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict9"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/cash-operations":{"post":{"operationId":"receipts.cashOperation","summary":"Register a cash deposit or withdrawal","description":"Registers a service receipt for cash put into or taken out of the till. A withdrawal may take no more than the till holds by the open shift's totals: cash sales less cash refunds, plus service deposits, less service withdrawals. Cash in the till before the shift counts once a service deposit records it.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["DEPOSIT","WITHDRAWAL"],"description":"DEPOSIT is a service deposit or advance received, WITHDRAWAL a service withdrawal or encashment.","examples":["DEPOSIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, above zero.","examples":["500.00"]}},"required":["type","amount"]}}}},"responses":{"201":{"description":"The registered receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden5"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict10"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent6"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"502":{"description":"502","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadGateway"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable3"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/receipts/{id}":{"get":{"operationId":"receipts.find","summary":"Get a receipt","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]},"cabinetUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"The fiscal server's link to the receipt's page in the taxpayer's e-cabinet (CabinetUrl of CheckExt), used by the email of POST /receipts/{id}/deliveries. Null until the server provides it: while it's unreachable, or until an offline receipt is delivered. The QR code uses `qrUrl`, which needs no server."},"visualization":{"description":"The receipt as text, rendered by the fiscal server (CheckExt Visualization). Null until the fiscal server provides it: while it's unreachable, or until an offline receipt is delivered.","type":["string","null"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl","cabinetUrl","visualization"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"82563.25.6127","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":true,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?mac=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08&date=20261009&time=1423&id=82563.25.6127&sm=397.00&fn=4000002411","cabinetUrl":null,"visualization":null}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound6"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/receipts/{id}/deliveries":{"post":{"operationId":"receipts.deliveries.create","summary":"Email a receipt","description":"Emails the receipt's e-cabinet link (`cabinetUrl` of GET /receipts/{id}) and a summary (seller, time, lines, total, fiscal numbers) to the address given. Only once the fiscal server has the receipt: while its link isn't kept yet, the server is asked (CheckExt) as GET /receipts/{id} does. Up to 3 emails of a receipt at once, then one more every 3600s (RECEIPT_DELIVERY_LIMIT), and up to 200 of the team's at once, then one more every 18s (TEAM_DELIVERY_LIMIT). Every attempt counts, one the mail service refuses too, and so does a retry with the same key unless an earlier attempt answered: the email still goes out once. The address isn't stored.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"description":"The buyer's address.","examples":["user@example.com"],"type":"string","maxLength":254}},"required":["email"]}}}},"responses":{"201":{"description":"The email was handed to the mail service.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","createdAt"],"additionalProperties":false,"description":"An email of the receipt to the address given; the address isn't kept.","examples":[{"id":"0d3f5a8e-2c4b-4e1a-9f7d-6b5c4a3e2d1f","createdAt":"2026-10-16T12:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden6"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound6"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict11"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"429":{"description":"429","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TooManyRequests"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/shifts/{id}/receipts":{"get":{"operationId":"receipts.list","summary":"List a shift's receipts","description":"The shift's receipts (sales, refunds, stornos, service receipts), newest first, except ones revoked by an offline session (GET /shifts/{id} lists them as revoked). Read from the service's own records without asking the fiscal server, so without rendering or e-cabinet link (GET /receipts/{id} gives those); `qrUrl` needs no server and is present. `laterRefunds` holds refunds of the shift's sales made in later shifts, so both lists together tell what was returned of each sale.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"receipts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}},"laterRefunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]},"description":"Refunds of the shift's sales registered in later shifts (not in `receipts`). Only refunds linked to their sale (of this cash register's sale the service registered); storned ones included and marked `storned`, ones an offline session revoked left out."}},"required":["receipts","laterRefunds"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/receipts":{"get":{"operationId":"receipts.search","summary":"Find receipts by fiscal number","description":"The team's receipts with the fiscal number (ORDERTAXNUM) from any shift and cash register, newest first; usually one. Read from the service's own records like GET /shifts/{id}/receipts: receipts still being sent or revoked by an offline session aren't found. An online number with leading zeros is read as the server's integer. `refunds` holds the found sales' refunds from every shift (linked as in GET /shifts/{id}/receipts' `laterRefunds`), storned ones included and marked. With `cashRegister`, a number missing from the team's records is asked of the fiscal server as that cash register's receipt (CheckExt, its original XML), unless the cash register is offline or has another document with the number (a shift's opening or closing, a revoked receipt), which a refund would refuse too. The server is asked once, without retries, and its copy isn't kept: every lookup asks again. A receipt it lacks, or a refusal to look it up, counts as nothing found: `source` SERVICE with empty lists.","tags":["Receipts"],"parameters":[{"in":"query","name":"fiscalNumber","schema":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"allowEmptyValue":true,"allowReserved":true,"required":true,"description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","example":"3408730318"},{"in":"query","name":"cashRegister","schema":{"description":"The team's cash register whose receipt to ask the fiscal server for (CheckExt) when the team's records lack the number; returned with `source` FISCAL_SERVER. Not asked offline, or when the cash register has any document with the number.","examples":[4000002411],"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"allowEmptyValue":true,"allowReserved":true,"description":"The team's cash register whose receipt to ask the fiscal server for (CheckExt) when the team's records lack the number; returned with `source` FISCAL_SERVER. Not asked offline, or when the cash register has any document with the number.","example":4000002411}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"source":{"type":"string","const":"SERVICE","description":"The service's own records; also the answer when nothing was found anywhere."},"receipts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}}},"required":["source","receipts","refunds"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","const":"FISCAL_SERVER","description":"The fiscal server's copy of the cash register's receipt."},"sale":{"anyOf":[{"type":"object","properties":{"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."}},"required":["cashRegister","fiscalNumber","localNumber","createdAt","offline","testing","items","payments","taxes","total","rounding","partPayment"],"additionalProperties":false,"description":"The fiscal server's copy of a sale the service doesn't have (CheckExt, «Оригінальний XML»), read from the document as its seller sent it. Not kept, so no id or shift; a refund of it is checked with the server again (POST /cash-registers/{num}/refunds).","examples":[{"cashRegister":4000002411,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"total":"397.00","rounding":"0.16","partPayment":null}]},{"type":"null"}],"description":"null when the server's document with the number isn't a sale (a refund, a storno, a service receipt, a shift's opening or closing…)."},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]},"description":"This service's refunds of that receipt, unlinked as the receipt isn't kept; storned ones included and marked, ones an offline session revoked left out."}},"required":["source","sale","refunds"],"additionalProperties":false}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"503":{"description":"503","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ServiceUnavailable2"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/sales":{"get":{"operationId":"receipts.pastSales","summary":"List a cash register's past sales","description":"The cash register's sales from shifts before the open one (all shifts when none is open), newest first by local number, paginated. Read from the service's own records like GET /shifts/{id}/receipts, without asking the fiscal server: only counted sales, none still being sent or revoked by an offline session. The open shift's sales are in GET /shifts/{id}/receipts. `refunds` holds the page's sales' refunds from every shift, the open one included (linked as in GET /shifts/{id}/receipts' `laterRefunds`), storned ones included and marked, to tell what was returned of each sale.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"query","name":"page","schema":{"default":1,"description":"The page, from 1.","examples":[1],"type":"integer","minimum":1,"maximum":9007199254740991},"allowEmptyValue":true,"allowReserved":true,"description":"The page, from 1.","example":1},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page, up to 100.","examples":[20],"type":"integer","minimum":1,"maximum":100},"allowEmptyValue":true,"allowReserved":true,"description":"Items per page, up to 100.","example":20}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"receipts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]}},"refunds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Receipt id, also the document's UID.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"type":{"type":"string","enum":["SALE","REFUND","STORNO","SERVICE_DEPOSIT","SERVICE_WITHDRAWAL"],"description":"SALE is a sales receipt (DOCSUBTYPE 0), REFUND a return receipt (1), STORNO cancels the previous receipt (5), SERVICE_DEPOSIT records a service deposit or advance (2), SERVICE_WITHDRAWAL a service withdrawal or encashment (4).","examples":["SALE"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]},"shiftId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"shiftNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Its shift's `number`.","examples":[42]},"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"localNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local number of the document (ORDERNUM): one gapless sequence per cash register across every kind of document, online or offline.","examples":[9537]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date","description":"Time of the operation (ORDERDATE, ORDERTIME)."},"cashier":{"type":"string","description":"Full name of the cashier, as printed on documents (CASHIER).","examples":["Іван Іванович Іванов"]},"businessUnit":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Id of the business unit (господарська одиниця) in the fiscal server's register (Entity).","examples":[1937281]},"name":{"type":"string","examples":["Кафе \"Сонечко\""]},"address":{"type":"string","examples":["УКРАЇНА, м. Київ, вул. Сонячна, 27"]},"team":{"type":"object","properties":{"name":{"type":"string","examples":["ТОВ Тестова організація"]},"tin":{"type":"string","description":"ЄДРПОУ or ДРФО code of the business.","examples":["44082020"]},"vatNumber":{"description":"VAT payer number (ІПН); null for non-payers.","examples":["440820207777"],"type":["string","null"]},"singleTax":{"type":"boolean","description":"Whether it's an individual entrepreneur on the single tax.","examples":[false]}},"required":["name","tin","vatNumber","singleTax"],"additionalProperties":false}},"required":["id","name","address","team"],"additionalProperties":false,"description":"The seller as filed in the header (ORGNM, POINTNM, POINTADDR, TIN, IPN): the business unit's details from the fiscal server's register at issue time, kept so a reprint shows them after they change (GET /cash-registers/{num} shows the current ones)."},"offline":{"type":"boolean","description":"Whether it was issued offline (OFFLINE) and holds an offline fiscal number.","examples":[false]},"testing":{"type":"boolean","description":"Whether it's a test receipt, which isn't fiscal (TESTING).","examples":[false]},"items":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Internal product code (CODE).","examples":["98765"],"type":"string","maxLength":64},"barcode":{"description":"Barcode (BARCODE).","examples":["4820000000017"],"type":"string","maxLength":64},"uktzed":{"description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. Not together with `dkpp`.","examples":["876543"],"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$"},"dkpp":{"description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. Not together with `uktzed`.","examples":["11.22.33-44.55"],"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$"},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"Product, service or operation name (NAME).","examples":["Куряче стегно"]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false},"quantity":{"type":"string","pattern":"^(?!0+(\\.0{1,3})?$)\\d{1,12}(\\.\\d{1,3})?$","description":"Quantity (AMOUNT).","examples":["5.701"]},"price":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price per unit (PRICE).","examples":["52.30"]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates on the line (LETTERS; GET /tax-rates), e.g. «АД».","examples":["АД"]},"discount":{"description":"Discount on this line.","type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},"exciseLabels":{"description":"Series and numbers of the excise stamps (EXCISELABELS).","examples":[["AATE508932 0000412167"]],"type":"array","items":{"type":"string","maxLength":64}},"cost":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Price × quantity, before any discount (COST, check01.xsd: «Сума операції (без урахування знижки)»).","examples":["298.16"]},"discountSum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's own discount (DISCOUNTSUM); null without one. A discount on the whole receipt isn't in it.","examples":[null]},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The line's amount after its own discount and its share of the receipt's discount, as calculated at issue.","examples":["298.16"]},"partPaySum":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The line's share of the part paid, before cash rounding (PARTPAYSUM); null without `partPayment`.","examples":[null]}},"required":["name","unit","quantity","price","taxLetters","cost","discountSum","total","partPaySum"],"additionalProperties":false,"examples":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}]}},"payments":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"CASH"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"provided":{"description":"Cash the buyer handed over (PROVIDED), to give change from.","examples":["500.00"],"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$"},"change":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"Change given (REMAINS); null when `provided` wasn't given.","examples":["3.00"]}},"required":["method","amount","change"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","const":"CARD"},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]},"card":{"description":"Terminal data of the payment (PAYSYS).","type":"object","properties":{"paymentSystem":{"description":"Payment system (NAME).","examples":["Mastercard"],"type":"string"},"acquirer":{"description":"Acquiring bank (ACQUIRENM).","examples":["Приват Банк"],"type":"string"},"terminalId":{"description":"POS terminal id (DEVICEID).","examples":["S1K700J8"],"type":"string","maxLength":128},"transactionNumber":{"description":"Transaction number on the terminal (POSTRANSNUM).","examples":["000622"],"type":"string","maxLength":128},"transactionAt":{"description":"Time of the terminal transaction (POSTRANSDATE).","examples":["2024-11-21T17:09:24+02:00"],"type":"string","format":"date-time","x-native-type":"date"},"acquirerTransactionId":{"description":"Id of the transaction in the payment system, given by the acquirer (ACQUIRETRANSID).","examples":["12121212121212121212"],"type":"string","maxLength":128},"authCode":{"description":"Authorization code (AUTHCD).","examples":["130432"],"type":"string","maxLength":64},"maskedPan":{"description":"Masked card number (EPZDETAILS).","examples":["XXXXXXXXXXXX1713"],"type":"string","maxLength":128}},"additionalProperties":false}},"required":["method","amount"],"additionalProperties":false},{"type":"object","properties":{"method":{"type":"string","enum":["CERTIFICATE","BANK_TRANSFER","PREPAYMENT","CREDIT"]},"amount":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Amount paid this way (SUM).","examples":["476.53"]}},"required":["method","amount"],"additionalProperties":false}],"description":"`method` is the payment form; the backend sets the code and name the fiscal server expects (PAYFORMCD, PAYFORMNM).","examples":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"},{"method":"CARD","amount":"397.16","card":{"paymentSystem":"Mastercard","acquirer":"Приват Банк","terminalId":"S1K700J8","transactionNumber":"000622","transactionAt":"2024-11-21T17:09:24+02:00","authCode":"130432","maskedPan":"XXXXXXXXXXXX1713"}}]}},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"turnover":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Sum of the lines the tax applies to, before discounts (TURNOVER).","examples":["397.16"]},"sourceSum":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount the tax is calculated from, after discounts (SOURCESUM). For VAT it leaves out the excise included in the same lines.","examples":["392.45"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Tax amount (SUM).","examples":["65.41"]}},"required":["type","name","letter","percent","included","turnover","sourceSum","amount"],"additionalProperties":false}},"discount":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["AMOUNT","PERCENT"],"description":"A fixed amount or a percentage (DISCOUNTTYPE).","examples":["PERCENT"]},"value":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Discount in hryvnias, or in percent for PERCENT.","examples":["10.00"]}},"required":["type","value"],"additionalProperties":false},{"type":"null"}],"description":"Discount on the whole receipt."},"total":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The receipt's sum (SUM): the amount paid, after rounding; with `partPayment`, the full cost of the goods, unrounded, of which `partPayment.amount` is paid. Only the cash part is rounded, to 0.50 UAH.","examples":["397.00"]},"rounding":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals, may be negative.","examples":["-0.25"]},{"type":"null"}],"description":"Cash rounding (RNDSUM); null when the amount wasn't rounded. The amount before rounding (NORNDSUM) is the amount paid (`partPayment.amount`, else `total`) plus `rounding`, so rounding up makes it negative.","examples":["0.16"]},"partPayment":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PREPAYMENT","INSTALMENT","FINAL"],"description":"PREPAYMENT is the first payment for goods handed over or services rendered later (PARTPAYTYPE 1, «Передплата»), INSTALMENT a further payment (3, «Чергова сплата»), FINAL the last one, settling the rest (2, «Остаточний розрахунок»).","examples":["PREPAYMENT"]},"amount":{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"The part paid, after cash rounding (CHECKTOTAL PARTPAYSUM), unlike the request's `partPayment.amount`, which is before it: that one is this plus `rounding`.","examples":["15.00"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"`amount` as a percentage of `total` (PARTPAYPERCENT); a FINAL payment rounded up in cash may pass 100.","examples":["13.04"]},"prepayment":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt the payments started with (PARTPAYORDPREPAYNUM). Checked for its format only: the prepayment may come from another cash register or program.","examples":["3408730318","82563.25.6127"]}},"required":["fiscalNumber"],"additionalProperties":false},{"type":"null"}],"description":"The PREPAYMENT receipt the payments started with; null for a PREPAYMENT."},"remainder":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"«Залишок до сплати» as the sale was issued with it (its COMMENT, «Залишок до сплати 33,66 грн.»): `total` less every payment of the chain before rounding, this one included. A PREPAYMENT's is `total` less it; an INSTALMENT's only when the team has its prepayment, counting the chain's payments not storned or returned on the team's cash registers. Null for a FINAL, a refund, an unknown chain, or nothing left.","examples":["100.00"]}},"required":["type","amount","percent","prepayment","remainder"],"additionalProperties":false},{"type":"null"}],"description":"The partial payment the receipt registers (CHECKTOTAL PARTPAYTYPE, PARTPAYSUM); null for a receipt paid in full. A refund of one returns all of it, with the same `type` and `prepayment`."},"original":{"anyOf":[{"type":"object","properties":{"fiscalNumber":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of a document (ORDERTAXNUM). The fiscal server assigns it to online documents; an offline one is `<offline session>.<number in the session>.<control number>`.","examples":["3408730318","82563.25.6127"]},"cashRegister":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register (ПРРО), assigned by the fiscal server when its registration (form 1-ПРРО) is accepted.","examples":[4000002411]}},"required":["fiscalNumber","cashRegister"],"additionalProperties":false},{"type":"null"}],"description":"Receipt that this one returns or cancels (storno)."},"storned":{"type":"boolean","description":"Whether a storno receipt cancelled this one.","examples":[false]},"qrUrl":{"type":"string","format":"uri","description":"The receipt's QR code link: a search for it in the taxpayer's e-cabinet, per form ФКЧ-1 line 29 (Положення №13, наказ Мінфіну 21.01.2016 №13). Built by the backend, so available at once, offline too: date (yyyyMMdd) and time (HHmm) in Kyiv time, the receipt's fiscal number, the total (SUM) and the cash register's fiscal number; offline receipts add `mac`, the SHA-256 (hex) of the signed document. The e-cabinet finds it once the fiscal server has it.","examples":["https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"]}},"required":["id","type","cashRegister","shiftId","shiftNumber","fiscalNumber","localNumber","createdAt","cashier","businessUnit","offline","testing","items","payments","taxes","discount","total","rounding","partPayment","original","storned","qrUrl"],"additionalProperties":false,"examples":[{"id":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11","type":"SALE","cashRegister":4000002411,"shiftId":"8a6e0804-2bd0-4672-b79d-d97027f9071a","shiftNumber":42,"fiscalNumber":"3408730318","localNumber":9537,"createdAt":"2026-10-09T14:23:38+03:00","cashier":"Іван Іванович Іванов","businessUnit":{"id":1937281,"name":"Кафе \"Сонечко\"","address":"УКРАЇНА, м. Київ, вул. Сонячна, 27","team":{"name":"ТОВ Тестова організація","tin":"44082020","vatNumber":"440820207777","singleTax":false}},"offline":false,"testing":false,"items":[{"code":"98765","barcode":"4820000000017","uktzed":"876543","name":"Куряче стегно","unit":{"code":25,"name":"кг"},"quantity":"5.701","price":"52.30","taxLetters":"А","cost":"298.16","discountSum":null,"total":"298.16","partPaySum":null},{"code":"76543456","uktzed":"543210","name":"Пиво","unit":{"code":87,"name":"бут"},"quantity":"6","price":"16.50","taxLetters":"АД","exciseLabels":["AATE508932 0000412168"],"cost":"99.00","discountSum":null,"total":"99.00","partPaySum":null}],"payments":[{"method":"CASH","amount":"397.00","provided":"400.00","change":"3.00"}],"taxes":[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"turnover":"397.16","sourceSum":"392.45","amount":"65.41"},{"type":1,"name":"Акциз","letter":"Д","percent":"5.00","included":true,"turnover":"99.00","sourceSum":"99.00","amount":"4.71"}],"discount":null,"total":"397.00","rounding":"0.16","partPayment":null,"original":null,"storned":false,"qrUrl":"https://cabinet.tax.gov.ua/cashregs/check?date=20261009&time=1423&id=3408730318&sm=397.00&fn=4000002411"}]},"description":"Refunds of the page's sales from any shift, storned ones included and marked; one an offline session revoked is left out."},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"How many past sales the cash register has, on every page.","examples":[42]}},"required":["receipts","refunds","total"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/prepayments/{fiscalNumber}":{"get":{"operationId":"receipts.prepayment","summary":"Get what a prepayment's chain has paid","description":"What the partial payment chain begun by the team's PREPAYMENT receipt with the fiscal number has paid so far before rounding: its payments not storned or returned, on any of the team's cash registers, of the open shift's mode (test or fiscal), as POST /cash-registers/{num}/receipts counts an INSTALMENT's `remainder`. For the POS to show what an instalment leaves to pay.","tags":["Receipts"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411},{"in":"path","required":true,"name":"fiscalNumber","schema":{"type":"string","pattern":"^(\\d{1,128}|\\d+\\.\\d+\\.\\d+)$","description":"Fiscal number of the PREPAYMENT receipt.","examples":["3408730318","82563.25.6127"]},"description":"Fiscal number of the PREPAYMENT receipt.","example":"3408730318"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"paid":{"anyOf":[{"type":"string","pattern":"^\\d{1,13}\\.\\d{2}$","description":"Amount in hryvnias with exactly two decimals.","examples":["476.53"]},{"type":"null"}],"description":"The chain's payments before rounding; null when the team has no such prepayment of the open shift's mode, or no shift is open.","examples":["15.00"]}},"required":["paid"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/cash-registers/{num}/offline":{"get":{"operationId":"offline.status","summary":"Offline status","description":"Whether the cash register works offline and how much of the offline limits is used. Clients should warn the cashier near a limit.","tags":["Offline"],"parameters":[{"in":"path","required":true,"name":"num","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Fiscal number of the cash register.","examples":[4000002411]},"description":"Fiscal number of the cash register.","example":4000002411}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the cash register may work offline (OfflineSupported).","examples":[true]},"mode":{"type":"string","enum":["ONLINE","OFFLINE"],"examples":["OFFLINE"]},"session":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Offline session id the fiscal server issued (OfflineSessionId), the first part of the fiscal numbers of offline documents.","examples":[82563]},"startedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","startedAt"],"additionalProperties":false},{"type":"null"}],"description":"The current offline session; null when online."},"sessionMinutes":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Current offline session duration, from its start to its last financial document, counted by the backend over its offline documents, undelivered included; null when online. May differ from the fiscal server's OfflineSessionDuration, which knows only delivered ones.","examples":[95]},"monthMinutes":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Offline time used this calendar month (Europe/Kyiv), counted by the backend over its offline documents, undelivered included; a session spanning months is split at Kyiv midnight. May differ from the fiscal server's OfflineSessionsMonthlyDuration.","examples":[1440]},"limits":{"type":"object","properties":{"sessionMinutes":{"type":"integer","minimum":0,"maximum":9007199254740991,"examples":[2160]},"monthMinutes":{"type":"integer","minimum":0,"maximum":9007199254740991,"examples":[10080]}},"required":["sessionMinutes","monthMinutes"],"additionalProperties":false,"description":"Legal offline limits, to warn the cashier about: 36 hours per session, 168 hours per calendar month. Under martial law offline work may exceed them (Law 265/95-ВР, section II p.13), so the backend refuses documents past either (OFFLINE_LIMIT_EXCEEDED) only when configured to enforce them; reported either way. Whether the fiscal server blocks a cash register past them is unknown; its refusal of a document is authoritative and comes back as DOCUMENT_REJECTED."},"pendingDocuments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Documents created offline that aren't delivered to the fiscal server yet.","examples":[37]},"deliveryRefusal":{"anyOf":[{"type":"object","properties":{"refused":{"type":"string","enum":["PACKAGE","DOCUMENT"],"description":"PACKAGE: a package of offline documents (SendOflPackage). DOCUMENT: the online document left unanswered when the cash register went offline, resent ahead of the offline session. Either way the cash register stays offline, still taking documents, until accepted.","examples":["PACKAGE"]},"since":{"type":"string","format":"date-time","x-native-type":"date","description":"When the fiscal server first refused it; kept while every retry is refused."},"httpStatus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"examples":[400]},"code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The server's error code («Коди помилок»); null when it gave none.","examples":[9]},"message":{"type":"string","description":"The server's text, as it gave it.","examples":["Офлайн сесію відхилено"]}},"required":["refused","since","httpStatus","code","message"],"additionalProperties":false},{"type":"null"}],"description":"The fiscal server's refusal blocking delivery of offline documents, retried automatically every 15 minutes; null when none. An admin resends it from the app, signed with the cash register's key."}},"required":["supported","mode","session","sessionMinutes","monthMinutes","limits","pendingDocuments","deliveryRefusal"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/product-categories":{"get":{"operationId":"products.categories.list","summary":"List product categories","description":"Every category of the team, in Ukrainian alphabetical order of their names.","tags":["Products"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},"name":{"type":"string","minLength":1,"maxLength":30,"description":"Unique within the team, ignoring letter case.","examples":["Кульки"]},"tone":{"type":"string","enum":["BLUE","ORANGE","GREEN","PURPLE","PINK","TEAL"],"description":"The category's colour, assigned at creation in turn (BLUE, ORANGE, GREEN, PURPLE, PINK, TEAL; the seventh is BLUE again) and never changed. The POS tints the category's products with it.","examples":["BLUE"]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","tone","createdAt"],"additionalProperties":false}}},"required":["categories"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}},"post":{"operationId":"products.categories.create","summary":"Create a product category","description":"Creates a team category to file products under, with the next colour in turn (`tone`). A repeat with the same idempotency key returns the same category. Only an admin or an API token.","tags":["Products"],"parameters":[{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":30,"description":"Unique within the team, ignoring letter case.","examples":["Кульки"]}},"required":["name"],"examples":[{"name":"Кульки"}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},"name":{"type":"string","minLength":1,"maxLength":30,"description":"Unique within the team, ignoring letter case.","examples":["Кульки"]},"tone":{"type":"string","enum":["BLUE","ORANGE","GREEN","PURPLE","PINK","TEAL"],"description":"The category's colour, assigned at creation in turn (BLUE, ORANGE, GREEN, PURPLE, PINK, TEAL; the seventh is BLUE again) and never changed. The POS tints the category's products with it.","examples":["BLUE"]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","tone","createdAt"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict12"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/product-categories/{id}":{"patch":{"operationId":"products.categories.update","summary":"Update a product category","description":"Renames the category. Only an admin or an API token.","tags":["Products"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":30,"description":"Unique within the team, ignoring letter case.","examples":["Кульки"]}},"required":["name"],"examples":[{"name":"Декор"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},"name":{"type":"string","minLength":1,"maxLength":30,"description":"Unique within the team, ignoring letter case.","examples":["Кульки"]},"tone":{"type":"string","enum":["BLUE","ORANGE","GREEN","PURPLE","PINK","TEAL"],"description":"The category's colour, assigned at creation in turn (BLUE, ORANGE, GREEN, PURPLE, PINK, TEAL; the seventh is BLUE again) and never changed. The POS tints the category's products with it.","examples":["BLUE"]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","tone","createdAt"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict12"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/products":{"get":{"operationId":"products.list","summary":"List products","description":"The team's products in Ukrainian alphabetical order of names, optionally filtered by search or category. With a search, exact code or barcode matches come first, so a scanned code is on the first page however many names contain it.","tags":["Products"],"parameters":[{"in":"query","name":"page","schema":{"default":1,"description":"The page, from 1.","examples":[1],"type":"integer","minimum":1,"maximum":9007199254740991},"allowEmptyValue":true,"allowReserved":true,"description":"The page, from 1.","example":1},{"in":"query","name":"pageSize","schema":{"default":20,"description":"Items per page, up to 100.","examples":[20],"type":"integer","minimum":1,"maximum":100},"allowEmptyValue":true,"allowReserved":true,"description":"Items per page, up to 100.","example":20},{"in":"query","name":"search","schema":{"description":"Matches names containing it (case-insensitive) or an exact code or barcode, as the POS's single search field takes a name, an SKU or a scanned barcode.","examples":["кулька"],"type":"string","maxLength":100},"allowEmptyValue":true,"allowReserved":true,"description":"Matches names containing it (case-insensitive) or an exact code or barcode, as the POS's single search field takes a name, an SKU or a scanned barcode.","example":"кулька"},{"in":"query","name":"categoryId","schema":{"description":"Only products of this category.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},"allowEmptyValue":true,"allowReserved":true,"description":"Only products of this category.","example":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00"]},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},{"type":"null"}]},"uktzed":{"anyOf":[{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},{"type":"null"}]},"dkpp":{"anyOf":[{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},{"type":"null"}]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false,"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]}},"required":["type","name","letter","percent","included"],"additionalProperties":false},"description":"The team's tax rates the product's receipt lines carry, VAT first (by type, then letter): their letters are the lines' `taxLetters`.","examples":[[],[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true}]]},"categoryId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},{"type":"null"}],"description":"The product's category; null for none."},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","code","barcode","uktzed","dkpp","unit","price","taxes","categoryId","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00","name":"Гелієва кулька","code":"002","price":"45.00","unit":{"name":"шт"},"categoryId":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f","taxes":[],"barcode":null,"uktzed":null,"dkpp":null,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Products matching the search and category in total, on every page.","examples":[42]}},"required":["products","total"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}},"post":{"operationId":"products.create","summary":"Create a product","description":"Adds a product to the team's catalog; receipts copy its fields into their lines. A repeat with the same idempotency key returns the same product. Only an admin or an API token.","tags":["Products"],"parameters":[{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},"unit":{"default":{"name":"шт"},"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"taxLetters":{"default":"","type":"string","maxLength":15,"description":"Letters of the team's tax rates (GET /tax-rates) the product carries, e.g. «АД»: at most one of each type; empty for none.","examples":["","АД"]},"uktzed":{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},"dkpp":{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},"categoryId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]}},"required":["name","price"],"examples":[{"name":"Гелієва кулька","code":"002","price":"45.00","unit":{"name":"шт"},"categoryId":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f","taxLetters":""}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00"]},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},{"type":"null"}]},"uktzed":{"anyOf":[{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},{"type":"null"}]},"dkpp":{"anyOf":[{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},{"type":"null"}]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false,"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]}},"required":["type","name","letter","percent","included"],"additionalProperties":false},"description":"The team's tax rates the product's receipt lines carry, VAT first (by type, then letter): their letters are the lines' `taxLetters`.","examples":[[],[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true}]]},"categoryId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},{"type":"null"}],"description":"The product's category; null for none."},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","code","barcode","uktzed","dkpp","unit","price","taxes","categoryId","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00","name":"Гелієва кулька","code":"002","price":"45.00","unit":{"name":"шт"},"categoryId":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f","taxes":[],"barcode":null,"uktzed":null,"dkpp":null,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound8"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict13"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/products/{id}":{"patch":{"operationId":"products.update","summary":"Update a product","description":"Changes the given fields; omitted ones stay, null clears `barcode`, `uktzed`, `dkpp` or `categoryId`. Setting `uktzed` clears `dkpp` and vice versa. `unit` and `taxLetters` are replaced whole. Only an admin or an API token.","tags":["Products"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},{"type":"null"}]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"taxLetters":{"type":"string","maxLength":15,"description":"Letters of the team's tax rates (GET /tax-rates) the product carries, e.g. «АД»: at most one of each type; empty for none.","examples":["","АД"]},"uktzed":{"anyOf":[{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},{"type":"null"}]},"dkpp":{"anyOf":[{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},{"type":"null"}]},"categoryId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},{"type":"null"}]}},"examples":[{"price":"50.00","barcode":null}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00"]},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},{"type":"null"}]},"uktzed":{"anyOf":[{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},{"type":"null"}]},"dkpp":{"anyOf":[{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},{"type":"null"}]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false,"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]}},"required":["type","name","letter","percent","included"],"additionalProperties":false},"description":"The team's tax rates the product's receipt lines carry, VAT first (by type, then letter): their letters are the lines' `taxLetters`.","examples":[[],[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true}]]},"categoryId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},{"type":"null"}],"description":"The product's category; null for none."},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","code","barcode","uktzed","dkpp","unit","price","taxes","categoryId","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00","name":"Гелієва кулька","code":"002","price":"45.00","unit":{"name":"шт"},"categoryId":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f","taxes":[],"barcode":null,"uktzed":null,"dkpp":null,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound8"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict13"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}},"delete":{"operationId":"products.remove","summary":"Remove a product","description":"Removes the product and returns it as it was. Receipts that sold it keep their own copy of its lines. Only an admin or an API token.","tags":["Products"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00"]},"name":{"type":"string","minLength":1,"maxLength":1024,"description":"What the receipt lines of the product say (NAME).","examples":["Гелієва кулька"]},"code":{"type":"string","minLength":1,"maxLength":64,"description":"The product's SKU (артикул), its receipt lines' CODE; unique within the team. If omitted, the backend assigns one above the team's largest all-digit code, at least three digits long (\"001\", \"013\").","examples":["002"]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64,"description":"The product's barcode, its receipt lines' BARCODE; unique within the team.","examples":["4820000000017"]},{"type":"null"}]},"uktzed":{"anyOf":[{"type":"string","pattern":"^(?!0+$)(\\d{10}|\\d{8}|\\d{6}|00\\d{3}|\\d{4})$","description":"Product code by the УКТ ЗЕД classifier (UKTZED), 10, 8, 6 or 4 digits or 00 and 3 digits; required for excise goods. A product has it or `dkpp`, not both.","examples":["950300"]},{"type":"null"}]},"dkpp":{"anyOf":[{"type":"string","pattern":"^(\\d{2}\\.\\d{2}\\.\\d{2}-\\d{2}(\\.\\d{1,2})*|\\d{2}\\.\\d{2}\\.\\d{2}(-\\d{1,2})*|\\d{2}\\.\\d{2}(\\.\\d{1,2})*)$","description":"Service code by the ДКПП classifier (DKPP), XX.XX[.XX[-XX[.XX]]]. A product has it or `uktzed`, not both.","examples":["93.29.19"]},{"type":"null"}]},"unit":{"type":"object","properties":{"code":{"description":"Unit code by the classifier of units (UNITCD).","examples":[25],"type":"integer","minimum":1,"maximum":99999},"name":{"type":"string","maxLength":64,"description":"Unit name (UNITNM).","examples":["кг"]}},"required":["name"],"additionalProperties":false,"description":"The unit the product is sold in; `{ \"name\": \"шт\" }` if not given.","examples":[{"name":"шт"},{"code":2009,"name":"шт"}]},"price":{"type":"string","pattern":"^(?!0+\\.00$)\\d{1,13}\\.\\d{2}$","description":"Price per unit, the receipt lines' PRICE.","examples":["45.00"]},"taxes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","minLength":1,"maxLength":1,"description":"Letter that marks the tax and its rate on receipt lines (LETTER).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]}},"required":["type","name","letter","percent","included"],"additionalProperties":false},"description":"The team's tax rates the product's receipt lines carry, VAT first (by type, then letter): their letters are the lines' `taxLetters`.","examples":[[],[{"type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true}]]},"categoryId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The category the product is filed under (GET /product-categories).","examples":["2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f"]},{"type":"null"}],"description":"The product's category; null for none."},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["id","name","code","barcode","uktzed","dkpp","unit","price","taxes","categoryId","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"0b6f4f8e-5a43-4d2b-8c1e-7d9a3b2c1f00","name":"Гелієва кулька","code":"002","price":"45.00","unit":{"name":"шт"},"categoryId":"2f7c9b1e-4d3a-4c8b-9e6f-0a1b2c3d4e5f","taxes":[],"barcode":null,"uktzed":null,"dkpp":null,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound9"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict14"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/tax-rates":{"get":{"operationId":"taxRates.list","summary":"List tax rates","description":"Every team tax rate, in Ukrainian alphabetical order of letters, by which products and sales name them.","tags":["Tax rates"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"taxRates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","pattern":"^[АБВГҐДЕЄЖЗИІЇЙКЛМНОПРСТУФХЦЧШЩЬЮЯ]$","description":"LETTER of CHECKTAX and of the lines' LETTERS, a Ukrainian capital; unique in the team, whose rates are never removed (DPS: «певна літера може бути присвоєна лише один раз»).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e"]},"isDefault":{"type":"boolean","description":"Whether the POS prefills it on a new product. At most one rate of each type is the default.","examples":[false]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["type","name","letter","percent","included","id","isDefault","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e","type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"isDefault":false,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}},"required":["taxRates"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}},"post":{"operationId":"taxRates.create","summary":"Create a tax rate","description":"Adds a tax rate to the team's directory under a letter no team rate ever had. A repeat with the same idempotency key returns the same rate. Only an admin or an API token.","tags":["Tax rates"],"parameters":[{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":32767,"description":"Kind of tax or levy (CHECKTAX TYPE): 0 is VAT, 1 is excise, 2 and on other levies.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","pattern":"^[АБВГҐДЕЄЖЗИІЇЙКЛМНОПРСТУФХЦЧШЩЬЮЯ]$","description":"LETTER of CHECKTAX and of the lines' LETTERS, a Ukrainian capital; unique in the team, whose rates are never removed (DPS: «певна літера може бути присвоєна лише один раз»).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]}},"required":["type","name","letter","percent","included"],"examples":[{"type":1,"name":"Акциз","letter":"Ж","percent":"5.00","included":true},{"type":2,"name":"Збір","letter":"Ж","percent":"5.00","included":false}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","pattern":"^[АБВГҐДЕЄЖЗИІЇЙКЛМНОПРСТУФХЦЧШЩЬЮЯ]$","description":"LETTER of CHECKTAX and of the lines' LETTERS, a Ukrainian capital; unique in the team, whose rates are never removed (DPS: «певна літера може бути присвоєна лише один раз»).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e"]},"isDefault":{"type":"boolean","description":"Whether the POS prefills it on a new product. At most one rate of each type is the default.","examples":[false]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["type","name","letter","percent","included","id","isDefault","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e","type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"isDefault":false,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict15"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}},"/tax-rates/{id}":{"patch":{"operationId":"taxRates.update","summary":"Update a tax rate","description":"Changes the given fields; omitted ones stay. Type and letter never change: add another rate instead; rates are never removed. A rate in use is editable only while no team shift is open, though `isDefault` alone may change any time. Making a rate the default takes it from the other rate of its type. Products reflect the change at once; receipts keep the rates they were issued with. Only an admin or an API token.","tags":["Tax rates"],"parameters":[{"in":"path","required":true,"name":"id","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["8a6e0804-2bd0-4672-b79d-d97027f9071a"]},"example":"8a6e0804-2bd0-4672-b79d-d97027f9071a"},{"in":"header","name":"idempotency-key","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","examples":["5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"]},"description":"Client-generated per operation and reused on its retries: a repeat returns the first result instead of registering a second document.","example":"5f0c6a54-6b0e-4b5e-9a4e-3d7f1d0c2b11"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"isDefault":{"type":"boolean","description":"Whether the POS prefills it on a new product. At most one rate of each type is the default.","examples":[false]}},"examples":[{"percent":"7.00"},{"isDefault":true}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Kind of tax or levy (TYPE): 0 is VAT, 1 is excise.","examples":[0]},"name":{"type":"string","minLength":1,"maxLength":64,"examples":["ПДВ"]},"letter":{"type":"string","pattern":"^[АБВГҐДЕЄЖЗИІЇЙКЛМНОПРСТУФХЦЧШЩЬЮЯ]$","description":"LETTER of CHECKTAX and of the lines' LETTERS, a Ukrainian capital; unique in the team, whose rates are never removed (DPS: «певна літера може бути присвоєна лише один раз»).","examples":["А"]},"percent":{"type":"string","pattern":"^\\d{1,3}\\.\\d{2}$","description":"Percentage with two decimals.","examples":["20.00"]},"included":{"type":"boolean","description":"Whether the tax is included in the prices; false for a levy charged on top of them (inverse of SIGN).","examples":[true]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","examples":["3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e"]},"isDefault":{"type":"boolean","description":"Whether the POS prefills it on a new product. At most one rate of each type is the default.","examples":[false]},"createdAt":{"type":"string","format":"date-time","x-native-type":"date"},"updatedAt":{"type":"string","format":"date-time","x-native-type":"date"}},"required":["type","name","letter","percent","included","id","isDefault","createdAt","updatedAt"],"additionalProperties":false,"examples":[{"id":"3c1d7e2a-9b4f-4a6e-8d2c-5f0a1b2c3d4e","type":0,"name":"ПДВ","letter":"А","percent":"20.00","included":true,"isDefault":false,"createdAt":"2026-10-14T09:30:00.000Z","updatedAt":"2026-10-14T09:30:00.000Z"}]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Unauthorized"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Forbidden7"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NotFound10"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"409":{"description":"409","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Conflict16"},{"$ref":"#/components/schemas/UndefinedError"}]}}}},"422":{"description":"422","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnprocessableContent"},{"$ref":"#/components/schemas/UndefinedError"}]}}}}}}}}}