Přeskočit na hlavní obsah

API Přehled

DnA Cruises API je RESTful API postavené na Cloudflare Workers.

Základní URL​

  • Development: https://dev.api.dna.cruises
  • Production: https://api.dna.cruises

Dočasné URL (před nastavením vlastních domén):

  • Development: https://dna-cruises-api-dev.dnasound.workers.dev
  • Production: https://dna-cruises-api.dnasound.workers.dev

Prostředí​

API endpointy / a /health vrací informaci o prostředí:

{
  "name": "DnA Cruises API",
  "version": "1.0.0",
  "environment": "development" // nebo "production"
}

Autentizace​

Systém je uzavřený - bez účtu a autentizace nelze pracovat s daty. Všechny endpointy kromě těch nutných pro autentizaci vyžadují JWT token v Authorization headeru:

Authorization: Bearer <token>

Veřejné endpointy (bez autentizace): Tyto endpointy jsou jediné, které nevyžadují autentizaci, protože jsou nutné pro přihlášení:

  • POST /auth/bootstrap - inicializace admin účtu
  • POST /auth/login - přihlášení pomocí emailu a hesla
  • GET /auth/google - OAuth přesměrování
  • GET /auth/google/callback - OAuth callback
  • POST /auth/passkey/login/start - zahájení přihlášení pomocí passkey
  • POST /auth/passkey/login/finish - dokončení přihlášení pomocí passkey
  • POST /auth/2fa/verify - 2FA verifikace
  • POST /auth/2fa/resend - opětovné odeslání SMS kódu
  • GET /files/public/:token - veřejný přístup k souborům přes token

Všechny ostatní endpointy vyžadují autentizaci. Pokud token chybí nebo je neplatný, endpoint vrátí 401 Unauthorized. Bez platného účtu a tokenu není možné přistupovat k žádným datům systému.

Formát odpovědi​

Všechny API odpovědi mají následující formát:

{
  "success": true,
  "data": { ... },
  "message": "Volitelná zpráva"
}

Nebo v případě chyby:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Chybová zpráva"
}

Endpointy​

Health & Info​

  • GET / - API info a prostředí
  • GET /health - Kontrola zdraví s prostředím a časovou značkou

Autentizace​

  • POST /auth/bootstrap - Inicializace admin účtu
  • POST /auth/login - Přihlášení pomocí emailu a hesla
  • POST /auth/logout - Odhlášení
  • GET /auth/me - Informace o aktuálním uživateli
  • POST /auth/password - Změna hesla
  • POST /auth/passkey/register/start - Zahájení registrace passkey
  • POST /auth/passkey/register/finish - Dokončení registrace passkey
  • POST /auth/passkey/login/start - Zahájení přihlášení pomocí passkey
  • POST /auth/passkey/login/finish - Dokončení přihlášení pomocí passkey
  • GET /auth/passkeys - Seznam passkeys uživatele
  • PUT /auth/passkeys/:id - Přejmenování passkey
  • DELETE /auth/passkeys/:id - Smazání passkey
  • POST /auth/2fa/setup - Nastavení 2FA (TOTP nebo SMS)
  • POST /auth/2fa/enable - Aktivace 2FA
  • POST /auth/2fa/disable - Deaktivace 2FA
  • POST /auth/2fa/verify - Ověření 2FA kódu během přihlášení
  • POST /auth/2fa/resend - Opětovné odeslání SMS kódu
  • GET /auth/google - Zahájení Google OAuth
  • GET /auth/google/callback - OAuth callback

Items a Assets​

  • GET /items - Seznam items (paginace)
  • GET /items/:id - Získání itemu
  • POST /items - Vytvoření itemu (Admin)
  • PUT /items/:id - Aktualizace itemu (Admin)
  • DELETE /items/:id - Smazání itemu (Admin)
  • GET /categories - Seznam všech kategorií
  • GET /assets - Seznam assets (paginace, zobrazuje item_name, owner_id, weight_kg, defects)
  • GET /assets/scan/:scan_id - Vyhledání assetu podle scan_id
  • POST /assets - Vytvoření assetu (Admin)
  • PUT /assets/:id - Aktualizace assetu (Admin)
  • DELETE /assets/:id - Smazání assetu (Admin)

