JSON API

Routy, form requesty, kontroléry, resources podľa roly, filtre zoznamu cez query-builder, policy, limity požiadaviek a endpointy pre hostí — vypnuté, kým ich nezapnete:

TICKETS_ROUTES=on

• Prefix tickets.routes.prefix (api), názvy rout tickets.*, middleware tickets.routes.middleware (['api', 'auth', 'throttle:tickets-api']).
• {ticket} je číslo tiketu ([A-Z][A-Z0-9]{0,9}-[0-9]+). Kontroléry hľadajú tikety cez miesto pre modely, takže API funguje bez SubstituteBindings aj s vymeneným modelom tiketu. Soft-deleted tiket je 404, okrem obnovenia.
• Ak chcete zmeniť routu, publikujte routes/tickets.php (--tag=tickets-routes); publikovaná kópia natrvalo nahradí routy balíka.

So Sanctum

// config/tickets.php
'routes' => [
    'enabled' => env('TICKETS_ROUTES') ?: 'off',
    'middleware' => ['api', 'auth:sanctum', 'throttle:tickets-api'],
    // …
],

Rovnako funguje akýkoľvek guard (auth:api, …). Bez middleware auth by každý endpoint odpovedal anonymným volajúcim — tickets:doctor upozorní.

Limity požiadaviek

Definujú sa len pri zapnutých routách a platia, len kým je ich middleware throttle: v zozname: tickets-api povolí tickets.routes.rate_limit (120) požiadaviek za minútu na prihláseného používateľa (inak na IP); tickets-guest povolí tickets.routes.guest.rate_limit (30) za minútu na IP a tiket.

Routy

Endpoint na obnovenie kategórie neexistuje — použite Tickets::categories()->restore().

Založenie tiketu

POST /api/tickets
{
  "subject": "Printer on floor 3 is jammed",
  "description": "Paper jam error E-102.",
  "category_id": 4,
  "priority": "high",
  "channel": "web",
  "fields": {"asset_tag": "PRN-0042"},
  "project": {"type": "project", "id": 1}
}

Samoobsluha zakladá tiket pre prihláseného používateľa. subject (≤ 255), description, category_id, priority, channel, project a fields (pre neagenta len polia, ktoré smie upravovať) sú otvorené každému, kto smie zakladať. requester, guest (polia namiesto žiadateľa), assignee, due_at (po teraz), tags a watchers sú vstupy len pre agentov; riešiteľ iný ako vy vyžaduje oprávnenie assign. Polymorfné vstupy sú {type: alias, id} s aliasom z povolených zoznamov — názov triedy, neznámy alias alebo kľúč bez záznamu vráti 422. Prílohy sú multipart attachments[].

Hromadné akcie

POST /api/tickets/bulk
{"action": "transition", "tickets": ["TCK-1", "TCK-2"], "transition": "resolve", "payload": {"resolution": "Fixed"}}

action je assign (assignee alebo claim: true), unassign, transition (transition, reason?, payload?), priority (priority) alebo tags (tags.attach / tags.detach, každé najviac 50 názvov) — najviac tickets.routes.bulk.max (100) rôznych čísel. Každý tiket ide vlastnou kontrolou policy aj transakciou a zlyhanie jedného nikdy nezastaví ostatné:

{"data": [
  {"ticket": "TCK-1", "ok": true, "status": 200},
  {"ticket": "TCK-2", "ok": false, "status": 422, "code": "ticket_transition_denied", "message": "…"}
]}

Zlyhanie validácie pri jednom tikete hlási code validation_failed; každé iné zlyhanie nesie kód z tabuľky chýb (ticket_not_found pre neznáme číslo alebo tiket, ktorý používateľ vidieť nesmie). assign bez assignee a bez claim: true je 422 pre celú požiadavku.

Telá požiadaviek

Uploady (attachments[], file) sa cez media-library riadia mime typmi a limitom veľkosti svojej skupiny — tickets.attachments.* pre súbory tiketu, comments.media.* z balíka comments pre súbory správ — najviac 10 súborov na požiadavku.

Admin endpointy

Preložiteľný text (name, description, label, help, popis možnosti) je reťazec v aktuálnom jazyku alebo mapa jazykov (objekt s kľúčmi en, sk, …). Polymorfné vstupy sú {type: alias, id}; filtre zoznamov berú alias:key.

Resources

Podľa roly: divák je agent (oprávnenie agenta a rozsah agentov mu tiket povoľujú), žiadateľ, účastník (sledujúci) alebo hosť (cez podpísaný odkaz).

Osoby (žiadateľ, riešiteľ, autor, aktér, sledujúci) sa zobrazujú svojím aliasom z povolených zoznamov, nikdy názvom triedy: agenti dostanú {type, id, name}; ostatní {type, name}, pričom name je null pre hosťa, ktorý nie je samotným divákom. Žiadatelia nikdy neuvidia interné poznámky, zadržané odpovede, interné aktivity, last_activity_at, štítky ani zoznamy sledujúcich a meta hostiteľa sa neobjaví v žiadnom resource. Hodnoty enumov prichádzajú s preloženým popisom a farbou, takže klient vykreslí odznak bez vlastných tabuliek:

"status":   {"value": "pending", "label": "Waiting on requester", "category": "waiting", "color": "amber"},
"priority": {"value": "high", "label": "High", "weight": 30, "color": "orange"},
"channel":  {"value": "web", "label": "Web", "color": "blue"}

Telá odpovedí

Zoznam tiketov — filtre, radenie, stránkovanie

GET /tickets je query-builder-for-laravel nad visibleTo($user); každý filter je jeden zo scopes modelu Ticket:

Filtre len pre agentov — tag, requester=alias:key a pole, ktoré nie je viditeľné pre žiadateľa — nájdu len tikety, na ktorých diváka nechá pracovať rozsah agentov. Neznámy filter alebo radenie vráti 400 pri query-builder.mode.unknown_filter = reject (predvolené); ignore ich zahodí.

Radenie: created_at, updated_at, due_at, number, priority (váhy enumu) a pre agentov last_activity_at. Predvolene -last_activity_at pre agentov a -created_at pre ostatných. Stránkovanie: per_page (predvolene 20, najviac tickets.routes.max_per_page) a page; zoznam načíta kategóriu, riešiteľa, žiadateľa, štítky a počty správ vopred, v pevnom počte dopytov.

Chyby

Mapujú sa v kontroléroch balíka — nikdy vo vašom exception handleri — na {message, code}. Chyby konfigurácie zostávajú 500: opraviť ich musí hostiteľ, nie klient.