# 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í)

Aplikace, 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 hlavičky vtypu `X-...` 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>
```

## API

```http
GET    /health
GET    /version
GET    /status

# Account
GET    /account/agenda
GET    /account/user

# Contacts
GET    /contacts?page=1&pageSize=20
GET    /contacts/default
GET    /contacts/{id}
POST   /contacts
PATCH  /contacts
DELETE /contacts/{id}

# Issued invoices (vydané faktury)
GET    /issued-invoices?page=1&pageSize=20
GET    /issued-invoices/default
GET    /issued-invoices/{id}
POST   /issued-invoices
PATCH  /issued-invoices
POST   /issued-invoices/{id}/copy
DELETE /issued-invoices/{id}

# Received invoices (přijaté faktury)
GET    /received-invoices?page=1&pageSize=20
GET    /received-invoices/default
GET    /received-invoices/{id}
POST   /received-invoices
PATCH  /received-invoices
DELETE /received-invoices/{id}

# Registry
GET    /registers/bank-accounts?page=1&pageSize=20
GET    /registers/bank-accounts/{id}
POST   /registers/bank-accounts
PATCH  /registers/bank-accounts
DELETE /registers/bank-accounts/{id}
GET    /registers/vat-rates?page=1&pageSize=20
GET    /registers/vat-rates/{id}
GET    /registers/numeric-sequences?page=1&pageSize=20
```

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.

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

```bash
dotnet run
```

Swagger UI je na `/swagger`, OpenAPI dokument na `/swagger/v1/swagger.json`.

## 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` | – |