PlugCharge Partner API — dokumentácia

Čí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.

Ako začať

V CPO portáli (Nastavenia → Fakturácia → API kľúče) vytvorte kľúč a zvoľte rozsahy. Zobrazí sa client_id a client_secret — secret jedinýkrát.
Vymeňte kľúč za token (platí 15 minút):

curl -X POST https://api.plugcharge.eu/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"pc_…","client_secret":"…"}'

Volajte API s tokenom. Pre XML pridajte ?format=xml:

curl https://api.plugcharge.eu/api/v1/invoices?od=2026-01-01 \
  -H "Authorization: Bearer <access_token>"

curl "https://api.plugcharge.eu/api/v1/invoices/PLG202500042?format=xml" \
  -H "Authorization: Bearer <access_token>"

Po vypršaní tokenu vráti API 401 invalid_token — vyžiadajte si nový. Kľúč sa dá kedykoľvek odvolať v portáli; odvolanie platí okamžite.

Autentifikácia

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

POST `/oauth/token` #

Vydanie prístupového tokenu

OAuth 2.0 client_credentials. Telo môže byť application/json alebo application/x-www-form-urlencoded. Neznámy kľúč aj zlý secret vracajú tú istú odpoveď 401 — kľúče sa nedajú vyčítavať. Limit 20 pokusov za 5 minút.

Verejné — bez autentifikácie.

Telo požiadavky

Obsah: application/json, application/x-www-form-urlencoded

Pole	Typ	Popis
`grant_type` *	string `client_credentials`
`client_id` *	string	napr. `pc_9f2b…`
`client_secret` *	string

Odpovede

`200`	Token. Odpoveď má `Cache-Control: no-store`. `application/json` → Token
`400`	`unsupported_grant_type` `application/json` → Chyba
`401`	`invalid_client` `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

Partneri

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

GET `/partners` #

Zoznam partnerov

Protistrany dokladov operátora, zoradené podľa posledného dokladu. Na inkrementálny sync použite ?od= — vráti len partnerov s dokladom od daného dátumu.

Vyžaduje Authorization: Bearer s rozsahom partners:read.

Parametre

Názov	Kde		Typ	Popis
`od`	query	voliteľný	string (date)	Len partneri s dokladom od tohto dátumu (YYYY-MM-DD).
`typ`	query	voliteľný	string `firma` `osoba` `cpo`
`page`	query	voliteľný	integer = 1
`limit`	query	voliteľný	integer = 100
`format`	query	voliteľný	string `json` `xml`	Formát odpovede. `xml` má prednosť pred hlavičkou `Accept`. Predvolené `json`.

Odpovede

`200`	Zoznam partnerov. `application/json` → pole Partner `application/xml` → pole Partner
`401`	Chýbajúci, neplatný, expirovaný alebo odvolaný token. `application/json` → Chyba
`403`	Kľúč nemá potrebný rozsah (`insufficient_scope`). `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

GET `/partners/{id}` #

Detail partnera

Vyžaduje Authorization: Bearer s rozsahom partners:read.

Parametre

Názov	Kde		Typ	Popis
`id`	path	povinný	string	Identifikátor vrátane prefixu, napr. `u:3f9c…` alebo `t:8a1d…`.
`format`	query	voliteľný	string `json` `xml`	Formát odpovede. `xml` má prednosť pred hlavičkou `Accept`. Predvolené `json`.

Odpovede

`200`	Partner. `application/json` → Partner `application/xml` → Partner
`401`	Chýbajúci, neplatný, expirovaný alebo odvolaný token. `application/json` → Chyba
`403`	Kľúč nemá potrebný rozsah (`insufficient_scope`). `application/json` → Chyba
`404`	Partner neexistuje alebo nepatrí tomuto operátorovi. Odpoveď je rovnaká v oboch prípadoch. `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

Doklady

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

GET `/invoices` #

Zoznam dokladov

Vystavené doklady operátora. Obdobie sa filtruje podľa dátumu vystavenia. Zoznam neobsahuje položky — tie vracia detail.

Vyžaduje Authorization: Bearer s rozsahom invoices:read.

Parametre

Názov	Kde		Typ	Popis
`od`	query	voliteľný	string (date)	Od dátumu vystavenia (YYYY-MM-DD).
`do`	query	voliteľný	string (date)	Do dátumu vrátane (YYYY-MM-DD).
`stav`	query	voliteľný	string `issued` `paid` `overdue` `cancelled`
`typ`	query	voliteľný	string	`charging` \| `pausal` \| `platform_fee` \| …
`limit`	query	voliteľný	integer = 100
`format`	query	voliteľný	string `json` `xml`	Formát odpovede. `xml` má prednosť pred hlavičkou `Accept`. Predvolené `json`.

Odpovede

`200`	Zoznam dokladov. `application/json` → pole Doklad `application/xml` → pole Doklad
`401`	Chýbajúci, neplatný, expirovaný alebo odvolaný token. `application/json` → Chyba
`403`	Kľúč nemá potrebný rozsah (`insufficient_scope`). `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

