API dokumentace – napojení externích systémů

Směny.cz API dokumentace

Verze: 1.0
Typ API: GraphQL

Směny.cz API umožňuje napojení externích systémů (HR, docházka, ERP, plánování výroby) na systém plánování směn Směny.cz.

API umožňuje:

• čtení uživatelů
• čtení pracovišť
• čtení směn
• vytváření směn
• úpravu směn
• mazání směn
• synchronizaci zaměstnanců pomocí externího ID

1. Prostředí

Testovací prostředí (PREPROD)

Používejte pro vývoj a testování.

GraphQL endpoint:
https://preprod.smeny.cz/graphql

GraphiQL Explorer:
https://preprod.smeny.cz/graphiql?token=TOKEN

GraphiQL umožňuje:

• testování query
• testování mutation
• prohlížení schématu
• dokumentaci API

Produkční prostředí

https://smeny.cz/api/graphql/

⚠️ Produkční data nelze obnovit.

2. Autorizace

API používá JWT token.

Token lze vytvořit v administraci:

Nastavení → API přístupy
nebo: https://preprod.smeny.cz/company-access-token/list

HTTP autorizace

Authorization: Bearer TOKEN

Příklad requestu

POST /graphql HTTP/1.1
Host: preprod.smeny.cz
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "query": "{ workplaces { edges { node { id name } } } }"
}

3. GraphQL princip

API používá GraphQL. Existují dva typy operací:

Query

Slouží ke čtení dat. Například: users, workplaces, shifts

Mutation

Slouží k zápisu dat. Například: shiftCreate, shiftDelete

4. Stránkování (Pagination)

Výpisy používají pager.

pager: { first: 50 }

Doporučené maximum: first: 100

5. Datové typy

ID

UUID formát: fb01013a-3f2f-46d4-9d06-726b38868632

Datum a čas

ISO 8601 formát: 2026-07-01T08:00:00+02:00

6. Pracoviště

Výpis pracovišť

{
  workplaces(pager: { first: 50 }) {
    edges {
      node {
        id
        name
        fullName
      }
    }
  }
}

Ukázka odpovědi

{
  "data": {
    "workplaces": {
      "edges": [
        {
          "node": {
            "id": "fb01013a",
            "name": "Recepce",
            "fullName": "Firma > Recepce"
          }
        }
      ]
    }
  }
}

7. Uživatelé

Výpis uživatelů

{
  users(pager: { first: 100 }) {
    edges {
      node {
        id
        fullName
        email
        externalId
      }
    }
  }
}

Ukázka odpovědi

{
  "data": {
    "users": {
      "edges": [
        {
          "node": {
            "id": "15ae477a",
            "fullName": "Jan Novák",
            "email": "[email protected]",
            "externalId": "122585"
          }
        }
      ]
    }
  }
}

8. Externí ID uživatele

Externí ID je identifikátor zaměstnance z externího systému, například: 122585

Externí ID lze nastavit v detailu uživatele: Uživatel → Externí ID

Doporučujeme používat pro integraci. Výhody:

• stabilní identifikace
• jednoduchá synchronizace
• nezávislé na interním ID

9. Směny – vytvoření

Vytvoření směny s přiřazeným zaměstnancem

mutation {
  shiftCreate(input: {
    workplaceId: "fb01013a-3f2f-46d4-9d06-726b38868632"
    userId: "15ae477a-1112-4d33-a451-fc719bf77aed"
    since: "2026-07-01T08:00:00+02:00"
    till: "2026-07-01T16:00:00+02:00"
  }) {
    shift {
      id
      since
      till
    }
  }
}

Ukázka odpovědi

{
  "data": {
    "shiftCreate": {
      "shift": {
        "id": "b9123311",
        "since": "2026-07-01T08:00:00+02:00",
        "till": "2026-07-01T16:00:00+02:00"
      }
    }
  }
}

10. Vytvoření prázdné směny

Pokud není zadán userId, vznikne otevřená směna bez zaměstnance:

