Notifikace — interní API (/internal)

Endpointy pro odesílání notifikací z backend aplikací. Vyžadují x-internal-api-key header — bez JWT tokenu.

---

POST /internal/notifications — odeslání notifikace

Odešle jednu notifikaci uživateli (email + push, dle preferencí).

POST /api/internal/notifications
x-internal-api-key: <api-key>
Content-Type: application/json

Request body

{
  "recipientEmail": "uzivatel@firma.cz",
  "appCode": "crm",
  "type": "new_task",
  "template": "default",
  "data": {
    "taskTitle": "Zavolat zákazníkovi",
    "dueDate": "2024-01-25",
    "assignedBy": "Jana Nováková"
  },
  "locale": "cs"
}

Pole	Typ	Povinné	Popis
recipientEmail	string	✓	Email příjemce
appCode	string	✓	Kód aplikace
type	string	✓	Kód notifikačního typu (skupina)
template	string	✗*	Pojmenovaná šablona pod typem. *Volitelné, když má typ jedinou šablonu (použije se automaticky); povinné, když jich má víc (400 TEMPLATE_REQUIRED). Neznámý klíč → 400 UNKNOWN_TEMPLATE (details.available).
data	object	✗	Data pro šablonu (Mustache proměnné)
locale	string	✗	Locale pro šablonu (výchozí: profil uživatele nebo "cs")

Response

{
  "success": true,
  "data": {
    "id": 123,
    "status": "sent",
    "statusReason": null
  }
}

Stav	Popis
sent	Notifikace úspěšně odeslána
failed	Odeslání selhalo (chyba SMTP/Push)
skipped	Přeskočeno — uživatel má vypnuté notifikace nebo typ neexistuje

Příklad — odeslání e-mailové notifikace

curl -X POST http://localhost:3001/api/internal/notifications \
  -H "x-internal-api-key: muj-tajny-klic" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "jan.novak@firma.cz",
    "appCode": "crm",
    "type": "task_assigned",
    "data": {
      "taskTitle": "Připravit nabídku",
      "projectName": "Projekt Alfa"
    }
  }'

---

POST /internal/notifications/bulk — hromadné odeslání

Odešle více notifikací najednou (max 100 v jednom requestu), synchronně a bez throttlingu.

Rozeslání všem / throttlovaně

Pro rozeslání jednoho typu poli uživatelů nebo všem ("all") s throttlingem a sledováním průběhu na pozadí použijte Broadcast (POST /admin/notifications/broadcast/:appCode, admin/JWT).

POST /api/internal/notifications/bulk
x-internal-api-key: <api-key>
Content-Type: application/json

Request body

{
  "notifications": [
    {
      "recipientEmail": "jan.novak@firma.cz",
      "appCode": "crm",
      "type": "daily_report",
      "data": { "reportDate": "2024-01-20" }
    },
    {
      "recipientEmail": "petra.kratka@firma.cz",
      "appCode": "crm",
      "type": "daily_report",
      "data": { "reportDate": "2024-01-20" }
    }
  ]
}

Response

{
  "success": true,
  "data": [
    { "id": 124, "status": "sent" },
    { "id": 125, "status": "skipped", "statusReason": "notifications disabled" }
  ]
}

---

GET /internal/notifications/types — typy notifikací

GET /api/internal/notifications/types?appCode=crm
x-internal-api-key: <api-key>

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "new_task",
      "name": "Nový úkol",
      "description": "Oznámení o přiřazení nového úkolu",
      "emailEnabled": true,
      "pushEnabled": true,
      "userCanDisable": true,
      "defaultEmail": true,
      "defaultPush": false
    }
  ]
}

---

GET /internal/notifications/log/:email — log příjemce

Audit log odeslaných notifikací pro konkrétního uživatele.

