> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MAI55

> Report account incomes, balances, and outstanding debts to the Lithuanian tax authority.

MAI55 is the Lithuanian State Tax Inspectorate (VMI) report on the accounts, incomes and debts your clients hold with you. It covers three sub-reports, each reported once a year for a calendar year. This connector exposes a **REST API**: you push persons into a submission for one sub-report and reporting year, then hand it off to be reported to the tax authority.

## Sub-reports

A submission carries exactly one sub-report, chosen with `type` when you open it:

| Sub-report | What it reports                                   | Attached to each person                 |
| ---------- | ------------------------------------------------- | --------------------------------------- |
| `SIPL`     | Income paid into accounts over the reporting year | `accounts`, each with its `income`      |
| `SLIK`     | Account balances at the end of the reporting year | `accounts`, each with its `balance`     |
| `SKIS`     | Outstanding debt agreements                       | `debts`, each with its remaining amount |

Each sub-report has its own push endpoints. Rounds for different sub-reports are independent and may run at once.

## The person is the unit of reporting

Whichever sub-report you are reporting, you push **persons**, keyed by your own `clientPersonId`. Each person becomes exactly one reportable entry, with every account or debt they hold with you attached to it. That id must be unique within the submission, and it is how you address the person on update and delete.

`PUT` replaces a person rather than merging into them. Send all their accounts or debts every time, not just the ones that changed.

## How it works

<Steps>
  <Step title="Open a submission">
    `POST /reports/mai55/v1/submissions` with the sub-report `type` and reporting year. You get back a `submissionId` that scopes every subsequent call. Optionally include a `webhookUrl` to be notified when the submission finishes processing.
  </Step>

  <Step title="Push persons">
    `POST /reports/mai55/v1/submissions/{submissionId}/{sipl|slik|skis}/persons` with a batch of persons. Push to the path matching the submission's sub-report; pushing to another one is rejected.
  </Step>

  <Step title="Submit">
    `POST /reports/mai55/v1/submissions/{submissionId}:submit` starts report generation and submission to the tax authority. After this call the submission is no longer editable.
  </Step>

  <Step title="Track progress and fix errors">
    Poll `GET .../status` for the high-level state, or `GET .../report` for reported-versus-pending counts of persons and messages. `GET .../errors` lists the persons with unresolved tax authority validation errors, with the error codes to fix.
  </Step>
</Steps>

While a submission is still a draft you can [delete it](/regulatory/rrc/api/mai55/submissions/delete-submission) along with every person pushed under it. To change anything you have already reported, open a new submission for the same sub-report and year.

## Corrections

Opening a submission for a sub-report and year that has already been reported returns `kind: CORRECTION`. A correction works exactly like the first submission, using the same endpoints and keyed by `clientPersonId`, but each call now acts on what the tax authority already holds:

* **`POST /persons`** adds persons the tax authority has not seen. One it already holds is rejected, and must be amended with `PUT` or withdrawn with `DELETE`.
* **`PUT /persons/{clientPersonId}`** amends an already-reported person, replacing their entry whole. Amending a person the tax authority has never seen is rejected.
* **`DELETE /persons/{clientPersonId}`** withdraws the person's entry at the tax authority, with every account or debt it carried. A person it has never seen returns `404`.

Like any submission, a correction only reaches the tax authority once you submit it. You can open as many rounds for a sub-report and year as you need, but only one at a time: opening a submission while an earlier round for the same pair is still being processed returns `409`.

## Pushing persons

A batch holds up to 10,000 persons. A batch is not all-or-nothing. Persons that fail are reported individually and the rest of the batch is still saved, so a `207` response means some persons were rejected while the others were stored. Send the optional `Idempotency-Key` header to make a retried batch safe.

Two rules are worth knowing before you push:

* An account of type `CURRENT_ACCOUNT` must carry an IBAN as its `accountNumber`; any other account type can carry a different identifier.
* Under `SIPL`, only persons whose income across all their accounts reaches 15,000 EUR are reportable. The total is summed from the accounts rather than sent, as is the `SKIS` total debt.

## Submission status

`status` on a submission moves through:

| Status            | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `DRAFT`           | Open for pushing persons; not yet submitted.                     |
| `PROCESSING`      | Submitted; being reported to the tax authority.                  |
| `ACTION_REQUIRED` | Some persons were rejected and need correcting and re-reporting. |
| `REPORTED`        | Accepted by the tax authority.                                   |
| `FAILED`          | Reporting failed.                                                |

## Webhook

Instead of polling for status, pass a `webhookUrl` when you [open a submission](/regulatory/rrc/api/mai55/submissions/create-submission). Once the submission finishes processing, the connector calls it with a POST carrying a JSON body:

```json theme={null}
{"submissionId": "<submission id>", "status": "ACCEPTED"}
```

`status` is the tax authority's validation result for the submission: `ACCEPTED` or `REJECTED`. Calls originate from the following IP addresses; whitelist them to receive the webhook.

| Environment | IP addresses                                                |
| ----------- | ----------------------------------------------------------- |
| Test        | 34.78.184.35, 35.195.129.148, 34.76.178.43, 88.119.208.29   |
| Production  | 130.211.66.226, 35.205.15.220, 104.155.69.28, 88.119.208.29 |

## Authentication

All endpoints require a bearer JWT obtained via the OAuth2 `client_credentials` grant. See [Authentication](/regulatory/rrc/authentication). Each sub-report is authorised separately, so your client is granted access to `SIPL`, `SLIK` and `SKIS` individually. Listing submissions returns those of every sub-report you hold a permission for.

## API Reference

Explore the full API specification in the [Swagger documentation](https://api.rrc.finventi.com/reports/mai55/swagger-ui/index.html).

<Info>
  **IP Whitelisting Required:** Before you can access the Swagger documentation, your IP address must be whitelisted. Contact us to register your IP addresses.
</Info>

## Resources

<CardGroup cols={2}>
  <Card title="Submissions" icon="folder-plus" href="/regulatory/rrc/api/mai55/submissions/create-submission">
    Open a reporting batch, submit it, and track its status
  </Card>

  <Card title="SIPL" icon="money-bill-transfer" href="/regulatory/rrc/api/mai55/sipl/push-sipl-persons">
    Report the income you paid into your clients' accounts
  </Card>

  <Card title="SLIK" icon="building-columns" href="/regulatory/rrc/api/mai55/slik/push-slik-persons">
    Report year-end balances on your clients' accounts
  </Card>

  <Card title="SKIS" icon="file-invoice-dollar" href="/regulatory/rrc/api/mai55/skis/push-skis-persons">
    Report the debts your clients still owe you
  </Card>
</CardGroup>