mutation {
  shiftCreate(input: {
    workplaceId: "fb01013a"
    since: "2026-07-01T08:00:00+02:00"
    till: "2026-07-01T16:00:00+02:00"
  }) {
    shift {
      id
    }
  }
}

11. Úprava směny

Úprava se provádí pomocí shiftCreate s parametrem id existující směny:

mutation {
  shiftCreate(input: {
    id: "SHIFT_ID"
    workplaceId: "fb01013a"
    since: "2026-07-01T09:00:00+02:00"
    till: "2026-07-01T17:00:00+02:00"
  }) {
    shift {
      id
    }
  }
}

12. Smazání směny

mutation {
  shiftDelete(id: "SHIFT_ID") {
    ok
  }
}

13. Výpis směn

{
  shifts(
    filter: {
      since: "2026-07-01"
      till: "2026-07-31"
    }
  ) {
    edges {
      node {
        id
        since
        till
        user {
          fullName
        }
        workplace {
          name
        }
      }
    }
  }
}

14. Typ ShiftCreateInput

15. Hromadné vytvoření směn

Více směn lze vytvořit v jednom GraphQL požadavku pomocí aliasů:

mutation {
  a: shiftCreate(input: {
    workplaceId: "fb01013a"
    since: "2026-07-01T08:00:00+02:00"
    till: "2026-07-01T16:00:00+02:00"
  }) { shift { id } }

  b: shiftCreate(input: {
    workplaceId: "fb01013a"
    since: "2026-07-02T08:00:00+02:00"
    till: "2026-07-02T16:00:00+02:00"
  }) { shift { id } }
}

16. Dispatch mutation – docházkový systém

Pro napojení externích docházkových systémů existuje speciální GraphQL mutation dispatch.

Princip

Mutation přijímá JWT token podepsaný vaším privátním klíčem (RS256). Token obsahuje identifikaci uživatele a požadovanou akci. Server ověří token proti odpovídajícímu veřejnému klíči a provede operaci.

JWT formát

Header:

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "JWT"
}

Payload (claims):

{
  "iss": "nazev-systemu",
  "sub": "5b88d589-97ec-4aae-a203-5ba3dc6fa9ae",
  "personalNumber": "30479",
  "action": "presence-start",
  "parameters": "{\"checked\":true,\"message\":\"Směna zahájena\"}",
  "iat": 1695821566,
  "nbf": 1695821566,
  "exp": 1695821626
}

Popis polí

GraphQL volání

mutation {
  dispatch(input: { token: "<JWT>" }) {
    data {
      key
      value
    }
  }
}

Podporované akce

presence-start – začátek docházky

Zaznamená začátek docházky pro uživatele identifikovaného pomocí personalNumber.

{
  "checked": true,
  "message": "Směna zahájena"
}

presence-end – konec docházky

Zaznamená konec docházky.

{
  "checked": true,
  "message": "Směna ukončena"
}

Upozornění: Pole parameters v JWT payloadu je serializovaný JSON řetězec (ne objekt). Při sestavování tokenu je nutné objekt nejprve převést na string.

17. Doporučený integrační postup

1. Načíst pracoviště – workplaces
2. Načíst uživatele – users
3. Spárovat – použít externalId
4. Vytvářet směny – shiftCreate

18. Chybové stavy

19. Bezpečnost

• Token poskytuje plný přístup k účtu – ukládejte bezpečně
• Neposílejte token do frontend aplikací
• Privátní klíč (pro dispatch) uchovávejte v bezpečném prostředí (HSM / secret manager)
• Doporučená TTL tokenu pro dispatch: 60 sekund
• Veškerá komunikace probíhá výhradně přes HTTPS

20. Testování

Použijte GraphiQL Explorer pro testování dotazů:

https://preprod.smeny.cz/graphiql?token=TOKEN

21. Produkce

Produkční endpoint:

https://smeny.cz/api/graphql/?token=TOKEN