22 · Ukraine — VAT (ПДВ) by first event, regimes, and the Unified Register of Tax Invoices (ЄРПН)

Customization(3) layer. Depends on Organization, HR, Inventory, Purchasing, Sales, and Tax — six models, the widest coverage among the country packages.

← General specification · country package template — 20-Localization-Overview

Purpose#

The second country package after Saudi Arabia. It follows the same rule: the core knows nothing about Ukraine, and Ukraine does not rewrite the core. Tax is data — codes, rates, and rules in the Tax model — and the package adds only what the universal engine does not and should not have.

Ukraine has four things that KSA does not have:

1. First event (Articles 187.1 and 198.2 of the Tax Code of Ukraine, ПКУ) — the tax liability arises on whichever happens earlier: shipment or payment. The universal engine calculates tax from a document; here tax is calculated from counterparty accumulation.
2. Taxation regimes — one database can hold LLCs (ТОВ) on the general system and several individual entrepreneurs (ФОП) on the simplified system, with different rates and different bases.
3. Payroll withholdings and three own documents — personal income tax (ПДФО), military levy (військовий збір), remittance of withheld tax to the budget, single social contribution (ЄСВ) for a FOP "for self", and the VAT refund claim (бюджетне відшкодування ПДВ) are handled by package objects, not by the common tax document.
4. Unified Register of Tax Invoices (ЄРПН) through an operator — signatures and XML stay outside the platform. The package sends a flat JSON of facts, not a State Tax Service form.

Contour fact. 6 dictionaries, 4 dictionary extensions, 3 own documents (not zero — an important correction to the early understanding of the package), 8 registers, 5 services, 3 jobs, 13 commands, 9 extensions of other documents (one of them, TaxReturn.LocalizationUkraine, is declared but empty), 4 outbound channels, 3 reporting views, and 17 integration tests.

Process description for analysts — Ukraine; this page is the object-level reference.

What is created (object map)#

Total: 6 dictionaries, 8 registers, 3 documents, 5 services, 3 jobs, 13 commands, 1 enum, 4 EDTs, 4 dictionary extensions, 9 extensions of other documents (1 of them empty), 4 outbound channels, 3 reporting views, and 17 integration tests.

model.json#

{
  "modelType": "Custom",
  "modelVersion": "1.44.0",
  "layerId": 3,
  "publisher": "ZuloOne",
  "name": "LocalizationUkraine"
}

Six dependencies (not an abstract template — the real minVersion values from model.json):

As with KSA, the core has no backlink to the package: the connection is extensions and data. There is no Accounting dependency because the package does not touch the chart of accounts directly.

Reference data (DataPackages/vat-UA.json)#

The vat-UA manifest (DataPackages/index.json: when: "country", country: "UA", sort: 26 — immediately after Saudi sort: 25) loads tax legislation as four kinds of objects:

Example with numbers: military levy increase. Salary of 30,000 ₴ accrued on 2024-11-30 withholds military levy at 1.5% = 450 ₴. The same salary accrued on 2024-12-01 withholds 5% = 1,500 ₴ — more than three times more one day later. The rate is selected by accrual date, not by payment date (see Salary deductions).

16 tax codes — not only standard/reduced/zero/exempt. In addition to the obvious UA-S (20%), UA-7 (7%), UA-Z (zero), and UA-E (exempt), the package has UA-ZX — zero rate for export, separate from ordinary UA-Z: both map to category ZERO_RATED, but in declaration J0200126 they go to different lines (2.1 for export, 3 for other zero-rated supplies). Single tax has not only five "direct" codes (UA-EP3/5/15/6/10), but also double rates for special circumstances that are usually absent from a short single-tax description: UA-EPB3/UA-EPB5 for barter settlements (the non-cash form by itself raises the rate to 6%/10%, regardless of the income limit), and UA-EPF3/UA-EPF5 for income from activity forbidden for the simplified system (the same double tariff). UA-PDFO and UA-VZ cover payroll withholdings.

18 mappings cover THREE different ReturnType values, not one. J0200126 (VAT declaration) has 5 OUTPUT lines (UA-S→1.1, UA-7→1.2, UA-ZX→2.1, UA-Z→3, UA-E→5) and 2 INPUT lines (UA-S→10.1, UA-7→10.2), all with EffectiveFrom: 2024-10-01. J0103509 (single-tax declaration for a legal entity) has 8 OUTPUT lines: UA-EP3→1.3, UA-EP5→1.4, UA-EP6→2.3, UA-EP10→2.4, UA-EPB3→3.3, UA-EPB5→3.4, UA-EPF3→4.3, UA-EPF5→4.4 (EffectiveFrom: 2025-01-01). F0103309 (FOP declaration, a return code separate from J0103509) has 3 lines: UA-EP3→05, UA-EP5→06, UA-EP15→07 (EffectiveFrom: 2025-01-01). These three ReturnType values are what UaExportTaxReturn, UaExportSingleTax, and UaExportFopSingleTax export, respectively.

