# Versions and changes

The REST API has two versions in the same URL space: `/v03/` and `/v04/`. This page says which one to build on, what changes when you move, and what changed recently. One exception: the [Pro API](https://code.salaxy.com/integration/pro-api.md) for accounting firms is also served under `/v01/api/pro/...`, and the site's Pro guide uses that path.
Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

**Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md).

*Diagram: Your integration calls the Salaxy API host with one access token. The same host serves two versions side by side. The v03 path serves every area of the API. The v04 path serves mostly the same endpoints, with the payroll endpoints redesigned. You can move one area at a time. (v03 and v04 run on the same hosts and accept the same token. The note above says which version to build on; move area by area.)*

## Where to read each version

| | Reference | OpenAPI document |
|---|---|---|
| v03 | [REST API reference](https://code.salaxy.com/reference/rest-api.md) | [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) |
| v04 | [REST API reference v04](https://code.salaxy.com/reference/rest-api-v04.md) | [`/openapi/salaxy-04.json`](https://code.salaxy.com/openapi/salaxy-04.json) |

The API serves its own OpenAPI documents at `/openapi/v03.json` and `/openapi/v04.json` on each API host, for example `https://test-secure.salaxy.com/openapi/v03.json`. The earlier addresses under `/docs/swagger/` no longer work.

## From v03 to v04

Apart from the changes below, a v04 endpoint has the same path, parameters and models as in v03. To move a call, change `/v03/` to `/v04/` in the URL. v03 and v04 accept the same access token, so one integration can call both.

### Payroll

The payroll endpoints are redesigned. In v03, most payroll actions are separate commands that take the whole payroll object. In v04, the calculations and invoices of a payroll are sub-resources of that payroll, and each call sends only what changes.

| v03 | v04 | Notes |
|---|---|---|
| `GET /v03/api/payroll/odata` | `GET /v04/api/payroll` | The same OData list. `GET /v03/api/payroll` already works the same way |
| `POST /v03/api/payroll/add-employment` | `POST /v04/api/payroll/{id}/employments` | Body is an array of employment ids. The response is the added calculations as `CalculationListItem` objects, not the payroll |
| `POST /v03/api/payroll/add-calc` | `POST /v04/api/payroll/{id}/calcs` | Send the calculation ids in `ids` |
| `POST /v03/api/payroll/{id}/calcs` | `POST /v04/api/payroll/{id}/calcs` | **Same path, different contract.** See below |
| `POST /v03/api/payroll/delete-calc` | `DELETE /v04/api/payroll/{id}/calcs/{calcId}?delete=true` | One calculation per call. The calculation is deleted |
| `POST /v03/api/payroll/unlink-calc` | `DELETE /v04/api/payroll/{id}/calcs/{calcId}` | One calculation per call. Without `delete=true` it is only removed from the payroll |
| `GET /v03/api/payroll/cancel/{id}` | `POST /v04/api/payroll/{id}/cancel-invoices` | Body is an array of the calculation ids to cancel |
| `POST /v03/api/payroll/validate` | none | No v04 equivalent. Keep using v03 |
| `GET /v03/api/payroll/{id}/absences` | none | No v04 equivalent. Keep using v03 |

New in v04:

| Endpoint | Purpose |
|---|---|
| `GET /v04/api/payroll/{id}/calcs` | Lists the calculations of the payroll. Supports [OData queries](https://code.salaxy.com/reference/queries.md) |
| `POST /v04/api/payroll/{id}/preview-invoices` | Previews the invoices for the given calculations |
| `POST /v04/api/payroll/{id}/create-invoices` | Creates the invoices for the given calculations |

The invoice endpoints use the payment channel of the payroll (`input.paymentChannel`), so the URL has no channel. The body is an array of calculation ids. The v03 invoice endpoints, for example `POST /v04/api/invoices/create-for-payroll/{channel}/{payrollId}`, also work in v04 unchanged.

```http
POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/create-invoices
Authorization: Bearer {token}
Content-Type: application/json

["{calcId1}", "{calcId2}"]
```

### Saving calculations

`POST /payroll/{id}/calcs` has the same path in both versions, but the request and the response differ:

| | v03 | v04 |
|---|---|---|
| Request body | One `Calculation` object | A `PayrollCalculationsCollection`: `ids` (existing calculations to add) and `objects` (calculations to add or update) |
| Response | The saved `Calculation` | An array of `CalculationListItem` objects |

```http
POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/calcs
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": ["{calcId1}", "{calcId2}"]
}
```

### Options

Some v04 payroll endpoints take an optional `options` object. Send its fields as ordinary query parameters, for example `?excludePeriodicInvoices=true`.

| Endpoint | Options model | Fields |
|---|---|---|
| `POST /v04/api/payroll` | `PayrollSaveOptions` | `applyEmploymentDefaultRows` |
| `POST /v04/api/payroll/{id}/calcs` | `PayrollCalculationsSaveOptions` | `isMerge`, `rowMergeOption`, `sourceId`, `applyEmploymentDefaultRows`, `applyWorktime` |
| `.../preview-invoices`, `.../create-invoices`, `.../cancel-invoices` | `PayrollInvoicesOptions` | `excludePeriodicInvoices` |

### Reports

These report endpoints are not in v04. Keep using v03 for them.

| v03 endpoint | Notes |
|---|---|
| `GET /v03/api/reports/accounting/{refDate}` | Monthly or yearly `AccountingData` for an accounting target |
| `GET` and `POST /v03/api/reports/accounting` | `AccountingData` for a set of calculations |
| `GET /v03/api/reports/accounting/{refDate}/holiday-pay-debt` | Holiday pay debt as ledger entries. The report shape, `GET /v04/api/reports/holiday-pay-debt/{refDate}`, is in v04 |
| `GET /v03/api/reports/validate/pay-certificate/{id}` | Validates a pay certificate request |

`GET /v04/api/reports/data/accounting/{tableType}` and `GET /v04/api/reports/data/accounting/{tableType}/{refDate}` are in both versions. They return an `AccountingReportTable`, a different model from `AccountingData`, and take no accounting target. They do not replace the endpoints above. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md).

### New in v04

| Area | Endpoints |
|---|---|
| Calculation corrections | `/v04/api/calculations/correction/...` |
| Company authorisation | `POST /v04/api/company-authorization/link` creates a start link that sends a company representative to the authorisation flow. For testing without credentials, see [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md#test-helpers-in-v04-beta) |
| Data funnel | `/v04/api/data-funnel/...`: import data from files and rows through plans, runs and transformations. See [Limits](https://code.salaxy.com/reference/limits.md) for the file upload |
| Overview | `GET /v04/api/overview/all`, `GET /v04/api/overview/welcome-worker` |
| Payment channel config | `/v04/api/settings/payment-channels/{channel}/config`: see [Company settings](https://code.salaxy.com/integration/company-settings.md#payment-channel-config). Errors are [problem details](https://code.salaxy.com/reference/errors.md#problem-details-on-new-v04-endpoints) |
| Pro | `/v04/api/pro/...`: the [Pro API](https://code.salaxy.com/integration/pro-api.md), in the v04 Pro tag. The same endpoints are served under `/v01/api/pro/...`, which the Pro guide uses |

Endpoints for creating and changing test data are listed in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md).

## Which versions does an endpoint serve

- **Availability is per endpoint.** Two endpoints of one controller can serve different versions. Check the endpoint in the OpenAPI document of the version you call, not its neighbour.
- **An unversioned request resolves to v03.**
- **Test can be ahead of production.** An endpoint in the test OpenAPI document may not be in production yet. See [Environments](https://code.salaxy.com/get-started/environments.md).

## Changelog

Newest first. **Changes in the API** may affect your integration. **Added to the reference** only grows the reference: a client generated from it keeps working.

### v03 changes

| Change | What to do |
|---|---|
| The calculation row type `script` is renamed to `info`. An `info` row is for information only | Use `info` in `rowType` and accept `info` in responses. The reference still lists `script`, so code generated from an earlier file compiles |
| `Employment.accruals` is no longer used. The API does not store accrued time on the employment | Do not read or write `accruals`. For the remaining accrued holidays of an employment use `GET /v03/api/holidays/employment/{employmentId}/available-holiday-accruals` |
| The OpenAPI documents come from a new tool. The API is the same, but model names and types differ from the earlier documents: for example `PageResult_CalculationListItem_` is now `PageResultOfCalculationListItem`, and many fields are nullable | A client generated from an earlier document does not compile against a client generated from these documents. Regenerate and adjust |

### Added to the v03 reference

Nothing is removed or renamed. You can regenerate a client without code changes, but make sure it accepts enum values it does not know yet.

| Area | Added |
|---|---|
| Calculator | `POST /v03/api/calculator/addrow`, `deleterow`, `salary`, `setunionpayment`, `taxdeduction`, `work`, `workerset`, `recalculate-worktime/{type}` |
| Tax cards | `POST /v03/api/taxcards/approve/{method}`, `POST taxcards/file`, `GET taxcards/file/{id}`, `GET taxcards/issued`, `GET taxcards/my`, `GET taxcards/preview/{id}`, `GET taxcards/shared-exists/{personalId}` |
| Invoices | `POST /v03/api/invoices/create/{channel}/{id}`, `preview/{channel}`, `preview-by-id/{channel}`, `preview-for-payroll/{channel}/{payrollId}` |
| Reports | `GET` and `POST /v03/api/reports/data/accounting/{tableType}`, `GET reports/data/accounting/{tableType}/{refDate}`, `GET reports/pay-stats/{employmentId}`, `POST reports/pdf/{type}` |
| Employments | `GET /v03/api/employments/employing`, `GET employments/employing/{id}` |
| Query parameters | `$top` and `$skip` on several list endpoints; `version` on the SEPA endpoints |
| Enum values | `CalculationRowType`: `info`; `PayStatsPeriodLength`: `holidayYear` |
| Fields | Several optional fields. Diff the OpenAPI document for the full list. Among them are the `taxPercent` fields on `CalcTax` and `TaxcardResult` |

## Checklist

- You build on the current version, not on a beta version.
- You move one area at a time and test each in the test environment.
- You do not send a v03 payroll body to a v04 path that has a different contract.
- Your client accepts enum values it does not know yet.
- You regenerate your client from the OpenAPI document of the version you call.