GET /api/internal/notifications/log/jan.novak@firma.cz
x-internal-api-key: <api-key>

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "recipientEmail": "jan.novak@firma.cz",
      "appCode": "crm",
      "type": "new_task",
      "subject": "Nový úkol: Připravit nabídku",
      "status": "sent",
      "locale": "cs",
      "createdAt": "2024-01-20T10:30:00.000Z"
    }
  ]
}

---

GET /internal/notifications/log/app/:appCode — log aplikace

GET /api/internal/notifications/log/app/crm
x-internal-api-key: <api-key>

---

Správa šablon (3 úrovně)

Zrcadlí admin endpointy (typ → pojmenovaná šablona → jazyková verze), jen přes x-internal-api-key. Kompletní popis a pravidla viz Typy, šablony a jazykové verze a Admin API.

Metoda	Cesta	Účel
GET	/internal/notifications/templates/:appCode	Všechny pojmenované šablony aplikace
GET	/internal/notifications/types/:appCode/:type/templates	Šablony pod typem (vč. locale)
POST	/internal/notifications/types/:appCode/:type/templates	Vytvoř šablonu { key, name, description?, variables? }
PUT	/internal/notifications/templates/:id	Uprav šablonu (name, description, variables)
DELETE	/internal/notifications/templates/:id	Smaž šablonu + jazykové verze (kaskáda)
GET	/internal/notifications/templates/:id/locales	Jazykové verze šablony
PUT	/internal/notifications/templates/:id/locales/:locale	Upsert verze { subjectTemplate, bodyTemplate }
DELETE	/internal/notifications/templates/:id/locales/:locale	Smaž jednu jazykovou verzi

Příklad — vytvoření šablony a její české verze:

POST /api/internal/notifications/types/crm/new_task/templates
x-internal-api-key: <api-key>
Content-Type: application/json

{ "key": "default", "name": "Nový úkol", "variables": [ { "key": "taskTitle", "required": true } ] }

PUT /api/internal/notifications/templates/42/locales/cs
x-internal-api-key: <api-key>
Content-Type: application/json

{
  "subjectTemplate": "Nový úkol: {{taskTitle}}",
  "bodyTemplate": "<h1>Byl vám přiřazen nový úkol</h1><p>{{taskTitle}}</p>"
}

---

Mustache šablony

Šablony používají Mustache-style syntaxi pro vkládání proměnných:

<!-- subjectTemplate -->
Nový úkol: {{taskTitle}}

<!-- bodyTemplate (HTML) -->
<h1>Byl vám přiřazen nový úkol</h1>
<p><strong>Úkol:</strong> {{taskTitle}}</p>
<p><strong>Projekt:</strong> {{projectName}}</p>
<p><strong>Přiřadil/a:</strong> {{assignedBy}}</p>
<p><strong>Termín:</strong> {{dueDate}}</p>

Proměnné se předávají v poli data při odesílání notifikace.

Speciální proměnné (automaticky dostupné)

Proměnná	Obsah
	Email příjemce
	Jméno aplikace
	Název brandu
	Aktuální rok

---

Jak notifikace funguje — flow

POST /internal/notifications
    │
    ├─ Existuje notifikační typ?     NE → status: "skipped"
    │
    ├─ Má uživatel profil?           NE → vytvoří se lazy
    │
    ├─ Jsou notifikace povoleny?
    │   (userAppPreference.notificationsEnabled)
    │                                NE → status: "skipped"
    │
    ├─ Preference uživatele pro typ?
    │   (userNotificationPreference.email + .push)
    │
    ├─ Email povolen?
    │   ├─ Načti šablonu pro locale uživatele
    │   ├─ Renderuj šablonu s data
    │   └─ Odešli email (SMTP + DKIM)
    │
    ├─ Push povolen?
    │   ├─ Načti všechny push subscripce uživatele
    │   └─ Odešli Web Push na každé zařízení
    │
    └─ Ulož záznam do audit logu (notifications tabulka)

Viz Notifikační systém pro kompletní dokumentaci.