What the package does not create. ЄСВ (social insurance) rates are not here; they are in the common HR contour. vat-UA carries only VAT/ЄП/ПДФО/ВЗ. The package also does not create data for military-levy limits or a PIT base ceiling. The ceiling applies to ЄСВ, not to withholdings (see Salary deductions).

Settings#

LocalizationUkraineSettings is one record per tenant. Fields and the effect of each field:

The taxpayer identification number is not stored here. It lives in LegalEntity.TaxRegistrationNumber in Organization, because it is a legal-entity attribute, not a country setting.

Taxation regimes#

UaTaxRegime is a field on the legal entity through a dictionary extension (the Enum + EDT pair UaTaxRegimeEdt, because the field cannot reference the enum directly). It has four values:

Default is VatPayer: a tenant that does not know about regimes keeps accounting as a regular VAT payer.

Example with numbers. A FOP on 3% with VAT received 120 ₴:

• VAT base = 120 / 1.20 = 100, liability 20 ₴;
• single-tax base is also 100, not 120: single tax is charged on income excluding VAT.

The same amount for a FOP on 5% without VAT gives a single-tax base of 120 ₴ and zero VAT.

A regime change is not only a field change. Exceeding the limit from UaSingleTaxLimit writes a transition to UaRegimeChange, and job ApplyUaRegimeChanges moves the legal entity to the general system from the first day of the month after the quarter of the excess (ПКУ 293.8). The excess itself is taxed at 15% (ПКУ 293.4). At the same time, the regime change sets and removes TaxMapping for the exemption code; without that, sales after the transition would use the default code.

Dictionaries#

UaRegimeChange#

Audit trail, not a service table (isLogged: true). The line lives from excess detection until the transition date arrives, and remains after that.

Fields: see UaRegimeChange in Objects below.

UaSingleTaxLimit#

Dated annual limit (ПКУ 291.4). It is data, not a code constant, because it changes every year with the minimum wage.

Fields: see UaSingleTaxLimit in Objects below.

UaBankConnection#

Tenant half of the pb-statements channel: address, environment, account, and a reference to the credential. The token itself is not written here, because the dictionary is exported to the workspace and the workspace is in git. This is not TaxAuthorityConnection: the tax operator and the bank are different contours with different secrets.

Fields: see UaBankConnection in Objects below.

UaLandPlot#

