SudoSOS Back-end API / catalogue / vat
Catalogue: Vat ​
A VAT group is a named VAT rate that products reference. In the Netherlands the common ones are "Hoog 21%", "Laag 9%", and "Geen 0%", but SudoSOS stores the percentage as a double — Dutch VAT has never had decimal brackets, but politics can change that at any time and the schema would rather not need a migration the day it does.
Immutable rate, mutable label ​
VatGroup.percentage is declared update: false: once a group exists, its rate is fixed. To "change" a rate, create a new group and migrate products to reference it. Name, deleted, and hidden are the only mutable fields. This keeps historical accounting stable — a product that sold at 21% yesterday cannot retroactively become 9%.
Deleted vs. hidden ​
Two flags control visibility, and they solve different problems:
deleted— soft deletion. A group can only be marked deleted once no products reference it (seecanSetVatGroupToDeleted). The row stays in the database so historical SubTransaction rows and revisions keep resolving.hidden— excludes the group from user-facing pickers without affecting historical data. Useful for parking a rate that is no longer in use but still needs to compute for past transactions.
Linkage to products ​
Every ProductRevision references a VatGroup. Because revisions are immutable and pin the rate at transaction time, a product that is later moved to a different VAT group does not rewrite history — old sub-transaction rows keep resolving to the revision they were created against.
VAT declarations (Belastingdienst) ​
VatGroupService.calculateVatDeclaration aggregates VAT collected per group per period, so the treasurer can file with the Dutch tax authority. The cadence (monthly / quarterly / annually) is picked via VatDeclarationPeriod, matching the options the Belastingdienst offers.
For API interactions, refer to the Swagger Documentation.
Enumerations ​
| Enumeration | Description |
|---|---|
| VatDeclarationPeriod | Cadence of Dutch VAT declarations filed with the Belastingdienst. |
Classes ​
| Class | Description |
|---|---|
| VatGroup | TypeORM entity for the vat_groups table. Holds a named VAT rate that products reference. The percentage is immutable after creation; to change a rate, create a new group. |
| VatGroupController | Controller for managing all routes related to the vat group entity. |
| VatGroupService | Service class for the vat group entity. |
Interfaces ​
| Interface | Description |
|---|---|
| BaseVatGroupResponse | Base API Response for the vat group entity. |
| PaginatedVatGroupResponse | Paginated API Response for the vat group entity. |
| UpdateVatGroupRequest | API Request for updating an existing vat group entity. Only mutable fields; the rate itself cannot change on an existing group. |
| VatDeclarationResponse | API Response for a complete VAT declaration — one result table for a given year and period, containing one VatDeclarationRow per VAT group. |
| VatDeclarationRow | One row of a VAT declaration — the VAT collected for a single group, broken down by period. |
| VatGroupRequest | API Request for creating a new vat group entity. Adds the immutable percentage on top of the mutable fields in UpdateVatGroupRequest. |
| VatGroupResponse | API Response for the vat group entity. |
Functions ​
| Function | Description |
|---|---|
| canSetVatGroupToDeleted | Return whether a VAT group may be soft-deleted. A group is only deletable once no products reference it, since a referenced group would leave ProductRevision.vat dangling. |
| parseGetVatCalculationValuesParams | Parse VAT declaration parameters (year and period) from the query string of an HTTP GET request. The resulting values feed VatGroupService.calculateVatDeclaration. |
| parseGetVatGroupsFilters | Parse VAT group filter parameters from the query string of an HTTP GET request. |