# iDoklad

.NET 8 API služba pro server-to-server komunikaci s [iDoklad](https://www.idoklad.cz/) postavená nad
oficiálním **IdokladSdk** (.NET) verze **5.3.0** s OAuth2 *client credentials* flow.

Struktura projektu odpovídá sousední službě microsoft-365-service: konfigurace z prostředí,
přihlašovací údaje z hlaviček s fallbackem na proměnné prostředí, tenká service vrstva nad SDK,
controllery a samostatná dokumentace ve Swaggeru.

## Konfigurace (proměnné prostředí)

Aplikaci, ClientId, ClientSecret a ApplicationId získáte ve vývojářském portálu iDoklad. Tyto
hodnoty lze nastavit jako výchozí přes proměnné prostředí, nebo je předávat per-request v hlavičkách
(viz níže).

```env
# Výchozí přihlašovací údaje iDoklad (client credentials flow)
IDOKLAD_CLIENT_ID=
IDOKLAD_CLIENT_SECRET=
IDOKLAD_APPLICATION_ID=

# Volitelné
IDOKLAD_LANGUAGE=Cz                 # Cz | Sk | En (jazyk odpovědí iDoklad API)
IDOKLAD_REQUEST_TIMEOUT_SECONDS=100
IDOKLAD_API_URL=                    # vlastní URL API (jen pokud je nastavena i identity URL)
IDOKLAD_IDENTITY_URL=               # vlastní URL token endpointu Identity Serveru

# Obecné (sdílené napříč službami portálu)
APP_NAME=iDoklad Service
APP_VERSION=1.0.0
ROOT_PATH=                          # base path při běhu za reverzní proxy
```

> `IDOKLAD_API_URL` a `IDOKLAD_IDENTITY_URL` se použijí pouze pokud jsou nastavené **obě**; jinak
> SDK použije produkční URL iDokladu.

## Přihlašovací údaje v request hlavičkách

Citlivé proměnné (zejména **secret**) se **nepředávají v query stringu ani v těle** požadavku –
**vyžadují se v HTTP hlavičkách**. To je zohledněno i ve Swaggeru: u každého agendového endpointu
jsou tyto hlavičky zdokumentované jako parametry.

| Hlavička | Význam | Fallback (env) |
| --- | --- | --- |
| `X-ClientId` | iDoklad OAuth2 ClientId | `IDOKLAD_CLIENT_ID` |
| `X-ClientSecret` | iDoklad OAuth2 ClientSecret (**citlivé – jen přes TLS**) | `IDOKLAD_CLIENT_SECRET` |
| `X-ApplicationId` | iDoklad ApplicationId z vývojářského portálu | `IDOKLAD_APPLICATION_ID` |
| `X-Idoklad-Language` | volitelný jazyk odpovědí (`Cz`/`Sk`/`En`) | `IDOKLAD_LANGUAGE` |

Každá hodnota se nejprve čte z hlavičky a teprve pokud chybí, použije se výchozí proměnná prostředí.
Pokud po aplikaci fallbacku některý z údajů `ClientId`/`ClientSecret`/`ApplicationId` chybí, vrátí
služba `401` se seznamem chybějících hlaviček. Dekódované secrety se nikdy nelogují.

Příklad požadavku:

```http
GET /issued-invoices?page=1&pageSize=20
X-ClientId: <client id>
X-ClientSecret: <client secret>
X-ApplicationId: <application id>
```

## Swagger / OpenAPI

Interaktivní dokumentace běží na **`/docs`**, surový OpenAPI dokument na `/swagger/v1/swagger.json`.
Každý agendový endpoint má ve Swaggeru zdokumentované credential hlavičky i popisky operací.

## Pokryté agendy

Propojeno je **41 ze 45 clientů** SDK 5.3.0. Standardní agendy podporují stránkovaný `list`,
`detail`, `default` (kde to SDK umožňuje) a `create`/`update`/`delete`; číselníky jsou read-only.

Meta (bez credentials): `GET /health`, `GET /version`, `GET /status`.

| Tag | Agendy (cesty) |
| --- | --- |
| Account | `/account/agenda`, `/account/user` |
| Contacts | `/contacts` |
| IssuedInvoices | `/issued-invoices` (+ `/default`, `/{id}/copy`) |
| ReceivedInvoices | `/received-invoices` (+ `/default`) |
| SalesDocuments | `/proforma-invoices`, `/credit-notes`, `/sales-receipts`, `/sales-orders`, `/recurring-invoices`, `/issued-tax-documents`, `/issued-document-templates` |
| PurchaseAndCash | `/received-receipts`, `/cash-vouchers`, `/cash-registers` |
| Payments | `/bank-statements`, `/issued-payments`, `/received-payments` (+ `/fully-unpay/{invoiceId}`) |
| Catalog | `/price-list-items`, `/stock-movements`, `/tags` |
| Registers | `/registers/bank-accounts`, `/registers/vat-rates`, `/registers/numeric-sequences` |
| CodeLists | `/code-lists/banks`, `/countries`, `/currencies`, `/constant-symbols`, `/exchange-rates`, `/payment-options`, `/vat-codes`, `/vat-reverse-charge-codes`, `/sales-offices`, `/sales-pos-equipment` |
| Integration | `/webhooks`, `/notifications`, `/logs`, `/registered-sales`, `/unpaired-documents`, `/attachments`, `/system/code-books` |
| Statistics | `/statistics/*` (invoicing-for-period/year, quarter-summary, top-partners, agenda-summary, contact/{id}, debt-intervals, top-debtors, vat-payer-progress) |

Request/response těla odpovídají modelům iDoklad SDK (`*PostModel`, `*PatchModel`, `*GetModel`).
Serializace používá Newtonsoft.Json, aby se chování shodovalo s atributy modelů v SDK. Chyby z
iDoklad API se propagují jako `application/problem+json` s odpovídajícím HTTP statusem.

### Zatím nezapojené (na vyžádání)

Tyto klienty mají nestandardní/binární/facade charakter a nejsou zatím napojené:

- **MailClient** – odesílání dokladů e-mailem (facade nad typy dokladů).
- **ReportClient** – generování PDF reportů (binární výstup).
- **DocumentPaymentClient** – facade nad platbami (překrývá se s `issued-payments` / `received-payments`).
- **BatchClient** – dávkové operace.

Mimo to nejsou napojené pokročilé operace `Recount`, `*Batch` a `RecurringInvoice/NextIssueDates`.
`InboxClient` a `ReceivedDocumentsClient` v SDK 5.3.0 ještě nejsou (přibyly až po vydání).

## Lokální spuštění

```bash
dotnet run
```

Swagger UI otevřete na `http://localhost:<port>/docs`.

## Architektura

| Vrstva | Soubor(y) | Odpovídá v microsoft-365-service |
| --- | --- | --- |
| Konfigurace | `Configuration/IdokladSettings.cs` | `config.py` |
| Přihlašovací údaje z hlaviček | `Credentials/` | `credentials.py` |
| Klient SDK | `Client/DokladApiFactory.cs`, `Client/IdokladApiAccessor.cs` | `graph_client.py` |
| Service vrstva | `Services/*.cs` | `services.py` |
| Controllery | `Controllers/*.cs` | `routes.py` |
| Mapování chyb + Swagger | `Infrastructure/*.cs` | – |