Land plots for MPZ (minimum tax liability, мінімальне податкове зобов'язання) = normative monetary valuation × rate from settings × months in the period / 12. If the dictionary is empty, declaration appendices J0135709/F0133209 remain empty.

Fields: see UaLandPlot in Objects below.

UaTaxFilingExport#

Prepared return export for submission, created by the UaExport* commands.

Fields: see UaTaxFilingExport in Objects below.

Dictionary extensions#

The HR personnel core knows nothing about DPS forms. All 13 fields above live in this package's extensions, not directly in Employee/Position/ TimeOff.

Documents#

The three own documents are thin and one-directional, with the same skeleton: OnBeforeCreateAsync: next → IRecordDefaults.SeedAsync → seed LegalEntity if empty; OnBeforePostAsync: validate only on the subtype being posted, and re-read the document through IDocumentManager.GetDocumentAsync.

UaTaxRemittance#

Remittance of withheld PIT/military levy to the budget. requiresPosting + postOnSave, clonable. Header: required LegalEntity, required TaxCode (PIT or military-levy code). This is the package's only document with a table part: Lines (Employee × Amount).

Draft → Paid → Voided (both endpoint subtypes are isReadOnly). Transaction script UaTaxRemittancePaidTx on Paid: for each line with non-empty Employee and non-zero Amount, writes RegisterMovementSpec("UaPayrollLevy").Dim("LegalEntity", …).Dim("Employee", …).Dim("TaxCode", …).Res("Transferred", …). It does not touch TaxLedger: remittance does not change the liability; it only closes it with money. Voided removes these movements itself (Mix). Manual compensation is not needed here, unlike payroll payment, where PaidBase is written by an event handler.

Pre-posting checks: LegalEntity and TaxCode are not empty, at least one line exists, no amount is negative, and the sum of all lines is greater than zero.

UaFopEsvAccrual#

Accrual of ЄСВ for a FOP "for self". The employment contour does not write here; that is SocialInsurance in HR. Header: required LegalEntity, required Amount. No table part.

Draft → Posted → Voided. Transaction script UaFopEsvAccrualPostedTx on Posted: when LegalEntity is non-empty and Amount != 0, writes RegisterMovementSpec("UaFopEsv").Dim("LegalEntity", …).Res("Amount", …). Checks: LegalEntity is not empty, Amount > 0.

UaVatRefund#

VAT refund claim (line 20.2 of declaration J0200126, not more than line 19). Header: required LegalEntity, required Amount. No table part.

Draft → Posted → Voided. Transaction script UaVatRefundPostedTx on Posted writes RegisterMovementSpec("UaVatRefundClaim").Dim("LegalEntity", …).Res("Amount", …). Checks: LegalEntity is not empty, Amount > 0.

Registers#

Register dimensions and resources: see UaVatFirstEvent, UaVatPayable, UaPurchaseFirstEvent, UaVatCredit, UaPayrollLevy, UaBankStatement, UaFopEsv, and UaVatRefundClaim in Objects below.

Why the first event is keyed by dimensions, not analytics. The totals driver calculates the accrual, and the driver sees only register coordinates — analytics are unavailable to it. A register split by analytics would silently match zero lines, without an error. Therefore, UaVatFirstEvent carries legal entity, customer, and contract as dimensions. There are no duplicate analytics for them: customer and contract are already columns, and outlet moves to UaVatPayable.

Why payroll needed a separate register. TaxLedger (Tax) is split by direction, legal entity, and tax code. That is enough to pay the budget, but not enough to show withholding by a specific employee. Form 4ДФ needs the person, so UaPayrollLevy adds the Employee dimension.

UaBankStatement is the package's only registerEngineType: Information register. The other seven are registerEngineType: Standard with a balance table. The statement does not accumulate a balance; it stores posting facts, so useBalanceTable: false and allowNegativeBalance: true describe an import log, not a balance.

Salary deductions#

ЄСВ 22% did not require its own code. It is exactly the social-insurance contour in HR, and the package sets it through settings, not logic.

PIT 18% and military levy are withheld under separate codes and written to UaPayrollLevy and TaxLedger. The military-levy rate is taken on the accrual date: 1.5% until 2024-12-01, then 5% (see the example with numbers above). The ЄСВ base ceiling does not apply to withholdings; they have their own base.

Withholding reduces the debt to the employee through the PayrollLiability .Withheld resource in HR. This is the contract for any second withholder: without it, voiding the payroll fund would treat itself as the only one.

Remittance of the withheld amount to the budget is a separate document, UaTaxRemittance (above), not a subtype change on the payroll statement: only that document writes Transferred in UaPayrollLevy.

ЄРПН — electronic tax invoice#

The envelope is the common TaxDocument (Tax), with subtypes Draft → Issued → Cleared | Rejected; deduplication by source document and the submission journal already exist in the core. The package adds service UaEInvoice, two outbound channels (erpn-send and erpn-receipt), and job PullUaTaxInvoiceReceipts.

Why it is not like KSA. In Saudi Arabia, the host assembles XML and the signature, and Fatoora responds to the same submission. In Ukraine, XML and the qualified electronic signature (КЕП) stay with the operator: the script does not know DSTU 4145, and the key is in the operator's cabinet. Therefore the package sends a flat JSON of facts — contour, number, date, tax number (ІПН), lines — not a DPS form. A made-up form field name would pass our validation and fail in the cabinet when the registration deadline is already urgent.

Successful sending does not close the invoice. The operator has only accepted it for processing. The "sent, no response" state is resolved by a query (UaResolveTaxInvoice or the receipt job), not by resubmission: a repeat submission would create a second document for the same operation.

Channel erpn-gov is direct exchange with the state register for scenarios where the operator is not involved (status/reference request). erpn-send and erpn-receipt serve the regular operator route. Those three plus bank channel pb-statements make the package's four outbound channels.

The Ukraine sales extension folder is SalesRealization.LocalizationUkraine. Bindings inside point to SalesRealization; the handler is found by objectName in the script envelope, not by the folder name.

Extensions of other documents#

Direct package writes into other models' registers (PayrollLiability, TaxLedger from the two HR handlers above, next to package register UaPayrollLevy) are explained as a pattern in 20-Localization-Overview.

Services#

• UaFirstEvent — determines whether the first event (shipment or payment) has occurred by the accumulation in UaVatFirstEvent/UaPurchaseFirstEvent, and calculates the accrual as the increase of max(Shipped, Paid), so that an advance and a later shipment for the same amount do not double-tax it. Called from transaction scripts such as UaVatTx, UaPaymentFirstEventTx, and UaPurchaseReceiptTx.
• UaPayrollLevies — calculates PIT/military levy by the rate effective on the accrual date (see Salary deductions) and writes all three destinations in one call: UaPayrollLevy, PayrollLiability.Withheld (HR), and TaxLedger (Tax).
• UaTaxFiling — assembles UaTaxFilingExport by return code: reads TaxLedger/TaxReportMapping for the period, creates CSV and, where applicable, unsigned DeclarXml. Common entry point for all seven UaExport* commands.
• UaEInvoice — builds a flat JSON envelope for a tax invoice or adjustment calculation from the source document and queues channel erpn-send; parses receipts from inbound channels erpn-receipt/erpn-gov.
• UaBank — parses the Autoclient statement (REF+REFN, TRANTYPE C/D) into UaBankStatement lines. It does not itself reconcile with CustomerPayment/ VendorPayment by EDRPOU; that is intentionally left to a person (see the register description above).

Outbound channels and jobs#

Menu#

Root group Ukraine (displayOrder 12) with four subgroups:

• Settings — LocalizationUkraineSettings, UaBankConnection.
• Dictionaries — UaSingleTaxLimit, UaRegimeChange, UaTaxFilingExport, UaLandPlot.
• Registers — UaVatPayable, UaVatFirstEvent, UaVatCredit, UaPurchaseFirstEvent, UaPayrollLevy, UaBankStatement, UaFopEsv, UaVatRefundClaim.
• Documents — UaTaxRemittance, UaFopEsvAccrual, UaVatRefund.

Services, jobs, and reporting views are not shown in the menu because they are not menu-navigable object kinds on this platform.

Reporting views#

Three Custom Reports read package registers:

Printed declaration forms#

11 printed forms are physically located in directories of OTHER models. The form belongs to the host document, not to the package that fills it with data:

• 10 forms under Tax/Documents/TaxReturn/PrintForms/: UaDps4DfZr, UaDpsCalculationZr, UaDpsD1Zr, UaDpsD5Zr, UaDpsD6Zr, UaFopSingleTaxDeclarationZr, UaLevyWorkpaperZr, UaQuarterlyWorkpaperZr, UaSingleTaxDeclarationZr, UaVatDeclarationZr.
• 1 form under Sales/Documents/SalesRealization/PrintForms/: UaFiscalReceiptSample.

Business logic and invariants#

Prepayment is taxed before shipment; shipment does not accrue tax a second time. Accrual uses the increase of max(Shipped, Paid), not the sum: an advance of 120 ₴ closes the base, and a later shipment for the same amount adds nothing.

Partial prepayments together produce one full tax. Two half-events create exactly one full liability, not two and not one and a half.

A credit note moves the base, not only the tax, and does not release the liability until the prepayment is returned.

VAT from different outlets of one customer is not mixed because the contract is part of the register coordinates.

A payment whose legal entity conflicts with the line contract is rejected, and an empty legal entity is taken from the contract. Otherwise, Shipped and Paid would diverge by coordinates and tax would be accrued twice.

A non-VAT payer still writes events, but does not move credit: switching between regimes does not lose history.

Remittance and accrual of FOP ЄСВ / VAT refund do not accrue tax twice. All three own documents write a resource register without a second entry in TaxLedger: UaTaxRemittance closes a liability that is already accrued as debt and does not accrue it again; UaFopEsvAccrual/UaVatRefund are independent facts, not derivatives of sales or purchases.

Voided removes its own movements itself (Mix), except in one place. On payroll payment, PaidBase is written by an event handler and removal requires manual compensation. The package's own documents (UaTaxRemittance and others) do not need that, because only a transaction script writes their movements.

Package tests#

17 integration tests cover: end-to-end VAT flow by first event (UkraineVatFlowTest), seeded rates (UkraineSeededRatesTest), regimes and forced change (UkraineTaxRegimeTest, UkraineForcedRegimeChangeTest), input VAT on purchase (UkrainePurchaseVatTest), declaration exports (UkraineFilingExportTest, UkraineQuarterlyFilingTest, UkraineVatDeclarationFilingTest, UkraineFopSingleTaxDeclarationFilingTest, UkraineSingleTaxDeclarationFilingTest, UkraineDpsPayrollFilingTest, UkrainePayrollFilingTest), exemption mapping (UkraineExemptMappingTest), payroll withholdings (UkrainePayrollLevyTest), bank connection and statement (UkraineBankConnectionTest, UkraineBankStatementTest), and the single-tax limit (UkraineSingleTaxLimitTest).

What's not there yet#

• No live exchange with M.E.Doc in CI: the MakeDoc/ToGov/GetDocInfo adapter is in the package, but REST is a service on the accountant's PC. Setup note: M.E.Doc on the client. The exchange itself is not covered by tests.
• PrivatBank statement import is implemented, but without a live sandbox. Channel pb-statements, dictionary UaBankConnection, service UaBank, job PullUaBankStatements, and register UaBankStatement are all available in code and covered by tests (UkraineBankConnectionTest, UkraineBankStatementTest). What is missing: an Autoclient sandbox for checking against a live API and automatic creation of CustomerPayment/VendorPayment from a statement line. EDRPOU reconciliation is intentionally manual; see the register above. Setup note.
• No Diia (Дія). Login is platform identity, not a package feature. Why it is separate.
• No DPS cabinet container (Order No. 499 / QES). Unsigned DECLAR for the payroll J05 family is stored in field DeclarXml for import into M.E.Doc. Forms with official identifiers: payroll J0500111 / J0510411 / J0510111 / J0510511 / J0510611 (4ДФ R01011=income sign 101 / R01012=102, R0107=line 3; D1 G5 citizenship / G6S sex / G8=26 civil-law contract / G111–G113 full name / G12 Sick / G13 unpaid / G14 HireDate/FireDate / G15 maternity leave / G21–G22 part-time and incomplete hours / G24 new workplace from the flag, not HireDate; D5: HireDate/FireDate/DpsTransferDate/ DkppCode; ordinary employers do not file D2/D3), VAT J0200126 (form rows, not R00xG3; line 20.2 from UaVatRefund; UA-ZX→2.1, UA-Z→3), single tax for legal entities J0103509 (UA-EP6/UA-EP10 line 2, UA-EPB3/UA-EPB5 line 3, UA-EPF3/UA-EPF5 line 4, MPZ from UaLandPlot), and FOP F0103309 (F0133109 from UaFopEsvAccrual). Accrued amounts come from registers; paid amounts after PayrollPayment; ЄСВ paid from SocialInsurancePayment (D1 and R0107 are not reset); remitted from document UaTaxRemittance; C_REG/C_STI are legal-entity fields in the CSV header and in the DeclarXml head.
• Workpapers UA-LEVY and UA-QPR remain for transfer without DPS column codes.

Links with other modules#

• Outgoing: Tax — codes, rates, mappings, ledger, invoice envelope, TaxReturn declaration (empty extension); Sales and Purchasing — documents extended by the package; HR — accrual base, withholding resource, Employee/Position/ TimeOff fields; Organization — legal entity, its regime, and DPS codes; Inventory — counterparties and item in the first event.
• Incoming: none. The package is the top layer; nothing references it.

Objects#

Generated from workspace metadata by node tools/gen-reference.mjs; edit the metadata, not this block.

Dictionaries#

LocalizationUkraineSettings — Ukraine settings

UaBankConnection — Bank connections

UaLandPlot — Land plot (Ukraine MPZ)

UaRegimeChange — Forced regime change

UaSingleTaxLimit — Single tax revenue limit

UaTaxFilingExport — Tax filing export

Documents#

UaFopEsvAccrual — FOP ESS for self (Ukraine)

Header fields:

Subtypes:

Commands:

UaTaxRemittance — Tax remittance to budget (Ukraine)

Header fields:

Subtypes:

Commands:

UaVatRefund — VAT refund claim (Ukraine)

Header fields:

Subtypes:

Commands:

Registers#

UaBankStatement — PrivatBank statement lines

Dimensions:

Resources:

UaFopEsv — FOP ESS for self (Ukraine)

Dimensions:

Resources:

UaPayrollLevy — Ukraine payroll levies withheld

Dimensions:

Resources:

UaPurchaseFirstEvent — Ukraine input VAT first event

Dimensions:

Resources:

UaVatCredit — Ukraine input VAT credit

Dimensions:

Resources:

UaVatFirstEvent — Ukraine VAT first event

Dimensions:

Resources:

UaVatPayable — Ukraine VAT payable

Resources:

Analytics:

UaVatRefundClaim — VAT refund claim (Ukraine)

Dimensions:

Resources:

Table parts#

UaTaxRemittanceLines — Remittance lines

Used by: UaTaxRemittance.