DigitalniJmenovky.cz REST API
DigitalniJmenovky.cz API umožňuje programaticky spravovat zaměstnance, jmenovky, gateway a statusy. API je RESTful, vrací JSON a používá standardní HTTP metody.
Veškeré požadavky musí být odesílány přes HTTPS. HTTP požadavky jsou automaticky přesměrovány.
Base URL: https://api.digitalnijmenovky.cz/v2
Autentizace
API používá Bearer token autentizaci. API klíč získáte v nastavení konzole pod Settings → API Keys.
Klíč posílejte v hlavičce každého požadavku:
Authorization: Bearer djcz_live_sk_xxxxxxxxxxxxxxxxxxxx
API klíče mají dva typy: live (produkce) a test (sandbox). Testovací klíče začínají djcz_test_sk_.
Testovací klíč (sandbox)
djcz_test_sk_demo_4f8a2b9c1e7d3f6a
Tento klíč je určen výhradně pro testování dokumentace. Vrací fiktivní data a nelze jej použít v produkci.
Chybové kódy
API vrací standardní HTTP stavové kódy. Chybové odpovědi mají konzistentní formát:
{
"error": {
"code": "EMPLOYEE_NOT_FOUND",
"message": "Employee with id 'emp_xxx' not found",
"status": 404,
"request_id": "req_7f3a2c1d9e4b"
}
}
| Kód | Popis |
|---|---|
| 200 OK | Požadavek proběhl úspěšně |
| 201 Created | Záznam byl vytvořen |
| 400 Bad Request | Chybějící nebo neplatné parametry |
| 401 Unauthorized | Neplatný nebo chybějící API klíč |
| 403 Forbidden | Nedostatečná oprávnění |
| 404 Not Found | Záznam nenalezen |
| 429 Too Many Requests | Překročen rate limit |
| 500 Server Error | Interní chyba serveru |
Rate limiting
API omezuje počet požadavků pomocí sliding window algoritmu. Limity jsou uvedeny v hlavičkách každé odpovědi:
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 847 X-RateLimit-Reset: 1741694400 Retry-After: 12 (pouze při 429)
| Plán | Limit | Okno |
|---|---|---|
| Free / Test | 100 req | 15 minut |
| Standard | 1 000 req | 15 minut |
| Enterprise | Neomezeno | — |
Zaměstnanci
Správa zaměstnanců přiřazených do systému jmenovek. Zaměstnanec je základní entita propojená s jednou nebo více jmenovkami.
Vrací seznam všech zaměstnanců v organizaci. Výsledky jsou stránkované (výchozí: 20 záznamů).
| Parametr | Typ | Povinný | Popis |
|---|---|---|---|
| limit | integer | volitelný | Počet výsledků (1–100, výchozí: 20) |
| offset | integer | volitelný | Přeskočit N záznamů (stránkování) |
| department | string | volitelný | Filtrovat podle oddělení (slug) |
| status | string | volitelný | Filtrovat: in_office, home_office, vacation, meeting |
curl https://api.digitalnijmenovky.cz/v2/employees \ -H "Authorization: Bearer djcz_test_sk_demo_4f8a2b9c1e7d3f6a" \ -G \ --data-urlencode "limit=3" \ --data-urlencode "department=it"
Vytvoří nového zaměstnance a volitelně ho přiřadí k jmenovce a oddělení.
| Pole | Typ | Povinný | Popis |
|---|---|---|---|
| first_name | string | povinný | Jméno zaměstnance |
| last_name | string | povinný | Příjmení zaměstnance |
| role | string | povinný | Pracovní pozice |
| department_id | string | povinný | ID oddělení |
| string | volitelný | E-mail pro sync s kalendářem | |
| plate_id | string | volitelný | ID jmenovky k přiřazení |
| initial_status | string | volitelný | Výchozí status (default: in_office) |
curl -X POST https://api.digitalnijmenovky.cz/v2/employees \ -H "Authorization: Bearer djcz_test_sk_demo_4f8a2b9c1e7d3f6a" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Tomáš", "last_name": "Novák", "role": "Senior Developer", "department_id": "dept_it_001", "email": "[email protected]", "plate_id": "plate_042", "initial_status": "in_office" }'
Změní status zaměstnance. Změna se projeví na přiřazené jmenovce do 3 sekund.
| Parametr | Typ | Popis |
|---|---|---|
| id | string | ID zaměstnance (formát: emp_XXXXXXXX) |
| Pole | Typ | Povinný | Hodnoty |
|---|---|---|---|
| status | string | povinný | in_office · home_office · meeting · vacation · sick · offline |
| until | datetime | volitelný | ISO 8601 — automatický reset po uplynutí |
| note | string | volitelný | Krátká poznámka (max 60 znaků) |
curl -X PATCH \ https://api.digitalnijmenovky.cz/v2/employees/emp_tn8f2a1c/status \ -H "Authorization: Bearer djcz_test_sk_demo_4f8a2b9c1e7d3f6a" \ -H "Content-Type: application/json" \ -d '{ "status": "meeting", "until": "2026-03-11T15:30:00Z", "note": "Týdenní standup" }'
Webhooks
Webhooks umožňují váš systém notifikovat o změnách v reálném čase — bez nutnosti pollovat API. DigitalniJmenovky.cz odešle HTTP POST na váš endpoint při každé definované události.
Dostupné události
| Událost | Popis |
|---|---|
| employee.status_changed | Status zaměstnance byl změněn |
| plate.refreshed | Jmenovka byla překreslena |
| plate.offline | Jmenovka přestala reagovat (baterie?) |
| gateway.connected | Gateway se připojila k síti |
| gateway.disconnected | Gateway ztratila připojení |
| employee.created | Nový zaměstnanec byl přidán |
Příklad payload — employee.status_changed
{
"event": "employee.status_changed",
"created_at": "2026-03-11T12:34:56Z",
"request_id": "req_7f3a2c1d9e4b",
"data": {
"employee_id": "emp_tn8f2a1c",
"name": "Tomáš Novák",
"status_prev": "in_office",
"status_new": "meeting",
"until": "2026-03-11T15:30:00Z",
"plate_id": "plate_042",
"source": "calendar_sync"
}
}
Ověření podpisu: Každý webhook požadavek obsahuje hlavičku X-Inkplate-Signature — HMAC-SHA256 podpis těla požadavku. Vždy ověřte podpis před zpracováním!
{
"data": [
{
"id": "emp_tn8f2a1c",
"first_name": "Tomáš",
"last_name": "Novák",
"role": "Senior Developer",
"department": {
"id": "dept_it_001",
"name": "IT Oddělení"
},
"status": "in_office",
"plate_id": "plate_042",
"updated_at": "2026-03-11T08:02:00Z"
},
{
"id": "emp_jh3k9b2d",
"first_name": "Jana",
"last_name": "Horáková",
"role": "HR Manažerka",
"department": {
"id": "dept_hr_002",
"name": "HR & Lidé"
},
"status": "home_office",
"plate_id": "plate_017",
"updated_at": "2026-03-11T07:45:00Z"
}
],
"meta": {
"total": 247,
"limit": 20,
"offset": 0
}
}
{
"error": {
"code": "INVALID_API_KEY",
"message": "The API key provided is invalid or has been revoked.",
"status": 401,
"request_id": "req_err_9a2b"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Retry after 12 seconds.",
"status": 429,
"retry_after": 12
}
}