JiriUhlir
132 lines
4.6 KiB
Markdown
132 lines
4.6 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í)
|
||
|
||
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` | – |
|