# Taxcards

Year 2019 version for taxcards. This API will be replaced by the new 2020 version in January 2020. The new version is labeled as V03 (3.0-rc in before release) and old V02.

Salaxy API v03, **Finland only**. 20 operations. Interactive version: [REST API reference](https://code.salaxy.com/reference/rest-api.md). Machine-readable: [OpenAPI document](https://code.salaxy.com/openapi/salaxy-03.json).

**The reference wins:**
These pages are generated from the OpenAPI document. If a guide and this reference disagree about a field, follow the reference. Error responses are not in the document — see [Errors](https://code.salaxy.com/reference/errors.md).

## `GET /v03/api/taxcards/calculate/{id}`

**Calculates the widhholding tax based on a given tax card**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Identifier of the tax card |
| `income` | query | number |  | New salary or other income, for which the widthholding tax is calculated. |
| `paymentDate` | query | string |  | Date of payment (typically SalaryDate) determines the taxation year. |

Response: `TaxcardResult`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/calculate/{id})

## `POST /v03/api/taxcards/calculate`

**Calculates the widhholding tax based on a given tax card**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `income` | query | number |  | New salary or other income, for which the widthholding tax is calculated. |
| `paymentDate` | query | string |  | Date of payment (typically SalaryDate) determines the taxation year. |

Request body: `Taxcard` (required)

Response: `TaxcardResult`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/calculate)

## `GET /v03/api/taxcards`

**Performs an OData query to the search index.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `$search` | query | string |  |  |
| `$filter` | query | string |  | Specifies the logic to pull back a subset of records. |
| `$orderby` | query | string |  | Specifies the values used to sort the collection of entries. |
| `$select` | query | string |  | The $select system query option allows the clients to requests a limited set of properties for each entry. |
| `$top` | query | number |  | Specifies the subset of entries by count. |
| `$skip` | query | number |  | Specifies the count of entries to skip. |
| `$count` | query | boolean |  | Indicates whether or not to include a total entry count. |

Response: `PageResultOfTaxcardListItem`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards)

## `POST /v03/api/taxcards`

**Updates or creates a new object.
Paid calculations may be checked and added as Diff rows depending on taxcardOnly parameter.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `calcDiffCheck` | query | TaxcardCalcDiffCheck |  | Defines the behavior of how to check and handle existing paid calculations when saving the taxcard. |

Request body: `Taxcard` (required)

Response: `Taxcard`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards)

## `GET /v03/api/taxcards/{id}`

**Gets a single object based on identier. 
By default also returns Diff if paid calculations are different in database than in the taxcard.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Unique identifier for the object |
| `calcDiffCheck` | query | TaxcardCalcDiffCheck |  | Defines the behavior of how to check and handle existing paid calculations. Default is "getDiff" where the system fetches the paid calculations in the database and adds them as Diff-rows. Note that "commitDiff" is not currently supported. May later be supported if necessary. |

Response: `Taxcard`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/{id})

## `DELETE /v03/api/taxcards/{id}`

**Deletes an object from the storage**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Unique identifier for the object. |

Response: `string`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/DELETE/v03/api/taxcards/{id})

## `GET /v03/api/taxcards/new`

**Factory method that creates a new object**

Response: `Taxcard`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/new)

## `POST /v03/api/taxcards/auto-set`

**Sets the automatic taxcard on for the given personal ID.
Method will make the request to tax authorities API immediately.
NOTE: In current implementation, the income type is always Salary (00024: Palkkaa).**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `personalId` | query | string |  | Personal ID for which the auto taxcard is set. If null, the current user is used: Must be a Worker account. |
| `taxPercentMinimum` | query | number |  | A Worker may request a minimum percent that is deducted even if the effective tax percent would be lower. This can be used if Worker knows that he/she will be earning more in the year than what was estimated when the taxcard was created. |
| `salaryDate` | query | string |  | The first salary date for which the taxcard is fetched. If null, uses today. |

Response: `Taxcard`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/auto-set)

## `POST /v03/api/taxcards/auto-refresh`

**Checks automatic taxcards from the Tax authorities API: If the taxcard has been checked within 2 days, does nothing.
If there are no changes, updates the LastChecked date only. If there are changes, creates a new taxcard container and returns it instead.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `taxcardIds` | query | string[] |  | List of taxcards ids that should be checked |
| `salaryDate` | query | string |  | The salary date for which the taxcard is fetched. If null, uses today. |
| `forceUpdate` | query | boolean |  | If true, skips the 2 day rule and always checks from the tax athorities API. |

Response: `TaxcardListItem[]`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/auto-refresh)

## `GET /v03/api/taxcards/file/{id}`

**Gets a file download (typically PDF or original image) for the taxcard.
Shows owned taxcards, taxcards that have the same personal ID as Worker account or that are copies of Worker account's shared card.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Identifier of the taxcard if owned. For a shared card or employer added card, may also be the URI of the Employer copy if the current user is the Worker account with the personal ID or owns the original copy. |

Response: File stream or 404 error if not found.

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/file/{id})

## `GET /v03/api/taxcards/preview/{id}`

**Gets a file preview (typically png) for the taxcard.
Shows owned taxcards, taxcards that have the same personal ID as Worker account or that are copies of Worker account's shared card.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Identifier of the taxcard if owned. For a shared card or employer added card, may also be the URI of the Employer copy if the current user is the Worker account with the personal ID or owns the original copy. |

