Funebrio REST API — dokumentace pro vývojáře

Verze: v1 · Stav: produkční · Posledně aktualizováno: 2026-05-11

Tento dokument popisuje veřejné REST API pohřební platformy Funebrio určené pro integraci s externími systémy (webové formuláře, ERP, účetní software, mobilní aplikace, …).

API je dostupné pro tenantty s aktivovanou funkcí API přístup v nastavení licence.

1. Přehled

• Protokol: HTTPS
• Formát: JSON (request i response)
• Autentizace: Bearer token (Laravel Sanctum)
• Verzování: v URL — aktuálně /api/v1/
• Rate limit: 60 požadavků / minutu / token

Base URL

https://{tenant}.funebrio.cz/api/v1

{tenant} je subdoména konkrétního zákazníka (např. pohrebnisluzba-novak.funebrio.cz).

2. Autentizace

Každý požadavek musí obsahovat HTTP hlavičku:

Authorization: Bearer {api_token}
Accept: application/json

Tokeny vystavuje administrátor tenantta v UI Nastavení → API. Při vytvoření API uživatele se token zobrazí jednorázově — uložte si jej okamžitě na bezpečné místo, znovu jej nelze získat.

Důležité

• Token je vázaný na konkrétního API uživatele, nikoliv na reálnou osobu.
• Každý API uživatel se započítává do limitu uživatelů podle licenčního plánu.
• API uživatel nemůže být použit pro přihlášení do webového rozhraní.
• Token lze v UI kdykoliv obnovit (původní přestane fungovat) nebo smazat.

Příklad ověření

curl https://demo.funebrio.cz/api/v1/me \
  -H "Authorization: Bearer 1|abc123xyz..." \
  -H "Accept: application/json"

Odpověď:

{
  "data": {
    "id": 42,
    "name": "Web objednávky",
    "role": "api"
  }
}

3. Chybové stavy

Formát chybové odpovědi

Validační chyba (422):

{
  "message": "The first name field is required.",
  "errors": {
    "first_name": ["The first name field is required."]
  }
}

Autorizační chyba (401 / 403):

{
  "error": "api_disabled",
  "message": "API přístup není v aktuálním plánu aktivní."
}

Možné kódy: api_disabled, invalid_token.

4. Paginace

Endpointy vracející kolekce podporují paginaci přes query parametry:

Odpověď obsahuje meta blok:

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 50,
    "total": 127
  }
}

5. Endpointy

5.1 Zemřelí

GET /deceased — seznam zemřelých

Query parametry:

Příklad:

curl https://demo.funebrio.cz/api/v1/deceased?search=Novak \
  -H "Authorization: Bearer {token}"

Odpověď:

{
  "data": [
    {
      "id": 12,
      "first_name": "Jan",
      "last_name": "Novák",
      "birth_number": "5301011234",
      "date_of_birth": "1953-01-01",
      "date_of_death": "2026-04-15",
      "place_of_death": "Praha",
      "gender": "male",
      "workflow_step": "Příprava obřadu",
      "created_at": "2026-04-16T08:32:00+02:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
}

GET /deceased/{id} — detail zemřelého

Vrací rozšířený set polí včetně adresy, obřadu, pohřbení a poznámek.

Odpověď:

{
  "data": {
    "id": 12,
    "first_name": "Jan",
    "last_name": "Novák",
    "birth_number": "5301011234",
    "date_of_birth": "1953-01-01",
    "date_of_death": "2026-04-15",
    "place_of_death": "Praha",
    "gender": "male",
    "address": "Hlavní 1, 110 00 Praha",
    "workflow_step": "Příprava obřadu",
    "ceremony_at": "2026-04-22T10:00:00+02:00",
    "ceremony_place": "Krematorium Strašnice",
    "burial_type": "cremation",
    "burial_at": "2026-04-22",
    "burial_place": "Hřbitov Olšany",
    "coffin_id": "K-2026-042",
    "notes": "Rodina si přeje květiny pouze bílé.",
    "created_at": "2026-04-16T08:32:00+02:00"
  }
}

POST /deceased — vytvoření záznamu

Tělo požadavku:

Příklad:

curl -X POST https://demo.funebrio.cz/api/v1/deceased \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Marie",
    "last_name": "Dvořáková",
    "date_of_death": "2026-05-08",
    "place_of_death": "Brno",
    "gender": "female"
  }'

Odpověď: 201 Created s objektem data (stejný formát jako GET).

PUT /deceased/{id} · PATCH /deceased/{id} — úprava

Všechna pole jsou volitelná (sometimes). Posílejte pouze ta, která chcete změnit.

Editovatelná pole navíc:

• ceremony_at (datetime)
• ceremony_place (string)
• burial_at (date)
• burial_place (string)

5.2 Objednávky

GET /orders — seznam objednávek

Query parametry: status (new, confirmed, completed, cancelled), per_page.

Odpověď:

{
  "data": [
    {
      "id": 88,
      "customer_name": "Tomáš Marný",
      "customer_email": "tomas@example.cz",
      "status": "new",
      "deceased": { "id": 12, "first_name": "Jan", "last_name": "Novák" },
      "total_with_vat": 28500.00,
      "invoice_number": null,
      "created_at": "2026-05-10T14:21:00+02:00"
    }
  ],
  "meta": { ... }
}

GET /orders/{id} — detail objednávky

Vrací navíc položky objednávky (items), součty bez DPH (total_without_vat), DPH (total_vat) a interní poznámky.

{
  "data": {
    "id": 88,
    "customer_name": "Tomáš Marný",
    "customer_address": "Hlavní 1, Praha",
    "customer_phone": "+420 777 123 456",
    "customer_email": "tomas@example.cz",
    "status": "new",
    "deceased": { "id": 12, "first_name": "Jan", "last_name": "Novák" },
    "total_without_vat": 23553.72,
    "total_vat": 4946.28,
    "total_with_vat": 28500.00,
    "invoice_number": null,
    "notes": "Doručit do pondělí",
    "items": [
      {
        "id": 201,
        "product_id": 15,
        "name": "Rakev dubová",
        "quantity": 1,
        "unit_price": 18000.00,
        "vat_rate": 21
      }
    ],
    "created_at": "2026-05-10T14:21:00+02:00"
  }
}

POST /orders — vytvoření objednávky

Tělo:

Poznámky k cenám: Cena položky se ukládá jako snapshot v okamžiku vytvoření objednávky (cena z ceníku produktu). Pozdější změna ceníku už objednávku neovlivní.

Stav nové objednávky je vždy new.

Příklad:

curl -X POST https://demo.funebrio.cz/api/v1/orders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Tomáš Marný",
    "customer_address": "Hlavní 1, Praha",
    "customer_email": "tomas@example.cz",
    "deceased_id": 12,
    "items": [
      { "product_id": 15, "quantity": 1 },
      { "product_id": 22, "quantity": 4 }
    ]
  }'

