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 /docs/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	–