---
title: "Sync invoices for a period"
method: POST
path: "/v1/sii/keys/{sii_key_id}/sync_invoices"
tags: ["SII Key"]
---

# Sync invoices for a period

`POST /v1/sii/keys/{sii_key_id}/sync_invoices`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/sii/keys/{sii_key_id}/sync_invoices`
- Auth: HTTP bearer

Triggers a synchronous sync of the company's electronic documents (DTEs) from
the SII for the tax periods in `[from, to]` (both `YYYY-MM`, inclusive). The
call authenticates with this key, walks each month in the range, and upserts
the resulting fiscal invoices.

The range is validated server-side: `from` and `to` must both match `YYYY-MM`,
`from` must be ≤ `to`, and the span must not exceed **24 months** — otherwise
the request fails with `422` (`sii/invalid-range`).

Because CxP payables ingestion relies on the company's own certificate, this
is how you backfill or refresh a company's SII inbox/outbox on demand. The call
is synchronous and can take a while for wide ranges.

## Path parameters

- `sii_key_id` string, uuid, required

## Parameters

- `#/paths/~1v1~1sii~1keys/get/parameters/0` (unresolved $ref)

## Request body

- SiiKeySyncInvoices
  - `from` string, required: First tax period to sync, in `YYYY-MM` format. Anything that does not match `YYYY-MM` is rejected with `422` (`sii/invalid-range`).
  - `to` string, required: Last tax period to sync (inclusive), in `YYYY-MM` format. Must be greater than or equal to `from`, and the span must not exceed 24 months — otherwise `422` (`sii/invalid-range`).

## Response `200`

The sync completed successfully.

- object
  - `status` 'synced', required: Always `synced` on success.
  - `from` string, required: First tax period synced (`YYYY-MM`).
  - `to` string, required: Last tax period synced (`YYYY-MM`).
  - `last_synced_at` string, date-time, nullable: The key's `last_synced_at` after the sync.

## Other responses

- `401`: Unauthorized. Two shapes are possible: - **Authorization failure** (empty body): the caller lacks `sii_keys_manage` and does not own the key. Auth is by key ownership or `sii_keys_manage` permission — the `company-id` header is not used to scope this operation. - **SII credentials rejected** (`{ "error": { "code": "sii/auth-failed" } }`): the SII rejected this key's stored credentials when the mapper ran the sync.
- `404`: SII key not found. Body: `{ "message": "Resource not found" }`.
- `409`: A sync is already in progress for this key upstream. Body: `{ "error": { "code": "sii/sync-in-progress" } }`.
- `422`: Invalid range — `from`/`to` not in `YYYY-MM`, `from` after `to`, or the span exceeds 24 months. Body: `{ "error": { "code": "sii/invalid-range" } }`.
- `429`: The SII WAF is throttling Cardda's crawler; the sync can't complete right now. Body: `{ "error": { "code": "sii/rate-limited" } }`.
- `500`: An unmapped internal error occurred while syncing. Body: `{ "error": { "code": "sii/unknown" } }`.
- `502`: The upstream extractor reported item-level failures (a partial sync: `sii/partial-failure`), or a mapped-but-opaque upstream SII error (`sii/upstream-error`). Body: `{ "error": { "code": "sii/upstream-error" } }`; on `sii/upstream-error` the additive `upstream_status` / `upstream_code` fields carry the real cause the extractor returned when the mapper captured it. (`sii/partial-failure` does not carry the additive fields.)
- `504`: The upstream SII call timed out. Body: `{ "error": { "code": "sii/upstream-timeout" } }`.

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) - [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/banking-api/revisions/ff1aeb3fda8b?raw)