cc nasazeni

README.md

@@ -1,8 +1,131 @@
 # iDoklad
 
-.NET API služba vytvořená přes CSBot Services Portal.
+.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.
 
-## Endpointy
+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.
 
-- GET /
-- GET /health
+## 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` | – |