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

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).

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

GET /issued-invoices?page=1&pageSize=20
X-ClientId: <client id>
X-ClientSecret: <client secret>
X-ApplicationId: <application id>

API

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í

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	–