API Stafio

Jednotné rozhraní, přes které se ke Stafiu připojují externí aplikace — vlastní web, mobilní aplikace i aplikace třetích stran.

Rychlý start

Standardní API v8 slouží k napojení vlastního webu nebo systému. Následující čtyři kroky vedou od založení účtu k prvnímu volání; podrobnosti ke každému z nich jsou dál na této stránce.

1. Připravte účet a API klíč

Založte samostatného integračního uživatele s rolí STAFIO.API a přidělte mu potřebná pracoviště a střediska. V Profil → API klíče, případně na detailu uživatele jako administrátor, vytvořte klíč. Jeho plná hodnota je viditelná jen 15 minut. Uložte ji na server integrace do chráněné konfigurace, nikoli do JavaScriptu veřejného webu.

Od správce potřebujete také adresu API své instance. V příkladech nahraďte <INSTANCE> skutečným hostitelem. Nepoužívejte zde api.stafio.cz, protože jde o přihlašovací bránu.

2. Vyměňte klíč za token

POST https://<INSTANCE>/api/rpc/platform_jwt_token_generate8
Content-Type: application/json
Content-Profile: platform
Prefer: params=single-object

{"api_key":"<VAS_API_KLIC>"}

Zkontrolujte HTTP stav a pole success v JSON odpovědi. Při úspěchu použijte hodnotu token. Při neúspěchu zpracujte message_text. Klíč se ověřuje přímo na vaší instanci. Platnost tokenu určuje nastavení klíče, standardně 60 minut; po vypršení jej znovu vyměňte.

3. Proveďte první volání bez změny dat

POST https://<INSTANCE>/api/rpc/call
Content-Type: application/json
Content-Profile: api
Prefer: params=single-object
Authorization: Bearer <TOKEN_Z_ODPOVEDI>

{"version":8,"func":"ping","params":{}}

Úspěšná odpověď má ok: true. Poté můžete zkusit například seznam inzerátů se stejnými hlavičkami:

{"version":8,"func":"job.list","params":{"limit":20,"offset":0}}

4. Zpracujte odpovědi

Obálka standardního volání obsahuje ok, version, func, data, meta a error. Nestačí kontrolovat HTTP 200: aplikační chyba může být vrácena s ok: false. Zároveň ošetřete HTTP chyby autentizace, proxy a sítě, které tuto obálku mít nemusí.

• Při chybě přihlášení zkontrolujte instanci, klíč a platnost tokenu.
• Při chybě oprávnění zkontrolujte roli a přiřazení dat integračnímu účtu.
• Po timeoutu zápis neopakujte naslepo: nejprve ověřte, zda již nevznikla registrace nebo reakce.

Funkční implementaci přihlášení a volání najdete v PHP ukázce. Živé demo používá skutečné API; odeslání formuláře může vytvářet data.

Jak to funguje

Celé API má jediný endpoint. Nevolá se tedy různá URL podle funkce, ale vždy stejná adresa a v těle požadavku se řekne, co se má provést.

POST https://<instance>/api/rpc/call
Content-Type: application/json
Content-Profile: api
Prefer: params=single-object
Authorization: Bearer <JWT>

Tělo požadavku je vždy objekt se třemi povinnými poli:

{
  "version": 8,
  "func": "job.list",
  "params": { "limit": 20, "offset": 0 }
}

Pole	Význam
version	Verze kontraktu. Povinné, celé kladné číslo. Aktuální verze je 8.
func	Logické jméno funkce (např. job.list). Není to jméno databázové procedury.
params	Parametry funkce. Povinné — když funkce nic nepotřebuje, pošle se {}.

Hlavička Prefer: params=single-object je povinná — bez ní by se tělo požadavku nepředalo jako jeden celek a volání skončí chybou.

Odpověď

Odpověď má vždy stejný tvar, ať dopadne jakkoliv:

{
  "ok": true,
  "version": 8,
  "func": "job.list",
  "data": [ { "job_id": 1042, "name": "Skladník" } ],
  "meta": { "row_count": 1 },
  "error": null
}

Při chybě:

{
  "ok": false,
  "version": 8,
  "func": "job.list",
  "data": null,
  "meta": null,
  "error": { "code": "API_FUNC_UNKNOWN", "message": "Neznámá funkce…", "detail": null }
}

Chyby (včetně neočekávaných) se vracejí s HTTP kódem 200 a rozlišují se polem ok. Klient tak má jednotné zpracování a nemusí řešit různé stavové kódy.

Čí data se vrátí, určuje token, se kterým voláte — stejný požadavek tak u každého zákazníka vrací jeho vlastní data.

