JA2 DocsPřihlásit se

JÁ² Backoffice — API Documentation

Status (13.5.2026): Backoffice je teď interní tool pro JÁ² tým. User-facing Context Store byl odstraněn — žije v akademii (apps/akademie/) jako "Studio" workspace. Per-user data se automaticky migrovala (viz supabase/migrations/20260513000002_migrate_context_store_to_studio.sql).

Backoffice MCP je nyní pure-admin: CRM, support, check-in, integrace, skills knihovna. list_files / read_file / write_file / delete_file / search_files tooly odstraněny.

Overview

Backoffice slouží JÁ² týmu (David, Honza, Eva, Petra, Martin) pro:

  • CRM — customers, happenings, check-in, FAPI / SmartEmailing / Affilbox / Quiz pages integrace
  • Support inbox — Gmail-backed unified tickets, AI drafts
  • Admin — /admin/uzivatele (správa userů + rolí), /admin/roles (permissions matrix), happenings settings, voucher mappings, brigádníci přístup
  • Skills knihovna — sdílené AI skills přes MCP skill_list / skill_get

Vztah k akademii

| App | Doména | Pro koho | Per-user kontext | |---|---|---|---| | apps/web (backoffice — toto) | ja2.davidkirs.cz | Interní tým | žádný — bez user files | | apps/akademie | akademie.davidkirs.cz | Koncoví uživatelé | 3-tier sloty + Studio workspace |

Obě sdílí Supabase DB, ale každá má vlastní MCP server:

  • Backoffice MCP: /api/mcp — REST tools pro interní agenty (skills, crm, support, check-in, integrace, users)
  • Akademie MCP: /api/mcp — JSON-RPC 2.0 dispatcher (18 tools: 11 context + 7 Studio)

Pro propojení vlastního Claude / Cursor s vlastním kontextem použij akademii (akademie.davidkirs.cz/api/mcp). Backoffice MCP je primárně pro internal agent workflows.

Quick Start (interní tým)

1. Get an API Token

  1. Sign in na backoffice
  2. Settings → API Tokens
  3. Click New Token, name it (např. "Skill bootstrap")
  4. Copy — token shown only once

2. Connect Your AI Agent

{
  "mcpServers": {
    "ja2-backoffice": {
      "url": "https://ja2.davidkirs.cz/api/mcp",
      "token": "cs_your-token-here"
    }
  }
}

3. Available tool modules

Po odstranění Context Store je backoffice MCP rozdělen do těchto modulů (viz lib/mcp/index.ts):

| Modul | Role | Co dělá | |---|---|---| | skills | public | bootstrap, skill_list, skill_get — vstupní point pro AI agenta | | crm | admin | Customers, entitlements, attributions | | happenings | admin | Event CRUD, products | | team | admin | Team roles, internal people | | checkin | admin | Check-in ops, dev seed | | integrations | admin | FAPI / Affilbox / SmartEmailing sync | | users | admin | Whitelist + module access | | support | admin | Support inbox CRUD + reply |

File-system tools (list_files, read_file, …) byly odstraněny. User-facing kontext žije v akademii (Studio + sloty).

API Endpoints

MCP

| Endpoint | Auth | Description | |----------|------|-------------| | POST /api/mcp | Bearer token | MCP protocol endpoint pro internal AI agents | | GET /api/health | None | Server health check | | GET /api/docs | None | This documentation (raw Markdown) | | GET /api/docs/mcp | None | MCP tools documentation |

CRM / Quiz integration

| Endpoint | Auth | Description | |----------|------|-------------| | POST /api/webhooks/quiz | X-Webhook-Secret | Lead push z externích quiz pages (4 zdroje) | | GET /api/crm/leads | Bearer CRM_API_KEY | List leads (pagination, since, source filter) | | GET /api/crm/leads/[leadId] | Bearer | Single lead detail | | GET /api/crm/leads/[leadId]/report | Bearer | AI report pokud ready | | GET /api/crm/health | None | Health check |

FAPI / Webhooks

| Endpoint | Auth | Description | |----------|------|-------------| | POST /api/webhooks/fapi | Secret v URL query | FAPI events (paid invoice, voucher used) | | POST /api/webhooks/smartemailing | Bearer | SE batch events (open, click, unsubscribe) |

/api/webhook/github-sync byl odstraněn z backoffice. Auto-sync Studio souborů žije v akademii: apps/akademie/src/app/api/webhooks/github-sync/.

Authentication

MCP tokens (backoffice)

Authorization: Bearer cs_your-token-here

SHA-256 hashed v api_tokens.token_hash. Tokeny per user. Multiple tokens, individually revocable.

CRM API

Authorization: Bearer <CRM_API_KEY>

Single shared secret pro pull integrace (quiz API serverem). Read-only.

Webhook secrets

URL query nebo X-Webhook-Secret header. Timing-safe compare proti env.

More Documentation

  • Backoffice-specific:
  • Akademie protějšek (pro user-facing context):
    • apps/akademie/src/docs/index.md — entry point
    • apps/akademie/src/docs/mcp.md — JSON-RPC 2.0 dispatcher + 18 tools
    • apps/akademie/src/docs/studio.md — power-user workspace + index API
    • apps/akademie/src/docs/permissions.md — sdílené RBAC schema

Změny 13.5.2026 (Context Store removal)

Backoffice Context Store byl kompletně odstraněn ze user-facing app:

  • ❌ /store route (file-tree editor) — smazán
  • ❌ /api/export (ZIP download) — smazán
  • ❌ /api/webhook/github-sync — smazán, port v akademii
  • ❌ /settings/github — smazán, port v akademii
  • ❌ 5 MCP tools (list_files, read_file, write_file, delete_file, search_files)
  • ❌ lib/store/, lib/github/, components/store/ — smazáno
  • ✅ Data zachovaná v DB (context_files table zůstává jako backup, drop přijde po verifikaci)
  • ✅ Auto-migrace data do user_context_files(scope='workspace') proběhla migrací 20260513000002_migrate_context_store_to_studio.sql

Co to znamená pro tým: pokud jsi měl/a obsah ve /store, najdeš ho v akademii Studio (/studio route, ikona FolderTree v sidebaru). Potřebuješ akademie.workspace permission — admin (*) ji má automaticky.