GET `/invoices/{cislo}` #

Detail dokladu s položkami a rekapituláciou DPH

Adresuje sa ČÍSLOM dokladu, nie interným UUID — číslo je to, čo je na doklade a čo ERP pozná.

Vyžaduje Authorization: Bearer s rozsahom invoices:read.

Parametre

Názov	Kde		Typ	Popis
`cislo`	path	povinný	string	napr. `PLG202500042`
`format`	query	voliteľný	string `json` `xml`	Formát odpovede. `xml` má prednosť pred hlavičkou `Accept`. Predvolené `json`.

Odpovede

`200`	Doklad s položkami. `application/json` → DokladDetail `application/xml` → DokladDetail
`401`	Chýbajúci, neplatný, expirovaný alebo odvolaný token. `application/json` → Chyba
`403`	Kľúč nemá potrebný rozsah (`insufficient_scope`). `application/json` → Chyba
`404`	Doklad neexistuje alebo nepatrí tomuto operátorovi. `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

Relácie

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

GET `/sessions` #

Zoznam nabíjacích relácií

Vyžaduje Authorization: Bearer s rozsahom sessions:read.

Parametre

Názov	Kde		Typ	Popis
`od`	query	voliteľný	string (date)	Od začiatku relácie (YYYY-MM-DD).
`do`	query	voliteľný	string (date)	Do dátumu vrátane (YYYY-MM-DD).
`page`	query	voliteľný	integer = 1
`limit`	query	voliteľný	integer = 100
`format`	query	voliteľný	string `json` `xml`	Formát odpovede. `xml` má prednosť pred hlavičkou `Accept`. Predvolené `json`.

Odpovede

`200`	Zoznam relácií. `application/json` → pole Relacia `application/xml` → pole Relacia
`401`	Chýbajúci, neplatný, expirovaný alebo odvolaný token. `application/json` → Chyba
`403`	Kľúč nemá potrebný rozsah (`insufficient_scope`). `application/json` → Chyba
`429`	Prekročený limit požiadaviek (120/min na kľúč). `application/json` → Chyba

Dokumentácia

Verejné, bez autentifikácie.

GET `/openapi.json` #

Táto špecifikácia (OpenAPI 3.1, JSON)

Verejné — bez autentifikácie.

Odpovede

200 OpenAPI dokument.

GET `/docs` #

Dokumentácia pre ľudí (HTML)

Verejné — bez autentifikácie.

Odpovede

200 HTML stránka generovaná z tejto špecifikácie.

GET `/llms.txt` #

Index pre AI agentov (llms.txt)

Verejné — bez autentifikácie.

Odpovede

200 Textový index podľa konvencie llms.txt.

Schémy

`Chyba`#

Pole	Typ	Popis
`error` *	string	Kód chyby podľa RFC 6749 §5.2 alebo `not_found` / `server_error`.
`error_description`	string

`Token`#

Pole	Typ	Popis
`access_token` *	string
`token_type` *	string `Bearer`
`expires_in` *	integer	Sekundy. Aktuálne 900 (15 minút).
`scope` *	string	Udelené rozsahy oddelené medzerou.

`Partner`#

Protistrana dokladu. Vracajú sa LEN subjekty, ktorým reálne vznikol doklad — nie celá databáza zákazníkov.

Pole	Typ	Popis
`id` *	string	Stabilný identifikátor s prefixom zdroja: `u:<uuid>` zákazník, `t:<uuid>` operátor (CPO). napr. `u:3f9c1e2a-…`
`typ` *	string `firma` `osoba` `cpo`
`nazov`	string \| null	Názov firmy, alebo meno a priezvisko pri fyzickej osobe.
`ico`	string \| null
`dic`	string \| null	DIČ — daňové identifikačné číslo (má ho každý daňový subjekt).
`ic_dph`	string \| null	IČ DPH — identifikátor platcu DPH (len platca).
`ulica`	string \| null
`psc`	string \| null
`mesto`	string \| null
`stat`	string \| null	ISO 3166-1 alpha-2, napr. `SK`.
`email`	string \| null	Pri operátorovi (`typ = cpo`) je null.
`posledny_doklad` *	string (date-time)	Dátum posledného dokladu — kotva pre inkrementálny sync (`?od=`).
`pocet_dokladov` *	integer

`Doklad`#

Vystavený doklad. Návrhy (draft) sa nikdy nevracajú. Sumy sú desatinné čísla s bodkou, bez ohľadu na locale.

Pole	Typ	Popis
`id` *	string (uuid)
`invoice_number` *	string	Číslo dokladu — unikátne v rámci fakturujúceho subjektu. Toto je kľúč pre `GET /invoices/{cislo}`.
`type` *	string	`charging` \| `pausal` \| `platform_fee` \| …
`status` *	string `issued` `paid` `overdue` `cancelled`	`overdue` je odvodený: `issued` po dátume splatnosti.
`issue_date`	string \| null (date)
`due_date`	string \| null (date)
`paid_at`	string \| null (date-time)
`currency` *	string	napr. `EUR`
`amount` *	number	Celková suma s DPH.
`amount_paid` *	number
`variable_symbol`	string \| null
`vat_mode`	string \| null
`period_from`	string \| null (date)
`period_to`	string \| null (date)
`customer_email`	string \| null
`recipient_tenant`	string \| null	Názov operátora, ak je odberateľom CPO.
`net_total`	number \| null
`vat_total`	number \| null
`rounding`	number \| null
`supplier_name`	string \| null
`supplier_ico`	string \| null
`supplier_vat_id`	string \| null
`customer_name`	string \| null
`customer_ico`	string \| null
`customer_vat_id`	string \| null	IČ DPH odberateľa platné K DÁTUMU VYSTAVENIA (z registra DPH registrácií).
`customer_address`	string \| null
`cancelled_at`	string \| null (date)
`cancel_reason`	string \| null
`pdf_key`	string \| null	Interný kľúč PDF; samotné PDF sa cez toto API nevracia.

`DokladDetail`#

Rozširuje Doklad, object

Pole	Typ	Popis
`polozky` *	pole DokladPolozka
`rekapitulacia_dph` *	pole RekapitulaciaDph

`DokladPolozka`#

Pole	Typ	Popis
`invoice_number` *	string
`sort_order` *	integer
`item_kind`	string
`description` *	string
`quantity` *	number
`unit`	string \| null
`unit_price` *	number
`net_amount` *	number
`vat_rate` *	number	Sadzba v percentách, napr. `23`.
`vat_amount` *	number
`gross_amount` *	number

`RekapitulaciaDph`#

Jeden riadok na dvojicu (doklad, sadzba DPH) — základ a daň za každú sadzbu zvlášť, tak ako ide do priznania.

Pole	Typ	Popis
`invoice_number` *	string
`currency` *	string
`vat_rate` *	number
`net_amount` *	number
`vat_amount` *	number
`gross_amount` *	number

`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í.

