Core concepts

key, toolId and slug

A tool can be addressed in three ways:

Identifier	Example	Persistence	Used for
`key`	`kdv`	Permanent, the same in every environment	Integrations. The recommended identifier.
`toolId`	`8410ffe8-…` (UUID)	Environment-specific	Only for the endpoint that calculates by `toolId` (`calculateTool`).
`slug`	`kdv-hesaplama`	May change, differs by language	The page address on the website.

The key rule: lowercase letters, digits and hyphens; 2–64 characters (^[a-z0-9]+(-[a-z0-9]+)*$). Lists and search results return the key in every record. All keys are listed in the tool catalog.

Languages

The locale parameter can be tr or en. If a tool is not published in the requested language, 404 NOT_FOUND is returned; there is no automatic fallback to another language. The alternates field in the tool definition shows which languages and addresses the tool is available in.

Decimals are strings

Money and rate values are sent and received as strings: "1234.56". The dot is the decimal separator and there is no thousands separator. If you send a JSON number (1234.56), the request is rejected with 422 VALIDATION_ERROR.

Results are also returned as strings and always contain as many decimal places as the field’s scale ("1200.00"). Format them on your side without converting to floating point; calculations run on the server with decimal arithmetic, so no floating-point error occurs.

Type	Sent as	Example
`decimal`	string	`"1234.56"`
`date`	string, `YYYY-MM-DD`	`"2026-01-15"`
`boolean`	JSON `true` / `false`	`true`
`enum`	string, one of the `values` in the definition	`"exclusive"`

asOf: the rate date

Tax rates, exemption amounts and limits change over time. Every calculation uses the rates in force on the asOf date. If you omit it, today is used (Europe/Istanbul). To calculate with a past date, send it:

{ "asOf": "2023-01-15", "inputs": { "amount": "1000", "mode": "exclusive", "vatRateOption": "standard" } }

If no rate was in force on that date, 422 RATE_UNAVAILABLE is returned (details.rates, details.asOf). meta.rates in the response gives the key, value and effective range of every rate used; store it to make the result auditable.

Tool version

When a tool’s definition is updated, versionNumber increases. If you read the definition and generate your own form, send this number as version in the calculation request:

If the version is still live, the calculation is performed.
If the tool has been updated in the meantime, 409 CONFLICT (details.reason = "VERSION_OUTDATED") is returned; fetch the definition again and update your form.
If you do not send version, the live version is always used.

meta.toolVersion in the response shows the version used in the calculation. The API version (/v1) and the tool version are independent of each other.

Availability

Lists and the definition contain an availability field:

ONLINE: working normally.
MAINTENANCE: the tool is temporarily under maintenance. A calculation request returns 503 MAINTENANCE with Retry-After.

You should expect an error from a tool under maintenance; show the user a “temporarily unavailable” message and retry after Retry-After. See Errors.

Deterministic results

The same tool version, the same inputs and the same asOf date always give the same result. The calculation definition (the formula) is not public; only the input/output schema, labels, rates and results are published.