Rováš poskytuje REST API, cez ktoré partneri, doplnky a aplikácie môžu zakladať účty, podávať pracovné výkazy, čítať Merity a napojiť sa na produkty NeoFund (napríklad Civic).
| Prostredie | Základná URL |
|---|---|
| Produkcia | https://rovas.app |
| Vývoj | https://dev.rovas.app |
Cesty služieb majú predponu /rovas. OAuth protokol používa /oauth2.
Posielajte Accept: application/json a pri tele POST/PUT aj Content-Type: application/json.
Ak plánujete integráciu, kontaktujte nás — radi zabezpečíme partnerský prístup a prejdeme váš prípad použitia.
Riešenia postavené na API
Aplikácie a doplnky, ktoré prepojujú nástroje tretích strán s Rovášom, sú uvedené na stránke Rováš konektory.
Ktoré API použiť?
| Model | Autentifikácia | Najlepšie pre |
|---|---|---|
| Klasické | HTTP hlavičky API-KEY a TOKEN |
Partnerské backendy, doplnky na webe, server–server |
| OAuth 2 (Bearer) | Authorization: Bearer <access_token> |
Mobil / SPA s prihlásením v prehliadači (napr. Civic) |
Na jednom volaní tieto modely nemiešajte. Klasické endpointy očakávajú API kľúče; Civic/OAuth zdroje majú API-key auth vypnutú a očakávajú Bearer (alebo sú verejné).
Označenia autentifikácie v tejto referencii
| Označenie | Význam |
|---|---|
| API-KEY | Hlavičky API-KEY + TOKEN (klasické) |
| Bearer | Authorization: Bearer so scope user_profile |
| Verejné | Bez poverení (API-key auth na zdroji vypnutá) |
| Voliteľný Bearer | Verejné čítanie; Bearer pridá polia špecifické pre používateľa |
Klasické API — ako ho používať
Prihlasovacie údaje
- Prihláste sa do Rováša a otvorte Môj účet → Rováš API.
- Vygenerujte údaje pre endpoint
rovas_endpoint. - Pri každom autentifikovanom volaní pošlite:
API-KEY: <váš api kľúč>
TOKEN: <váš token>Každý pár kľúčov patrí jednému používateľovi Rováša. Volania bežia v jeho mene.
Partnerská registrácia (vytvorenie alebo prepojenie koncového používateľa)
Partneri (napr. neziskovky), ktorí zakladajú účty darcom alebo členom, potrebujú technický účet s rolou api client (pridelí NeoFund/Rováš). API kľúč tohto účtu slúži len na zakladanie / prepojenie účtov.
Odporúčaný endpoint
POST /rovas/rovas_partner_user
Starší ekvivalent: POST /rovas/rules/rules_create_user (rovnaké telo a odpoveď).
Telo požiadavky (povinné polia)
| Pole | Popis |
|---|---|
user_name |
Zobrazované meno |
user_id |
Vaše externé číselné ID používateľa |
user_email |
E-mail (na nájdenie existujúceho účtu v Rováši) |
user_country |
ISO 3166-1 alpha-2, veľké písmená (napr. SK) |
user_language |
Kód jazyka (napr. sk, en) |
server_url |
Základná URL vášho webu (napr. https://partner.example/) |
Voliteľné: hybridauth_provider (ak prázdne, predvolené Nabezky), partner_client_id.
Zoznam povolených poskytovateľov: GET /rovas/rovas_hybridauth_providers.json (zvyčajne verejné).
Úspešná odpoveď
{
"rovas_uid": 123,
"api_key": "…",
"token": "…"
}Uložte vrátené api_key / token a používajte ich ako API-KEY / TOKEN pri ďalších volaniach v mene tohto koncového používateľa.
Príklad
curl -sS -X POST "https://rovas.app/rovas/rovas_partner_user" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "API-KEY: $PARTNER_API_KEY" \
-H "TOKEN: $PARTNER_TOKEN" \
-d '{
"user_name": "Jana Partnerská",
"user_id": 12345,
"user_email": "jana@example.com",
"user_country": "SK",
"user_language": "sk",
"server_url": "https://partner.example/",
"hybridauth_provider": "Nabezky"
}'Typické chyby: 400 validácia, 401 zlé údaje, 403 chýba oprávnenie api client.
Referencia klasických endpointov
Schémy požiadaviek/odpovedí sú v OpenAPI súbore (na vyžiadanie). Prehľad:
Účty a identita
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
POST |
/rovas/rovas_partner_user |
API-KEY | Odporúčané vytvorenie/prepojenie partnerského používateľa; vracia rovas_uid, api_key, token |
POST |
/rovas/rules/rules_create_user |
API-KEY | Staršie vytvorenie/prepojenie (rovnaké telo/odpoveď) |
GET |
/rovas/rovas_hybridauth_providers.json |
Verejné* | Zoznam HybridAuth poskytovateľov pre hybridauth_provider |
POST |
/rovas/rules/rules_fetch_user_data |
API-KEY | Profil majiteľa kľúča |
POST |
/rovas/rules/rules_users_chrons |
API-KEY | Zostatky Chronov |
POST |
/rovas/rules/rules_user_s_merits |
API-KEY | Súčty Meritov (voliteľný filter NACE) |
POST |
/rovas/rules/rules_check_enabled_language |
API-KEY | Či je 2-písmenový kód jazyka zapnutý |
*Zvyčajne verejné, keď je na zdroji zapnuté „Disable API keys authentication“.
Projekty a pracovné výkazy
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
POST |
/rovas/rules/rules_proxy_create_new_project |
API-KEY | Vytvoriť projekt |
POST |
/rovas/rules/rules_proxy_delete_project |
API-KEY | Zmazať projekt |
POST |
/rovas/rules/rules_proxy_create_work_report |
API-KEY | Vytvoriť pracovný výkaz |
POST |
/rovas/rules/rules_proxy_delete_work_report |
API-KEY | Zmazať pracovný výkaz |
POST |
/rovas/rules/rules_proxy_report_editability |
API-KEY | Je výkaz editovateľný volajúcim |
POST |
/rovas/rules/rules_proxy_work_report_verifiability |
API-KEY | Je výkaz overiteľný volajúcim |
POST |
/rovas/rules/rules_proxy_report_verification_status |
API-KEY | Stav overenia |
POST |
/rovas/rules/rules_create_verification |
API-KEY | Vytvoriť overenie |
POST |
/rovas/rules/rules_create_verification_with_acccess_token |
Verejné† | Overenie cez access token |
POST |
/rovas/rules/rules_proxy_check_verifier_by_access_tokens |
pozri OpenAPI | Overiteľnosť cez access tokeny |
POST |
/rovas/rules/rules_proxy_reward_work_report |
API-KEY | Odmeniť pracovný výkaz |
GET |
/rovas/rovas_verifications.json |
API-KEY | Zoznam overení pracovných výkazov |
GET |
/rovas/rovas_comment_notices.json |
API-KEY | Čakajúce upozornenia na sledované komentáre (rovnaké úložisko ako Civic Bearer dvojča) |
PUT |
/rovas/node/{id} |
API-KEY | Upraviť uzol vlastnený majiteľom kľúča |
DELETE |
/rovas/node/{id} |
API-KEY | Zmazať uzol vlastnený majiteľom kľúča |
†Preklep v machine name pravidla (acccess) je v živej ceste zámerný.
Podiely, nákupy, konverzie
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
POST |
/rovas/rules/rules_proxy_check_or_add_shareholder |
API-KEY | Zabezpečiť podiel používateľa na projekte |
POST |
/rovas/rules/rules_proxy_check_or_add_project_shareholder |
API-KEY | Zabezpečiť projekt ako podielnika |
POST |
/rovas/rules/rules_proxy_purchase_product |
API-KEY | Spracovať nákup produktu |
POST |
/rovas/rules/rules_proxy_create_aur |
API-KEY | Záznam o použití majetku (poplatok za použitie) |
POST |
/rovas/rules/rules_get_merits_for_projects |
API-KEY | Hodnoty Meritov pre ID projektov oddelené ` |
POST |
/rovas/rules/rules_convert_euros_to_chrons |
API-KEY | Kurz EUR → Chron |
POST |
/rovas/rules/rules_convert_euros_to_chrons_reverse |
API-KEY | Kurz Chron → EUR |
Views (rebríčky / feedy)
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/views/top_10_workers_in_a_category |
pozri OpenAPI | Top pracovníci v kategórii |
GET |
/rovas/views/project_merits_feed |
pozri OpenAPI | Top odmeňujúci projektu |
GET |
/rovas/views/projects_merits |
pozri OpenAPI | Top používatelia naprieč projektmi z rovnakého webu |
OAuth 2 / Bearer — ako ho používať
OAuth používa aplikácia Civic a ďalší klienti, ktorých registrujeme. Nové produkty potrebujú vlastný OAuth klient — z tretích strán nepoužívajte Civic client_id.
Protokolové endpointy
| Metóda | Cesta | Auth | Poznámky |
|---|---|---|---|
GET |
/oauth2/authorize |
session prehliadača | PKCE; Civic podporuje lang, intent |
POST |
/oauth2/token |
verejný klient + PKCE | authorization_code / refresh_token |
POST |
/oauth2/revoke |
token | Odvolať access/refresh |
GET |
/oauth2/tokens/{access_token} |
— | Introspekcia → user_id, client_id, expires, scope (404 ak neplatný) |
Civic klient (referencia)
| Nastavenie | Hodnota |
|---|---|
client_id |
civic |
| Typ klienta | Verejný (bez secretu) |
| Granty | Authorization code + refresh token |
| PKCE | Povinné (S256) |
| Scope | user_profile |
| Redirect | civic://oauth/callback |
Dodatočné parametre authorize: lang=sk|en, intent=login|register.
Výmena tokenu (authorization code + PKCE)
curl -sS -X POST "https://rovas.app/oauth2/token" \
-d grant_type=authorization_code \
-d client_id=civic \
-d redirect_uri=civic://oauth/callback \
-d code=PASTE_CODE \
-d code_verifier=$VERIFIERVolanie API s Bearer
curl -sS "https://rovas.app/rovas/me" \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"Príklad odpovede GET /rovas/me:
{
"uid": 42,
"username": "sano",
"display_name": "Alexander Žaťko",
"total_me": 1248.35,
"total_chr": 320.0,
"created": "2019-03-12T14:22:01+00:00",
"language": "sk",
"receipt_history_retention": null
}Referencia OAuth / Civic endpointov
Na týchto zdrojoch je autentifikácia API kľúčom vypnutá. Kde je to potrebné, použite Bearer.
Domov a profil
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/me |
Bearer | Profil: uid, username, display_name, total_me, total_chr, created, language, receipt_history_retention |
GET |
/rovas/contributions/aggregate |
Verejné | Súčet Meritov komunity (+ placeholdery kategórií) |
GET |
/rovas/merit_distribution |
Voliteľný Bearer | JSON histogram Meritov; polia user_* pri Bearer |
POST |
/rovas/civic_receipt_history_preference |
Bearer | Uchovávanie histórie dokladov (keep | policy) |
GET |
/rovas/civic_merit_history |
Bearer | Riadky osobnej histórie Meritov |
Používatelia
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/users_search?query= |
Bearer | Typeahead vyhľadávanie (parameter je query, nie q) |
GET |
/rovas/users_lookup?username= |
Bearer | Verejný komunitný profil (+ nace_expertise, agregáty kariet). Používatelia s total_me < 0 → 404 |
Voliteľné: lang=sk|en pri lookup pre lokalizované polia.
Daňové nároky
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
POST |
/rovas/rules/rules_proxy_claim_vat_receipt |
Bearer | Nárovať DPH z eKasy ako darcovské Merity (rozdelenie shares[]) |
GET |
/rovas/civic_claims?view=submitted|received |
Bearer | Zoznamy nárokov |
GET |
/rovas/civic_claims?receipt_uid= |
Bearer | Iba { claimed, receipt_uid } |
GET |
/rovas/civic_claims/summary |
Bearer | Súčty pre volajúceho |
GET |
/rovas/civic_national_hourly_rate?country= |
Verejné | Národná hodinová sadzba používaná vo vzorci ME |
Projekty, katalóg charít, dary
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/civic_project/{nid} |
Verejné‡ | Detail projektu (donate_iban, polia organizácie, …) |
GET |
/rovas/civic_project_work_reports?project_nid= |
Verejné‡ | Pracovné výkazy projektu |
GET |
/rovas/civic_project_shareholders?project_nid= |
Verejné‡ | Podielnici |
GET |
/rovas/civic_charity_projects |
Verejné | Katalóg schválených projektov vo verejnom prospechu |
POST |
/rovas/civic_create_charity_org |
Bearer | Darca navrhne organizáciu vo verejnom prospechu |
‡Anonymný prístup pre schválené projekty vo verejnom prospechu; inak platia Bearer / pravidlá prístupu.
Dobrovoľnícke pracovné výkazy
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/civic_my_projects |
Bearer | Projekty, na ktoré používateľ nedávno podával výkazy |
GET |
/rovas/civic_projects_search?query= |
Bearer | Hľadanie publikovateľných projektov (query ≥ 3 znaky) |
GET |
/rovas/civic_nace_tree |
Verejné | Strom činností NACE |
POST |
/rovas/civic_create_project |
Bearer | Vytvoriť projekt |
POST |
/rovas/civic_create_work_report |
Bearer | Vytvoriť pracovný výkaz (dôkaz: URL, fotky a/alebo mapa) |
GET |
/rovas/civic_work_report_map_config |
Bearer | Konfigurácia mapového widgetu pre dôkaz polohy |
POST |
/rovas/civic_ai_nace |
Bearer | AI návrh NACE + názvu (voliteľný modul) |
Overovanie a upozornenia
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/civic_pending_verifications |
Bearer | Výkazy priradené volajúcemu na overenie |
GET |
/rovas/civic_work_report/{nid} |
Bearer | Detail výkazu pre overovateľa |
POST |
/rovas/civic_submit_verification |
Bearer | Schváliť / zamietnuť / odmietnuť |
GET |
/rovas/civic_pending_comment_notices |
Bearer | Pollované upozornenia na sledované komentáre |
Merit index a spotlight
| Metóda | Cesta | Auth | Účel |
|---|---|---|---|
GET |
/rovas/civic_merit_index |
Verejné | Snapshot rebríčka (by_category, by_source, …) |
GET |
/rovas/civic_merit_index_countries |
Verejné | Možnosti filtra krajín |
GET |
/rovas/civic_merit_spotlight |
Verejné | Periodickí lídri podľa oblasti Civic |
GET |
/rovas/civic_merit_period_index |
Verejné | Periodický rebríček ME•ter |
Podpora
Otázky, OpenAPI schémy alebo nový OAuth klient: kontaktujte NeoFund.