# Accounting data

After a salary is paid, the customer's bookkeeping needs the entries: which accounts, which amounts, debit or credit. Salaxy returns them as one **AccountingData** object, posted through an **accounting target** (a chart of accounts and its posting rules). Your accounting software imports it.
Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Four boxes from left to right. A paid salary calculation in Salaxy. The accounting target, whose chart of accounts and posting rules map each salary component to an account. The AccountingData object with ledger accounts and entries. Your accounting system, which pulls the object with a GET request. Salaxy applies the accounting target when you read the data, not when the salary is paid. (Purple: Salaxy. You pull the same AccountingData object whichever way you select the salaries.)*

## Which fits you?

All four options return the same object. They differ in what they select and in how stable the figures are.

### Monthly pull (recommended)

Fits an accounting system that imports once per period.

**Monthly pull: how it works:**
Fetch the period once a month. A good day is the 5th of the next month: the Incomes Register report is due then, so most problems are already resolved.

```http
GET /v03/api/reports/accounting/2026-05-01?target=default&periodType=month HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>
```

All query parameters are optional:

| Parameter | Default | Meaning |
|---|---|---|
| `target` | your default target | Accounting target id. `default` or no value uses the default target of the account. |
| `periodType` | `month` | `month`, `quarter`, `year` or `custom`. Any date inside the period returns the whole period. |
| `endDate` | none | End of the period. Required for `custom`, ignored otherwise. |
| `periodDateKind` | the account's setting, normally `paidAtDate` | The date that decides whether a calculation is in the period: `paidAtDate`, `salaryDate`, `workDate`, `workDateStart` or `workDateEnd`. The same calculation can fall in different months under `paidAtDate` and `salaryDate`, so choose deliberately. |
| `minStatus` | `paymentSucceeded` | Lowest calculation status to include. The default reports paid calculations only. |
| `createdFrom` | none | Only calculations created on or after this date. Useful for picking up late additions to a period you have already fetched. |

Each call recomputes the period. A salary paid late therefore changes the figures of a month you have already imported.

### Saved monthly report

Fits an import that must reconcile: the same month returns the same figures until the report is written again.

**Saved monthly report: how it works:**
Salaxy writes one accounting report per customer company per month, on the 4th business day (see [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md)). List the saved reports as files, then fetch one by its id.

```http
GET /v03/api/files?$filter=entityType eq 'MonthlyReport.MonthlyAccounting'&$orderby=logicalDate desc&$top=1 HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>
```

```json
{
  "items": [
    {
      "id": "b7c4e3f1-2a9d-4e58-9f0b-6c1d8a2e5f34",
      "entityType": "MonthlyReport.MonthlyAccounting",
      "logicalDate": "2026-05-01",
      "createdAt": "2026-06-04T02:14:33Z",
      "updatedAt": "2026-06-04T02:14:33Z",
      "grossSalary": 12400.00,
      "payment": 15380.42,
      "data": {
        "calculationCount": 8,
        "workerCount": 3,
        "officialId": "1234567-8"
      }
    }
  ]
}
```

Then fetch the report with the `id`:

```http
GET /v03/api/reports/accounting/b7c4e3f1-2a9d-4e58-9f0b-6c1d8a2e5f34?target=default HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>
```

- **Filter on `entityType`.** The monthly-report files also hold the PDF and spreadsheet renderings of other reports.
- **Order by `logicalDate`.** It is the month the report covers. The default order, `updatedAt desc`, puts a regenerated older month first.
- **Name the month** with `and logicalDate eq 2026-05-01` instead of `$top=1`. A `$top` suppresses `nextPageLink`.
- **Regenerate** a month's saved report on demand with `POST /v03/api/reports/accounting/{refDate}/close`. It writes the report and returns its id as a string.

Two things surprise people:

- **Closing does not lock the period.** It rewrites the stored report and re-renders the PDF and spreadsheet. Calculations paid later still change what a period fetch returns. It is a write, so never call it to read.
- **The saved data is the calculations, not the postings.** The account numbers are applied when you read, with the `target` you pass. Pass the same target every time, or the same id returns the same figures on different accounts.

The saved report uses the account's own `periodDateKind` setting. When that setting is anything other than `paidAtDate`, a salary paid after the 4th business day of the next month is missing from the saved report of its month. A period fetch for that month returns it. Regenerate with `close` if you rely on saved reports.

### By calculation

Fits a system that must book every payment on the day it is paid.

**By calculation: how it works:**
```http
GET /v03/api/reports/accounting?calculationIds=ceabf85e-6d1e-49b4-a738-a7edf1208d82,efe73c17-c00f-4937-b9c5-72b6ce6bae6e&target=default HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>
```

The endpoint takes `calculationIds` and `target` only. Poll for newly paid calculations, or react to a payment channel trigger, then fetch their ids.

Per-calculation posting is hard to get right. The [holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md) is a monthly balance, not a per-payment figure, so you still need a monthly pull for it. You also need to know whether the calculation is the only one for that worker in the period. Talk to Salaxy support before you choose this method in production.

### By invoice (payment channel owners)

Fits a partner that owns a payment channel and tracks invoices instead of calculations. It also fits single late corrections after the monthly pull.

**By invoice: how it works:**
These routes use the access token of your **technical account**, not a token for one customer. One token reaches every customer served by the channel. See [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md).

```http
GET /v03/api/payment-channel/{channel}/{invoiceId}/accounting?target=default HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>
```

Several invoices in one call: `GET /v03/api/payment-channel/{channel}/accounting?ids=<id1>,<id2>&target=default`.