Token — získání a prodlužování

Každé volání API se posílá s tokenem v hlavičce Authorization: Bearer <JWT>. Token se nevytváří ručně — vydává ho samo API.

Příprava: uživatel s rolí pro API

1. Založte uživatele, pod kterým bude integrace běžet (samostatného pro každou integraci, ne sdíleného).
2. Přiřaďte mu roli STAFIO.API — ta zpřístupňuje endpoint api.call.

Doporučeně: přihlášení API klíčem

API klíč je trvalé heslo pro strojový přístup. Má stejná práva jako uživatel, kterému patří, a odvolá se jeho zakázáním nebo smazáním — bez zásahu do hesla uživatele.

Kde se klíč vytvoří:

1. Přihlaste se do Stafia a otevřete Profil → záložka API klíče.
2. Klikněte na Nový API klíč a vyplňte popis, k čemu klíč slouží.
3. Vygenerovaná hodnota se zobrazí ve sloupci Klíč a je viditelná jen 15 minut — zkopírujte si ji hned, později už ji nelze zjistit (v přehledu zůstane jen začátek).
4. Ve sloupci Platnost tokenu (min) nastavíte, jak dlouho platí token vydaný na klíč (výchozí 60 minut).

Administrátor zakládá a ruší klíče všech uživatelů ownera na detailu uživatele → záložka API klíče — integrátor tak nepotřebuje heslo k účtu, pod kterým poběží.

Klíč se vymění za token přímo na instanci zákazníka:

curl -X POST <base_api_url>/rpc/platform_jwt_token_generate8 \
  -H 'Content-Type: application/json' \
  -H 'Content-Profile: platform' \
  -H 'Prefer: params=single-object' \
  -d '{ "api_key": "stf_..." }'

Klíč patří jedné databázi a přihlašovací proxy app.stafio.cz ho po instancích nerozesílá — volání s klíčem musí mířit rovnou na adresu API dané instance. Token vydaný na klíč se neobnovuje přes platform_jwt_token_renew8; po vypršení si klient vyžádá nový stejným voláním.

Přihlášení jménem a heslem — přes app.stafio.cz

Tato cesta platí, když se integrace přihlašuje uživatelským jménem a heslem místo API klíče. Zákazníci jsou rozdělení do více databází a klient dopředu neví, ve které je ten jeho. První požadavek proto míří vždy na app.stafio.cz a volá se proxy_jwt_token_generate8:

curl -X POST https://app.stafio.cz/api/rpc/proxy_jwt_token_generate8 \
  -H 'Content-Type: application/json' \
  -H 'Content-Profile: platform' \
  -H 'Prefer: params=single-object' \
  -d '{
        "login": "<uživatel>",
        "password": "<heslo>"
      }'

Parametr	Význam
login, password	Přihlašovací údaje uživatele
app_domain	Volitelné — doména instance, je-li známa
token_type	Volitelné. STAFIO_APP_PUBLIC vydá veřejný (anonymní) token bez hesla — pro veřejné výpisy inzerátů
otp	Volitelné — jednorázový kód, je-li u účtu zapnuté dvoufaktorové ověření

Proxy uživatele najde: buď je v databázi, na kterou jste zavolali, nebo se postupně zeptá ostatních instancí a přihlášení jim přepošle. Vrácený token pak patří té správné databázi.

Nevolejte platform_jwt_token_generate8 přímo. Ta hledá uživatele jen v jedné konkrétní databázi, takže pro zákazníka v jiné instanci skončí chybou.

Kam posílat další požadavky

Odpověď obsahuje token a v něm je i adresa API dané instance:

{ "success": true, "token": "eyJhbGciOi…", "user_name": "Jan Novák" }

Token (JWT) nese mimo jiné tyto údaje:

Údaj v tokenu	K čemu je
base_api_url	Adresa API instance zákazníka — sem míří všechna další volání
app_domain	Doména instance; z ní se skládají adresy obrázků a dokumentů
owner_id, user_id, role	Identita — určuje, čí data se vrací
exp	Konec platnosti

Postup je tedy vždy: přihlásit se na app.stafio.cz → z tokenu si přečíst base_api_url → všechno ostatní posílat tam. To platí i pro prodlužování tokenu a pro stahování obrázků.

Payload tokenu si klient přečte běžným dekódováním JWT (prostřední část oddělená tečkami, Base64URL) — podpis ověřovat nemusí, ten kontroluje server.

Platnost a prodloužení

Token platí 1 den. Integrace ho proto musí pravidelně prodlužovat.

