# PlugCharge Partner API

> Čítacie API pre účtovné a ERP systémy — partneri, doklady, relácie.

Rozhranie pre externé systémy, ktoré si potrebujú stiahnuť účtovné dáta operátora nabíjacích staníc (CPO).

**Len čítanie.** Žiadny endpoint nič nevytvára ani nemení. Doklady sa cez toto API vystaviť nedajú — číselný rad a finančná história sú nemenné.

**Rozsah dát nesie kľúč.** Každý API kľúč patrí jednému operátorovi a vracia výhradne jeho dáta. Tenant sa nikdy neurčuje parametrom požiadavky.

**Dva formáty.** Každý čítací endpoint vracia JSON alebo XML (`?format=xml`). XML je zrkadlom JSON — jednoduchý tvar bez menných priestorov; polia sú obalené do elementov s rovnakými názvami, zoznamy do opakovaného elementu.

**Ako začať:** kľúč (`client_id` + `client_secret`) si vytvorí správca operátora v CPO portáli (Nastavenia → Fakturácia → API kľúče). Secret sa zobrazí jedinýkrát.

## Autentifikácia

OAuth 2.0 client_credentials. Token platí 15 minút; kľúč sa overuje raz, potom sa používa token.

- [POST /oauth/token](https://api.plugcharge.eu/api/v1/docs#post-oauth-token): Vydanie prístupového tokenu (verejné)

Tok: OAuth 2.0 client_credentials na `POST https://api.plugcharge.eu/api/v1/oauth/token` → nepriehľadný Bearer token s platnosťou 15 minút. Rozsahy:
- `partners:read`: Čítanie partnerov
- `invoices:read`: Čítanie dokladov
- `sessions:read`: Čítanie relácií

## Partneri

Protistrany dokladov — zákazníci (firmy aj fyzické osoby) a operátori, ktorým bol vystavený doklad.

- [GET /partners](https://api.plugcharge.eu/api/v1/docs#get-partners): Zoznam partnerov (rozsah: partners:read)
- [GET /partners/{id}](https://api.plugcharge.eu/api/v1/docs#get-partners-id): Detail partnera (rozsah: partners:read)

## Doklady

Vystavené faktúry vrátane položiek a rekapitulácie DPH.

- [GET /invoices](https://api.plugcharge.eu/api/v1/docs#get-invoices): Zoznam dokladov (rozsah: invoices:read)
- [GET /invoices/{cislo}](https://api.plugcharge.eu/api/v1/docs#get-invoices-cislo): Detail dokladu s položkami a rekapituláciou DPH (rozsah: invoices:read)

## Relácie

Nabíjacie relácie — podklad pre nákladové strediská.

- [GET /sessions](https://api.plugcharge.eu/api/v1/docs#get-sessions): Zoznam nabíjacích relácií (rozsah: sessions:read)

## Dokumentácia

Verejné, bez autentifikácie.

- [GET /openapi.json](https://api.plugcharge.eu/api/v1/docs#get-openapi-json): Táto špecifikácia (OpenAPI 3.1, JSON) (verejné)
- [GET /docs](https://api.plugcharge.eu/api/v1/docs#get-docs): Dokumentácia pre ľudí (HTML) (verejné)
- [GET /llms.txt](https://api.plugcharge.eu/api/v1/docs#get-llms-txt): Index pre AI agentov (llms.txt) (verejné)

## Schémy

- [Chyba](https://api.plugcharge.eu/api/v1/docs#schema-Chyba) — polia: error, error_description
- [Token](https://api.plugcharge.eu/api/v1/docs#schema-Token) — polia: access_token, token_type, expires_in, scope
- [Partner](https://api.plugcharge.eu/api/v1/docs#schema-Partner): Protistrana dokladu. Vracajú sa LEN subjekty, ktorým reálne vznikol doklad — nie celá databáza zákazníkov. — polia: id, typ, nazov, ico, dic, ic_dph, ulica, psc, mesto, stat, email, posledny_doklad, pocet_dokladov
- [Doklad](https://api.plugcharge.eu/api/v1/docs#schema-Doklad): Vystavený doklad. Návrhy (`draft`) sa nikdy nevracajú. Sumy sú desatinné čísla s bodkou, bez ohľadu na locale. — polia: id, invoice_number, type, status, issue_date, due_date, paid_at, currency, amount, amount_paid, variable_symbol, vat_mode, period_from, period_to, customer_email, recipient_tenant, net_total, vat_total, rounding, supplier_name, supplier_ico, supplier_vat_id, customer_name, customer_ico, customer_vat_id, customer_address, cancelled_at, cancel_reason, pdf_key
- [DokladDetail](https://api.plugcharge.eu/api/v1/docs#schema-DokladDetail)
- [DokladPolozka](https://api.plugcharge.eu/api/v1/docs#schema-DokladPolozka) — polia: invoice_number, sort_order, item_kind, description, quantity, unit, unit_price, net_amount, vat_rate, vat_amount, gross_amount
- [RekapitulaciaDph](https://api.plugcharge.eu/api/v1/docs#schema-RekapitulaciaDph): Jeden riadok na dvojicu (doklad, sadzba DPH) — základ a daň za každú sadzbu zvlášť, tak ako ide do priznania. — polia: invoice_number, currency, vat_rate, net_amount, vat_amount, gross_amount
- [Relacia](https://api.plugcharge.eu/api/v1/docs#schema-Relacia): Nabíjacia relácia — podklad pre nákladové strediská. Bez identifikátora karty: RFID UID je autentifikačný kredenciál a do účtovného exportu nepatrí. — polia: id, status, started_at, ended_at, kwh, final_price, currency, lokalita, mesto, partner_id

## Odkazy

- [OpenAPI 3.1 (JSON)](https://api.plugcharge.eu/api/v1/openapi.json): strojovo čitateľná špecifikácia
- [Dokumentácia (HTML)](https://api.plugcharge.eu/api/v1/docs): pre ľudí, generovaná z tej istej špecifikácie
- Formát odpovedí: JSON predvolene, XML cez `?format=xml` (zrkadlo JSON, bez menných priestorov)
- API je len na čítanie — žiadny endpoint nič nevytvára ani nemení