Verteco Peppol Portál

Dokumentácia

API portálu

REST API pre integráciu externých systémov (účtovné a fakturačné aplikácie, ERP) s naším Peppol Access Pointom. Všetky požiadavky aj odpovede sú vo formáte JSON.

Základ

Base URL
https://peppol.verteco.digital/api/v1
Formát
application/json (request aj response)
Kódovanie
UTF-8

Chybové odpovede majú jednotný tvar. Validačné chyby pridávajú mapu fields.

// 4xx chyba
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// validačná chyba (400)
{ "error": "validation_failed", "message": "Some fields are invalid",
  "fields": { "ico": "IČO must be 8 digits" } }

Autentifikácia

Po register alebo login server nastaví httpOnly cookie portal_session (JWT, platnosť 7 dní). Prehliadač ju posiela automaticky na rovnakom origine. Pre server-to-server integráciu pripravujeme API tokeny (hlavička Authorization: Bearer …) — viď Pripravujeme.

POST/auth/register

Vytvorí účet a prihlási (nastaví cookie).

curl -X POST https://peppol.verteco.digital/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"email":"[email protected]","password":"tajneheslo123"}'

// 200 OK  (+ Set-Cookie: portal_session=…)
{ "id": "0b26b0da-…", "email": "[email protected]" }
POST/auth/login

Prihlásenie existujúceho účtu.

curl -X POST https://peppol.verteco.digital/api/v1/auth/login \
  -H 'Content-Type: application/json' -c cookies.txt \
  -d '{"email":"[email protected]","password":"tajneheslo123"}'
// 200 OK { "id": "…", "email": "[email protected]" }
// 401    { "error": "invalid_credentials", "message": "Invalid email or password" }
GET/auth/me

Vráti prihláseného používateľa (vyžaduje cookie).

curl https://peppol.verteco.digital/api/v1/auth/me -b cookies.txt
// 200 OK { "id": "…", "email": "[email protected]" }
// 401    { "error": "unauthorized", "message": "Authentication required" }
POST/auth/logout

Odhlásenie — zruší cookie. Vráti 204.

Firmy

Firmy (IČO / IČ DPH), ktoré používateľ spravuje. Prístup je viazaný na členstvo — vidíte len firmy, ktorých ste členom. Tvorca firmy sa stáva jej owner.

GET/companies

Zoznam firiem prihláseného používateľa.

POST/companies

Pridá novú firmu (vy sa stanete owner).

curl -X POST https://peppol.verteco.digital/api/v1/companies -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"ico":"53412834","dic":"SK2121358349",
       "legalName":"Verteco digital services, s. r. o.","registeredAddress":"Žilina"}'

// 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349",
  "legalName":"Verteco digital services, s. r. o.","registeredAddress":"Žilina",
  "peppolParticipantId":null,"status":"pending_verification",
  "role":"owner","createdAt":"2026-06-03T09:40:27Z" }
GET/companies/{id}

Detail firmy (musíte byť členom).

PUT/companies/{id}

Úprava firmy (rola owner alebo admin). IČO je nemenné.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/08dd… -b cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"ico":"53412834","dic":"SK2121358349","legalName":"Nový názov s. r. o."}'

Pole status firmy

pending_verification
po vytvorení, čaká na overenie / SMP registráciu
active
aktívna v Peppol sieti
suspended
pozastavená
archived
archivovaná

Pripravujeme — odosielanie a príjem faktúr

Nasledujúce endpointy sú jadrom integrácie a budú doplnené. Tvar sa môže ešte zmeniť.
  • POST/companies/{id}/peppol/register— Registrácia firmy do Peppol SMP — priradí peppolParticipantId.
  • POST/companies/{id}/documents/send— Odoslanie faktúry (UBL / Peppol BIS 3.0) cez Access Point príjemcovi.
  • GET/companies/{id}/documents— Zoznam prijatých a odoslaných dokladov firmy (filtre: direction, dátum).
  • GET/companies/{id}/documents/{docId}— Detail dokladu vrátane stavu doručenia a MLS.
  • POST/companies/{id}/webhooks— Registrácia webhooku — notifikácia vášho systému pri prijatej faktúre.

Pre tieto endpointy zavedieme API tokeny na server-to-server volania (bez cookie). Chcete skorý prístup k integrácii? Napíšte na [email protected].