Prodloužení se dělá stávajícím platným tokenem — žádné heslo se neposílá a nejsou potřeba žádné parametry:

curl -X POST <base_api_url>/rpc/platform_jwt_token_renew8 \
  -H 'Content-Type: application/json' \
  -H 'Content-Profile: platform' \
  -H 'Authorization: Bearer <stávající token>'

Prodloužení se posílá na base_api_url z tokenu, ne na app.stafio.cz — přes proxy se chodí jen pro první přihlášení.

Vrátí se nový token se stejnou identitou a novou platností; starý zahoďte.

Doporučený postup pro integraci:

1. Při startu si vyžádejte token přes platform_jwt_token_generate8.
2. Token si držte a prodlužujte ho s rezervou (například jednou za pár hodin), ne až v okamžiku vypršení.
3. Když prodloužení selže (token už vypršel), přihlaste se znovu jménem a heslem.

Prodloužit lze jen token uživatele nebo osoby. U jiných typů vrátí volání chybu CANNOT_RENEW a je nutné se přihlásit znovu.

Pozor: vydaný token nelze odvolat — platí až do vypršení. Když token unikne, je jediná cesta zablokovat nebo změnit heslo dotčeného uživatele. Proto má mít každá integrace vlastního uživatele.

Přehled funkcí

ping

Ověření dostupnosti. Bez parametrů ({}), vrací { "pong": true }.

job.list — seznam inzerátů

Všechny parametry volitelné.

Parametr	Význam
region_id	Filtr regionu
work_type_id	Filtr druhu práce
partner_id	Filtr zaměstnavatele
label_ids	Filtr štítků
limit	Počet položek (výchozí 20, maximum 100)
offset	Posun pro stránkování

Vrací pole inzerátů: job_id, name, wage, description_short, region_id, region_description, work_type_id, work_type_desc, address, partner_id, partner_name, partner_logo_id, partner_logo_ois, photo_bin_object_id, created, created_as_text.

job.detail — detail inzerátu

Parametr	Význam
job_id	Povinné — ID inzerátu

Vrací navíc oproti seznamu: description (HTML), regions, regions_description, work_types, work_types_description, gallery_bin_object_id, gallery_bin_object_ois (pole obrázků galerie) a video_url.

job.response — odpověď na inzerát

Parametr	Význam
job_id	Povinné — ID inzerátu
first_name, last_name	Povinné — jméno a příjmení
email	Povinné
mobile	Povinné — celé telefonní číslo (samotná předvolba nestačí)
response_text	Volitelné — průvodní dopis / komentář
password	Volitelné — heslo pro založení účtu
mail_template_id	Volitelné — šablona potvrzovacího e-mailu (viz níže)
cv_file_name	Volitelné — název souboru životopisu včetně přípony; povinný, když je vyplněno cv_base64
cv_base64	Volitelné — obsah životopisu v Base64. Přiloží se k odpovědi a osobě se nastaví jako CV, pokud žádný nemá

Vrací { "result": true, "response_id": …, "info_text": … }.

Kam se odpověď zapíše:

Tabulka	Co se zapíše
jp_job_response_tab	Samotná odpověď na inzerát (vrácené response_id)
person_tab	Osoba — podle e-mailu se dohledá existující, jinak se založí nová
mail_box_tab	Potvrzovací e-mail — pouze pokud je předán mail_template_id

Před zápisem se kontroluje, že je inzerát aktivní, a že telefon má alespoň 9 číslic.

person.register — registrace uchazeče

Parametr	Význam
first_name, last_name	Povinné
email	Povinné
mobile	Povinné — celé telefonní číslo
password	Volitelné — heslo
cost_center	Volitelné — středisko („chci pracovat jako“)
emergency_contact	Volitelné — nouzový kontakt (u nezletilých odpovědná osoba); uloží se do kontaktů osoby jako „Nouzový kontakt“
domain	Volitelné — doména webu (např. o2callup.cz); určuje šablonu potvrzovacího e-mailu a adresu potvrzovacího odkazu. Bez parametru se bere z tokenu — token z přihlášení jménem a heslem doménu nenese, proto ji integrace posílá v parametru
mail_template_id	Volitelné — šablona uvítacího e-mailu (viz níže)
note	Volitelné — poznámka k uchazeči (např. shrnutí telefonického předvýběru). Uloží se do poznámek osoby, tedy tam, kam ji píše náborář v aplikaci — s časem a autorem, bez přepsání profilu
cv_file_name	Volitelné — název souboru životopisu včetně přípony; povinný, když je vyplněno cv_base64
cv_base64	Volitelné — obsah životopisu v Base64. Uloží se jako dokument osoby typu Web CV

