iDoklad

.NET 8 API služba pro server-to-server komunikaci s iDoklad 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).

# 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:

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í

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

5.9 KiB Raw Blame History Unescape Escape