Clients API

Client data is read from ClickHouse (CDM tables). All endpoints require JWT authentication.

List Clients

Returns all active applications (client contracts) from ClickHouse.

GET /api/v1/clients

Example

curl http://localhost:8081/api/v1/clients \
  -H "Authorization: Bearer $TOKEN"

Response (200)

{
  "data": [
    {
      "application_key": "APP-001",
      "customer_key": "CUST-001",
      "application_name": "Acme Support",
      "deal_type": "SUP",
      "deal_amount": 15000000.00,
      "monthly_limit": 40.0,
      "hourly_rate": 150000.00,
      "currency": "UZS",
      "invoice_amount": 0
    },
    {
      "application_key": "APP-002",
      "customer_key": "CUST-002",
      "application_name": "GlobalCorp Development",
      "deal_type": "HR",
      "deal_amount": 0,
      "monthly_limit": 0,
      "hourly_rate": 50.00,
      "currency": "USD",
      "invoice_amount": 5000.00
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 20
  }
}

---

Get Client Details

Returns application details with customer information and contacts.

GET /api/v1/clients/:key

Example

curl http://localhost:8081/api/v1/clients/APP-001 \
  -H "Authorization: Bearer $TOKEN"

Response (200)

{
  "data": {
    "application": {
      "application_key": "APP-001",
      "customer_key": "CUST-001",
      "application_name": "Acme Support",
      "deal_type": "SUP",
      "deal_amount": 15000000.00,
      "monthly_limit": 40.0,
      "hourly_rate": 150000.00,
      "currency": "UZS"
    },
    "customer": {
      "customer_key": "CUST-001",
      "company_name": "Acme Corporation",
      "company_type": "LLC",
      "tin": "123456789",
      "swift_bic": "",
      "signer_full_name": "John Director",
      "country": "UZ"
    },
    "contacts": [
      {
        "name": "Jane Manager",
        "email": "[email protected]",
        "phone": "+998901234567"
      }
    ]
  }
}

---

Get Client Worklogs

Returns raw worklogs for a client in a date range.

GET /api/v1/clients/:key/worklogs

Query Parameters

Parameter	Required	Description
from	Yes	Start date (YYYY-MM-DD)
to	Yes	End date (YYYY-MM-DD)

Example

curl "http://localhost:8081/api/v1/clients/APP-001/worklogs?from=2026-02-01&to=2026-02-28" \
  -H "Authorization: Bearer $TOKEN"

Response (200)

{
  "data": [
    {
      "issue_key": "PROJ-123",
      "issue_summary": "Fix login page timeout",
      "issue_type_name": "Bug",
      "priority_name": "P3",
      "time_spent_seconds": 7200,
      "started": "2026-02-15T10:00:00Z"
    },
    {
      "issue_key": "PROJ-124",
      "issue_summary": "Weekly standup",
      "issue_type_name": "Meeting",
      "priority_name": "P4",
      "time_spent_seconds": 1800,
      "started": "2026-02-15T09:00:00Z"
    }
  ]
}

Notes

• Worklogs are fetched from ClickHouse (tempo.worklogs_flat joined with jira.jira_issues)
• Results are filtered by the application's project labels
• Data freshness depends on n8n sync (~15 minute delay)
• The time_spent_seconds is the raw duration (before minimum billable rounding)

---

Client Invoice Configs

Per-client invoice defaults (display toggles, legal text template, numbering counter). Stored in PostgreSQL client_invoice_config table.

List All Configs

GET /api/v1/client-configs

Response (200)

{
  "data": [
    {
      "application_key": "APP-001",
      "default_show_task_list": true,
      "default_show_tracked_time": true,
      "default_show_task_pricing": false,
      "default_show_overtime": true,
      "default_legal_text": "Стороны подтверждают...",
      "last_invoice_number": 7
    }
  ]
}

---

Get Config

GET /api/v1/client-configs/:key

Returns the config for a specific application. Returns 404 if no config exists yet.

---

Update Config

PATCH /api/v1/client-configs/:key

Creates the config with defaults if it doesn't exist yet (upsert semantics).

Request

{
  "default_show_task_list": false,
  "default_legal_text": "Updated legal text template...",
  "last_invoice_number": 10
}

All fields are optional. Only provided fields are updated.

Response (200)

Returns the full updated config.

Notes

• last_invoice_number is the seed for per-client numbering. The next generated invoice will be last_invoice_number + 1.
• Display toggle defaults are copied to each new invoice at generation time.
• default_legal_text is copied to each new invoice and can be overridden per-invoice.