Pole	Typ	Popis
`id` *	string (uuid)
`status` *	string
`started_at` *	string (date-time)
`ended_at`	string \| null (date-time)
`kwh`	number \| null
`final_price`	number \| null
`currency`	string \| null
`lokalita`	string \| null	Názov lokality (stanice).
`mesto`	string \| null
`partner_id`	string \| null	Odkaz na partnera (`u:<uuid>`), ak je relácia viazaná na zákazníka.

Ako začať

Autentifikácia

POST /oauth/token #

Telo požiadavky

Odpovede

Partneri

GET /partners #

Parametre

Odpovede

GET /partners/{id} #

Parametre

Odpovede

Doklady

GET /invoices #

Parametre

Odpovede

GET /invoices/{cislo} #

Parametre

Odpovede

Relácie

GET /sessions #

Parametre

Odpovede

Dokumentácia

GET /openapi.json #

Odpovede

GET /docs #

Odpovede

GET /llms.txt #

Odpovede

Schémy

Chyba#

Token#

Partner#

Doklad#

DokladDetail#

DokladPolozka#

RekapitulaciaDph#

Relacia#

POST `/oauth/token` #

GET `/partners` #

GET `/partners/{id}` #

GET `/invoices` #

GET `/invoices/{cislo}` #

GET `/sessions` #

GET `/openapi.json` #

GET `/docs` #

GET `/llms.txt` #

`Chyba`#

`Token`#

`Partner`#

`Doklad`#

`DokladDetail`#

`DokladPolozka`#

`RekapitulaciaDph`#

`Relacia`#