API Dokumentace

Integrujte Docházka.net s vašimi systémy pomocí našeho RESTful API

API v1 REST JSON

API je v přípravě — přístupové klíče zatím vydáváme ručně. Napište nám na podpora@dochazka.net a klíč vám připravíme.

Obsah

Úvod Autentizace Endpointy → Uživatelé → Docházka → Směny → Pracovní dny Chybové kódy Limity

Úvod

Docházka.net API umožňuje programový přístup k vašim docházkovým datům.

Poznámka: API je součástí jednotného tarifu — aktivace na vyžádání přes podporu (podpora@dochazka.net).

Base URL

https://api.dochazka.net/v1

Formát dat

API komunikuje výhradně ve formátu JSON. Všechny požadavky musí obsahovat hlavičku:

Content-Type: application/json

Autentizace

API používá autentizaci pomocí API klíčů. Klíče zatím vydáváme ručně — napište nám na podpora@dochazka.net.

Použití API klíče

API klíč předávejte v hlavičce každého požadavku:

X-API-Key: YOUR_API_KEY

Příklad požadavku

curl -X GET https://api.dochazka.net/v1/users \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Endpointy

Uživatelé

GET /users - Seznam uživatelů

Vrací seznam všech aktivních uživatelů ve vašem tenantu.

Parametry:

page (optional) - Číslo stránky (default: 1)
per_page (optional) - Počet záznamů na stránku (default: 50, max: 100)

Odpověď:

{
  "users": [
    {
      "id": 123,
      "firstname": "Jan",
      "lastname": "Novák",
      "email": "jan.novak@firma.cz",
      "username": "jnovak",
      "is_active": true,
      "is_admin": false,
      "created_at": "2026-01-01T10:00:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "per_page": 50
}

Zakládání a úpravu uživatelů zatím provádíte ve webové aplikaci (Správa → Uživatelé); přes API je nyní dostupné čtení seznamu uživatelů.

Docházka

GET /attendance - Seznam záznamů

Vrací seznam docházkových záznamů.

Parametry:

user_id (optional) - ID uživatele
date_from (optional) - Datum od (YYYY-MM-DD)
date_to (optional) - Datum do (YYYY-MM-DD)
type (optional) - Typ záznamu (arrival/departure)

Odpověď:

{
  "records": [
    {
      "id": 456,
      "user_id": 123,
      "timestamp": "2026-01-08T08:00:00Z",
      "type": "arrival",
      "note": "Včasný příchod",
      "is_manual": false
    }
  ],
  "total": 100
}

POST /attendance - Přidání záznamu

Vytvoří nový docházkový záznam.

Tělo požadavku:

{
  "user_id": 123,
  "timestamp": "2026-01-08T08:00:00Z",
  "type": "arrival",
  "note": "Příchod z API"
}

// Odchod s důvodem (volitelné)
{
  "user_id": 123,
  "timestamp": "2026-01-08T16:30:00Z",
  "type": "departure",
  "exit_reason": "break",  // Možnosti: null, "break", "doctor", "vacation", "unpaid_leave"
  "note": "Odchod na pauzu"
}

Směny

GET /shifts - Seznam směn

Vrací vypočítané směny na základě docházkových záznamů.

Parametry:

user_id (optional) - ID uživatele
month (optional) - Měsíc (1-12)
year (optional) - Rok

Odpověď:

{
  "shifts": [
    {
      "id": 789,
      "user_id": 123,
      "date": "2026-01-08",
      "start_time": "2026-01-08T08:00:00Z",
      "end_time": "2026-01-08T16:30:00Z",
      "duration_minutes": 510,
      "is_complete": true,
      "shift_type": "work"
    }
  ],
  "summary": {
    "total_hours": 170,
    "total_days": 20,
    "average_hours_per_day": 8.5
  }
}

Pracovní dny (WorkDays)

Nové API pro práci s pracovními dny. Každý pracovní den může obsahovat více směn různých typů.

Pracovní dny

GET /workdays - Seznam pracovních dnů

Vrátí seznam pracovních dnů s agregovanými daty.

Parametry:

user_id - ID uživatele (volitelné)
date_from - Datum od (YYYY-MM-DD)
date_to - Datum do (YYYY-MM-DD)

Odpověď:

{
  "workdays": [
    {
      "id": 456,
      "user_id": 123,
      "date": "2026-01-08",
      "total_hours_worked": 8.5,
      "work_time_minutes": 480,
      "total_break_minutes": 30,
      "paid_absence_minutes": 0,
      "unpaid_absence_minutes": 0,
      "is_complete": true,
      "shifts": [
        {
          "id": 789,
          "start_time": "2026-01-08T08:00:00Z",
          "end_time": "2026-01-08T12:00:00Z",
          "duration_minutes": 240,
          "shift_type": "work",
          "sequence_number": 1
        },
        {
          "id": 790,
          "start_time": "2026-01-08T12:00:00Z",
          "end_time": "2026-01-08T12:30:00Z",
          "duration_minutes": 30,
          "shift_type": "break",
          "sequence_number": 2
        },
        {
          "id": 791,
          "start_time": "2026-01-08T12:30:00Z",
          "end_time": "2026-01-08T16:30:00Z",
          "duration_minutes": 240,
          "shift_type": "work",
          "sequence_number": 3
        }
      ]
    }
  ],
  "summary": {
    "total_hours": 170,
    "total_days": 20,
    "average_hours_per_day": 8.5,
    "total_work_time_hours": 160,
    "total_break_hours": 10,
    "total_paid_absence_hours": 0,
    "total_unpaid_absence_hours": 0
  }
}

Chybové kódy

Kód	Význam	Popis
`200`	OK	Požadavek byl úspěšně zpracován
`201`	Created	Záznam byl úspěšně vytvořen
`400`	Bad Request	Neplatný požadavek (chybné parametry)
`401`	Unauthorized	Chybí nebo je neplatný API klíč
`403`	Forbidden	Nedostatečná oprávnění
`404`	Not Found	Záznam nenalezen
`429`	Too Many Requests	Překročen limit požadavků
`500`	Server Error	Interní chyba serveru

Formát chybové odpovědi

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "details": {
      "field": "date_from",
      "error": "Invalid date format"
    }
  }
}

Limity

Důležité: API má nastavené limity pro ochranu před přetížením.

Rate limiting

Standardní limit: 1000 požadavků za hodinu
Individuální plány: až 10000 požadavků za hodinu (dle dohody)

Aktuální stav limitů je vrácen v hlavičkách odpovědi:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1641024000

Další omezení

Maximální velikost požadavku: 10 MB
Maximální počet záznamů na stránku: 100
Timeout požadavku: 30 sekund

Potřebujete API přístup?

API je součástí jednotného tarifu — napište nám pro aktivaci

Zobrazit plány