Vrací { "result": true, "person_id": …, "info_text": … }.

Nahrávání kandidátů z externího systému: note a cv_base64 jsou určené pro integrace, které kandidáty sbírají jinde (ATS, kariérní web, AI náborář) a do Stafia je předávají i s poznámkou a životopisem. Když kandidát patří ke konkrétnímu inzerátu, použijte místo registrace job.response — poznámka tam patří do response_text a životopis se přiloží přímo k odpovědi.

Registrace bez hesla: password se posílat nemusí — registrační formulář tedy pole pro heslo mít nemusí. Stafio si v takovém případě vygeneruje interní heslo, které se nikam neodesílá; uchazeč si své heslo nastaví později v aplikaci volbou Zapomenuté heslo (na jeho e-mail přijde odkaz pro nastavení hesla). Do té doby je uchazeč zaregistrovaný, ale do aplikace se nepřihlásí.

Šablony e-mailů

API samo od sebe žádný e-mail neposílá. E-mail vznikne jen tehdy, když volající předá parametr mail_template_id. Bez něj se odpověď i registrace uloží, ale žádná zpráva se nezaloží.

Šablona se dohledává podle vlastníka (zákazníka) a předaného ID. Z šablony se vezme předmět i tělo, doplní se do nich hodnoty a výsledek se založí do fronty mail_box_tab, odkud ho odešle standardní odesílání pošty. Odesílatel se nastaví na e-mail uživatele, pod kterým volání běží.

Funkce	Doporučené ID šablony
job.response	API_JOB_RESPONSE
person.register	API_PERSON_REG

Uvedená ID jsou doporučená konvence pro šablony používané tímto API — proto začínají API_. Šablonu s tímto ID si musíte ve svém účtu nejdřív založit; pokud neexistuje, e-mail se nezaloží. Použít lze i libovolnou jinou existující šablonu, právě proto je ID parametrem.

Pole, která lze v šabloně nahradit

V předmětu i těle šablony se nahradí tyto zástupné hodnoty:

Funkce	Dostupná pole
job.response	FIRST_NAME, LAST_NAME, EMAIL, MOBILE, RESPONSE_TEXT, JOB_ID, JOB_NAME
person.register	FIRST_NAME, LAST_NAME, EMAIL, MOBILE, COST_CENTER

Zápis zástupných polí v šabloně se řídí obecným mechanismem popsaným v Automatická pole a dynamické odkazy pro maily a SMS.

Obrázky

API vrací u loga a fotek identifikátor *_ois (např. partner_logo_ois, gallery_bin_object_ois). Adresu obrázku si klient poskládá sám — základ vezme z tokenu, nikoliv z vlastní konfigurace:

<app_domain>get/document-by-ois?ois=<ois>

Pozor: dokumenty a obrázky jsou na app_domain, ne pod base_api_url. base_api_url slouží jen pro volání API. Například pro app_domain = https://firma.stafio.cz/ je adresa obrázku https://firma.stafio.cz/get/document-by-ois?ois=….

Obrázek se stahuje běžným GET a nevyžaduje token, takže se dá vložit rovnou do <img src="…">.

gallery_bin_object_ois je pole, inzerát tedy může mít více obrázků.

Ukázka volání

curl -X POST https://<instance>/api/rpc/call \
  -H 'Content-Type: application/json' \
  -H 'Content-Profile: api' \
  -H 'Prefer: params=single-object' \
  -H 'Authorization: Bearer <JWT>' \
  -d '{"version":8,"func":"job.list","params":{"limit":20}}'

Ukázková aplikace

Funkční ukázka integrace běží na api-demo.stafio.cz — jednoduchá PHP aplikace, která přes toto API zobrazuje seznam a detail inzerátů, umožňuje odpovědět na inzerát a zaregistrovat se.

Zdrojový kód je na github.com/stafiocz/stafio-api-demo-php a je možné ho použít jako výchozí bod pro vlastní integraci: ukazuje přihlášení přes proxy, převzetí adresy API z tokenu, volání jednotlivých funkcí i skládání adres obrázků. Jde o jednoduchou PHP aplikaci bez knihoven — stačí PHP s rozšířeními curl a json.

Oprávnění

Uživateli, pod kterým má integrace běžet, přiřaďte roli STAFIO.API. Bez ní volání API skončí chybou oprávnění.

Doporučení: založte pro každou integraci vlastního uživatele, ne sdíleného. Vydaný token nelze odvolat, takže při jeho úniku je jediná možnost zablokovat nebo změnit heslo dotčeného uživatele — a to se pak nedotkne ostatních integrací.