PUT /orders/{id} · PATCH /orders/{id} — úprava

Lze měnit zákaznická data, stav, poznámky. Položky se přes API nyní upravovat nedají (pouze přes webové UI).

5.3 Faktury (read-only)

GET /invoices — seznam faktur

Query parametry:

Odpověď:

{
  "data": [
    {
      "id": 55,
      "invoice_number": "2026-00088",
      "customer_name": "Tomáš Marný",
      "deceased": { "id": 12, "first_name": "Jan", "last_name": "Novák" },
      "issued_at": "2026-05-10",
      "due_at": "2026-05-24",
      "paid_at": null,
      "total_with_vat": 28500.00,
      "status": "pending"
    }
  ],
  "meta": { ... }
}

Stavy: paid, overdue, pending.

GET /invoices/{id} — detail faktury

Vrací navíc notes, sent_at (kdy byla odeslána zákazníkovi e-mailem), order_id.

5.4 Produkty (read-only)

GET /products — seznam produktů

Vrací pouze aktivní produkty (skryté/archivované nejsou dostupné přes API).

Query parametry:

Odpověď:

{
  "data": [
    {
      "id": 15,
      "name": "Rakev dubová",
      "description": "Masivní dubová rakev s polstrováním",
      "category": "Rakve",
      "price": 18000.00,
      "vat_rate": 21,
      "price_with_vat": 21780.00,
      "unit": "ks",
      "active": true
    }
  ],
  "meta": { ... }
}

GET /products/{id} — detail produktu

Stejný formát jako položka v seznamu.

6. Use case: webová objednávka pohřbu

Typický scénář pro integraci s veřejným webem pohřební služby.

Krok 1: Načtení dostupných produktů

GET /api/v1/products?category_id=3

Krok 2: Vytvoření záznamu zemřelého (volitelně, jinak lze přiložit později)

POST /api/v1/deceased

Krok 3: Vytvoření objednávky s položkami

POST /api/v1/orders

V odpovědi přijde id objednávky a kalkulace cen. Administrátor pohřební služby objednávku v interním systému dokončí, vystaví fakturu a kontaktuje zákazníka.

7. Časová pásma a formáty

• Datumy: ISO 8601 YYYY-MM-DD
• Datum + čas: ISO 8601 s timezone YYYY-MM-DDTHH:MM:SS+02:00
• Měna: vždy CZK, čísla jako decimal s 2 desetinnými místy
• Texty: UTF-8

8. Bezpečnost a doporučení

• Token nikdy nevkládejte do veřejně přístupného frontend kódu. Volání API ze klientského JavaScriptu vyžaduje server-side proxy.
• Token rotujte alespoň jednou ročně (přes UI Nastavení → API → Obnovit token).
• Logujte chyby 4xx/5xx na své straně, zejména 429 (rate limit) — implementujte exponenciální backoff.
• Citlivá data: API vrací osobní údaje zemřelých a zákazníků. Nakládejte s nimi v souladu s GDPR.

9. Limity a omezení

10. Plánované funkce

• OpenAPI / Swagger specifikace pro automatické generování klientů
• Webhooks (notifikace při změně stavu objednávky)
• Endpoint pro stažení PDF faktury

11. Podpora

Při potížích s integrací kontaktujte vašeho account managera (kontakt je v aplikaci v sekci Podpora) nebo napište na podpora@funebrio.cz.