Projects​

  • GET /projects - Seznam projektů (paginace)
  • GET /projects/:id - Získání projektu
  • POST /projects - Vytvoření projektu (Producer, Admin)
  • PUT /projects/:id - Aktualizace projektu (Producer, Admin)
  • DELETE /projects/:id - Smazání projektu (Producer, Admin)

Kits​

Globální kity (pouze Admin):

  • GET /kits/global - Seznam globálních kitů
  • GET /kits/global/:id - Získání globálního kitu s členy
  • GET /kits/global/scan/:scan_id - Vyhledání kitu podle scan_id
  • POST /kits/global - Vytvoření globálního kitu
  • PUT /kits/global/:id - Aktualizace globálního kitu
  • DELETE /kits/global/:id - Smazání globálního kitu
  • POST /kits/global/:id/members/assets - Přidání/odebrání assetu z kitu
  • POST /kits/global/:id/members/items - Nastavení množství itemu v kitu

Projektové kity (Producer, Admin):

  • GET /projects/:id/kits - Seznam projektových kitů
  • GET /projects/:id/kits/:kitId - Získání projektového kitu s řádky
  • POST /projects/:id/kits - Vytvoření projektového kitu
  • PUT /projects/:id/kits/:kitId - Aktualizace projektového kitu
  • DELETE /projects/:id/kits/:kitId - Smazání projektového kitu
  • POST /projects/:id/kits/:kitId/lines - Přidání/odebrání/nastavení qty řádku v kitu

Nakládací sessiony​

  • GET /load-sessions - Seznam load sessions (s volitelným filtrem podle statusu)
  • POST /projects/:id/load-sessions - Vytvoření load session
  • GET /load-sessions/:id - Získání load session
  • GET /load-sessions/:id/plan - Získání plánu nakládky s rozřešenými daty
  • GET /load-sessions/:id/status - Získání statusu session (missing/extra)
  • POST /load-sessions/:id/scan - Zpracování skenu (asset, global kit, project kit)
  • POST /load-sessions/:id/scan/confirm - Potvrzení skenu (asset mimo plán, global kit bulk)
  • POST /load-sessions/:id/plan/add - Přidání položky do plánu
  • POST /load-sessions/:id/plan/remove - Odebrání položky z plánu
  • POST /load-sessions/:id/qty - Změna množství itemu (add/remove/set)
  • POST /load-sessions/:id/close - Uzavření load session

Files​

  • POST /files/upload - Nahrání souboru (s podporou project folder structure)
  • GET /files - Seznam souborů (paginace, filtrování podle entity_type a entity_id)
  • GET /files/:id/download - Stažení souboru (autentizovaný nebo veřejný přístup)
  • PUT /files/:id/public - Vygenerování veřejného tokenu pro sdílení
  • DELETE /files/:id/public - Zrušení veřejného sdílení
  • DELETE /files/:id - Smazání souboru
  • GET /files/public/:token - Veřejný přístup k souboru (bez autentizace)

Inventory​

  • GET /inventory/sessions - Seznam inventurních sessions (paginace)
  • POST /inventory/sessions - Vytvoření inventurní session
  • GET /inventory/sessions/:id/records - Získání záznamů inventury pro session
  • POST /inventory/sessions/:id/scan - Skenování assetu pro inventuru
  • POST /inventory/sessions/:id/close - Uzavření inventurní session

Audit log​

  • GET /audit - Dotazování audit logu s filtrováním a paginací

Users (pouze Admin)​

  • GET /users - Seznam uživatelů
  • GET /users/search - Vyhledání uživatelů
  • GET /users/:id - Získání uživatele
  • POST /users - Vytvoření uživatele
  • PUT /users/:id - Aktualizace uživatele
  • DELETE /users/:id - Smazání uživatele

Nasazení​

API je automaticky nasazeno přes Cloudflare Workers Builds:

  • Production: Automaticky při push do main branch
  • Development: Automaticky při push do dev branch

Bindings (D1, R2, environment variables) se automaticky přenášejí z wrangler.toml při každém deployi.