- **Net-salary invoices only.** Any other invoice type returns `404`, not an empty report.
- **One employer per call.** Ids from more than one employer fail with `400`. Group the ids by employer.
- **Optional attachments.** `GET /v03/api/payment-channel/{channel}/{id}/salarySlip?isSensitive=true` returns the salary slip PDF. `isSensitive=true` hides the worker's personal identity code. The invoice PDF is at `.../{id}/content`.

## The AccountingData object

```text
AccountingData
  ledgerAccounts[]      one per account number: accountNumber, accountName, accountGrouping, saldo
    entries[]           id, entryDate, description, isDebit, amount, vatPercent, vatAmount, vatRate,
                        accountNumber, accountName, accountGrouping, dimension
  target, employer, contact, period, summary, officialId, format
```

A shortened sample:

```json
{
  "ledgerAccounts": [
    {
      "accountNumber": "2921",
      "accountName": "Ennakonpidätysvelka",
      "accountGrouping": null,
      "saldo": -706.68,
      "entries": [
        {
          "id": null,
          "entryDate": "2025-10-08",
          "description": "Ennakonpidätykset",
          "isDebit": false,
          "amount": 706.68,
          "vatPercent": null,
          "vatAmount": null,
          "vatRate": "undefined",
          "accountNumber": "2921",
          "accountName": "Ennakonpidätysvelka",
          "accountGrouping": null,
          "dimension": {
            "calculationId": "efe73c17-c00f-4937-b9c5-72b6ce6bae6e",
            "calculationTitle": "Test Worker 2025-10-09"
          }
        }
      ]
    }
  ],
  "period": { "start": "2025-10-01", "end": "2025-10-31" },
  "summary": { "calculationCount": 2, "workerCount": 2 },
  "officialId": "1234567-8"
}
```

- **`accountGrouping`** names the entries that are posted together as one accounting row.
- **`dimension`** carries the cost-accounting values of the row. See [Dimensions](https://code.salaxy.com/integration/dimensions.md).
- **An entry has no income type code.** It identifies itself by account number, name and a Finnish `description`. Where two figures share an account pair, only `description` tells them apart.
- **There is no CSV endpoint.** The CSV and Excel files of the embedded UI are built in the browser from this same object. Build your own file from the JSON.

## The accounting target

A target defines how a salary result becomes entries. It holds a chart of accounts and a posting ruleset that decides, per income type and per kind of salary, the account, debit or credit, and the grouping. Built-in targets cover the common charts of accounts and accounting software. A custom target is made together with Salaxy support; creating one is not part of the integration. See [Accounting models](https://code.salaxy.com/integration/accounting-models.md) for how a target is assigned to a customer.

| Method | Path | Purpose |
|---|---|---|
| GET | `/v03/api/accounting-target` | List the targets (OData). Identity and status only: **no ruleset**. |
| GET | `/v03/api/accounting-target/{id}` | One target in full, with `ruleSet`. Use it to see how anything is posted. |

In `ruleSet`, `rows` hold the posting logic and `accounts` the chart of accounts. A row matches by `entryCodeGroup` and `entryCode`, and `isIncluded` says whether it posts. A row has no account number: its `debitId` and `creditId` point into `ruleSet.accounts`.

- **An unknown `target` id does not fail.** The request falls back to the built-in default target and returns `200` with entries on other accounts than you asked for. If the accounts look wrong, check the id first.
- **A target edit is retroactive.** Postings are applied on read, so an old month returns the new accounts at the next fetch. No response proves what was booked at the time. Keep your own record at import.
- **Archived documents are not retroactive.** The PDF and spreadsheet of the monthly cycle are rendered with the default target and keep their account numbers until you call `close` again.

## Holiday pay debt is not in here

`summary.holidayCalc` is always `null` in every response on this page, with no error. Holiday pay debt has its own endpoints: see [Holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md).

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| GET | `/v03/api/reports/accounting/{refDate}` | Period report |
| GET | `/v03/api/reports/accounting/{id}` | Saved report by id |
| GET | `/v03/api/reports/accounting?calculationIds=` | By calculation ids |
| POST | `/v03/api/reports/accounting/{refDate}/close` | Regenerate the saved report |
| GET | `/v03/api/files` | List saved monthly reports |
| GET | `/v03/api/payment-channel/{channel}/{id}/accounting` | One invoice (channel owner) |
| GET | `/v03/api/payment-channel/{channel}/accounting?ids=` | Several invoices (channel owner) |

The accounting data endpoints are **v03 only**. In the REST reference, see [Reports](https://code.salaxy.com/reference/rest/reports.md), [Accounting target](https://code.salaxy.com/reference/rest/accountingtarget.md) and [Payment channel](https://code.salaxy.com/reference/rest/paymentchannel.md). In `@salaxy/core`: `Reports.getAccountingDataForPeriod()` and `Reports.getAccountingDataForCalculationIds()`.

## Test it

1. Pay a test salary as in [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). Test data is described in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md).
2. Call the period report for that month with `target=default`. Expect `200` and your calculation in `summary.calculationCount`.
3. Fetch the target with `GET /v03/api/accounting-target/{id}` and check the accounts against your own chart.
4. In test, a saved report is written on the 4th business day of the next month. To get one sooner, call `close` for the month and fetch the report with the id it returns. See [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md).

## Checklist

- Choose one pull option per customer and keep the `periodDateKind` the same for every import.
- Pass the same `target` every time, and treat a `200` with unexpected accounts as a wrong target id.
- Never read holiday pay debt from `summary.holidayCalc`.
- Keep your own record of what you booked. Edits to a target change past months.
- For channel owner routes, use the technical account token and group invoices by employer.

**Next:** [Holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md)