Response: File stream or 404 error if not found.

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/preview/{id})

## `POST /v03/api/taxcards/reload-calcs/{id}`

**Reloads the income log based on the calculations.
Gets all the paid calculations that are relevant to this taxcard and lists them in the income log.
This method does not yet save the changes.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

Request body: `Taxcard` (required)

Response: The single object or null if none is found.

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/reload-calcs/{id})

## `POST /v03/api/taxcards/approve/{method}`

**Sets the approval for a taxcard.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `method` | path | TaxcardApprovalMethod | yes | Method of approval. AssureWaiting does not yet approve/reject. It just assures that there is a taxcard that can be viewed by the Employer. This information is stored in the database so that Worker can see who has looked at his/her taxcards (Data protetion / GDPR). |
| `ownedId` | query | string |  | Taxcard that will be approved / rejected. This an ID of the local copy (Employer / current account is owner). Either ownerId or sharedUri is required. |
| `sharedUri` | query | string |  | Taxcard that will be approved / rejected. This an URI of the Shared taxcard (Worker / owner is part of the URI). Either ownerId or sharedUri is required. |

Response: `Taxcard`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/approve/{method})

## `GET /v03/api/taxcards/my`

**Gets all the current taxcards for the current Worker account: 
The cards that the account has uploaded as well as the cards created by all Employers.
This method can only be run for a personal account (not for a Company account).**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `paymentDate` | query | string |  | Payment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change. |

Response: `WorkerCurrentTaxcards`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/my)

## `GET /v03/api/taxcards/issued`

**Performs an OData query to the search index. Returns
all**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `$search` | query | string |  |  |
| `$filter` | query | string |  | Specifies the logic to pull back a subset of records. |
| `$orderby` | query | string |  | Specifies the values used to sort the collection of entries. |
| `$select` | query | string |  | The $select system query option allows the clients to requests a limited set of properties for each entry. |
| `$top` | query | number |  | Specifies the subset of entries by count. |
| `$skip` | query | number |  | Specifies the count of entries to skip. |
| `$count` | query | boolean |  | Indicates whether or not to include a total entry count. |

Response: `PageResultOfTaxcardListItem`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/issued)

## `GET /v03/api/taxcards/employment/{id}`

**Gets all available / current taxcards for an employment.
By default, these taxcards are added by the Employer, but there may also be the latest taxcard added by the Worker.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Employent ID |
| `paymentDate` | query | string |  | Payment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change. |

Response: `WorkerCurrentTaxcards`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/employment/{id})

## `GET /v03/api/taxcards/shared-exists/{personalId}`

**For an employment relationship that is not yet created, allows checking if there is a shared taxcard.
Returns true if there is a shared taxcard available for the given Personal ID.
NOTE: There are unspecified and potentially changing restrictions on how many times this interface can be called to remove the risk of Phishing.
If such restriciton hits, the IsError property will be true. In this case, you should currently create the employment relation and fetch the taxcard info after that. 
We may later introduce a "Are you robot" type of interface to go around this (if necessary).**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `personalId` | path | string | yes | Personal ID of the Worker that will be added. |

Response: `SharedTaxcardExistsResult`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/shared-exists/{personalId})

## `GET /v03/api/taxcards/current`

**Gets a list of all non-terminated employments of the employer and resolves their current taxcards.
The current taxcards may be for the current year or for next year if the current date is either December or January.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `paymentDate` | query | string |  | Payment date for which the validity (current card in use) is calculated. If null, Next workday is used. This may be changed to next default payment date without that being a breaking change. |
| `$search` | query | string |  |  |
| `$filter` | query | string |  | Specifies the logic to pull back a subset of records. |
| `$orderby` | query | string |  | Specifies the values used to sort the collection of entries. |
| `$select` | query | string |  | The $select system query option allows the clients to requests a limited set of properties for each entry. |
| `$top` | query | number |  | Specifies the subset of entries by count. |
| `$skip` | query | number |  | Specifies the count of entries to skip. |
| `$count` | query | boolean |  | Indicates whether or not to include a total entry count. |

Response: `PageResultOfTaxcardListItem`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/current)

## `GET /v03/api/taxcards/current/{paymentDate}`

**Gets a list of all non-terminated employments of the employer and resolves their current taxcards for the
payment date in the path. The current taxcards may be for the current year or for next year if the current
date is either December or January.**

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `paymentDate` | path | string | yes | Payment date for which the validity (current card in use) is calculated. A value that is not a date is ignored, and the next workday is used. |
| `$search` | query | string |  |  |
| `$filter` | query | string |  | Specifies the logic to pull back a subset of records. |
| `$orderby` | query | string |  | Specifies the values used to sort the collection of entries. |
| `$select` | query | string |  | The $select system query option allows the clients to requests a limited set of properties for each entry. |
| `$top` | query | number |  | Specifies the subset of entries by count. |
| `$skip` | query | number |  | Specifies the count of entries to skip. |
| `$count` | query | boolean |  | Indicates whether or not to include a total entry count. |

Response: `PageResultOfTaxcardListItem`

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/GET/v03/api/taxcards/current/{paymentDate})

## `POST /v03/api/taxcards/file`

**Saves the tax card file for the user.
In the future returns parsed data from the file.**

Response: Tax card.

Try it: [interactive reference](https://code.salaxy.com/reference/rest-api.md#tag/taxcards/POST/v03/api/taxcards/file)
