JiriUhlir
124 lines
5.9 KiB
Markdown
124 lines
5.9 KiB
Markdown
# 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` | – |
|