# Digio API — обзор проекта

В репозитории лендинга несколько **независимых контрактов**. Не смешивайте ключи и сессии между ними.

| Контракт | Базовый путь | Аутентификация | Документация |
|----------|--------------|----------------|--------------|
| **Public API v1** | **`https://api.{домен}/v1/`** (канон) · `/api/v1/` на apex (legacy) | `dg_live_*` / `DIGIO_API_DEV_KEY` | Этот файл + [OpenAPI](../api/v1/openapi.json) |
| **Site JSON API** | **`https://api.{домен}/`** (канон) · `/api/` на apex (legacy) | Cookie `PHPSESSID` после login/register | Раздел ниже |
| **Billing (agent stack)** | `/api/billing-*.php` | `X-Digio-Billing-Secret` | Раздел ниже + [API агентов](./API_АГЕНТОВ.md) |
| **OAuth (браузер)** | `/oauth/` | Редиректы провайдеров | [OAUTH_SETUP.md](../OAUTH_SETUP.md) |
| **Конфиг для UI** | `window.DIGIO_OAUTH` | Публичные поля (без секретов) | Раздел ниже |

**OpenAPI (только v1):** [`/api/v1/openapi.json`](../api/v1/openapi.json)  
**Agent API (run/stop):** [API_АГЕНТОВ.md](./API_АГЕНТОВ.md)

---

# Public API v1

REST API для внешних интеграций: каталог тарифов и моделей, оценка стоимости токенов, проверка реферальных кодов и (по серверному ключу) снимок кошелька workspace.

**Канонический хост API:** `https://api.{домен}` (переменная `DIGIO_API_ORIGIN`, локально `https://api.digio.ok`)  
**Public API v1:** `https://api.{домен}/v1/`  
**Версия:** `1.0.0`  
**Формат:** JSON, UTF-8

Пути на apex (`https://{домен}/api/…`) сохранены для обратной совместимости с сайтом. Внешние сервисы в будущем должны ходить на **api-поддомен** и передавать ключ (`Authorization: Bearer` или `X-Digio-Api-Key`). Проверка ключа для session-эндпоинтов пока **не включена** — только для защищённых методов v1 (`usage-estimate`, `account-wallet`, `me`).

---

## Быстрый старт

```bash
# Проверка доступности (API subdomain)
curl -sS "https://api.digio.ok/v1/health.php"

# Каталог (без ключа)
curl -sS "https://api.digio.ok/v1/catalog.php"

# Оценка списания (нужен API-ключ)
curl -sS -X POST "https://api.digio.ok/v1/usage-estimate.php" \
  -H "Authorization: Bearer dg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"claude-sonnet-4-6","input_tokens":12000,"output_tokens":800}'
```

Локально (после `npm run build`):

```bash
php -S 127.0.0.1:8080 -t dist
export DIGIO_API_DEV_KEY=dg_dev_local_test
curl -sS "http://127.0.0.1:8080/api/v1/health.php"
```

`health.php` в ответе отдаёт актуальные URL `docs` и `openapi` для текущего origin.

---

## Аутентификация (v1)

| Тип эндпоинта | Ключ |
|---------------|------|
| Публичные (`health`, `catalog`, `locales`, `referrals-validate`) | Не требуется |
| Защищённые (`usage-estimate`, `account-wallet`, `me`) | Обязателен |

```http
Authorization: Bearer dg_live_xxxxxxxx
```

или

```http
X-Digio-Api-Key: dg_live_xxxxxxxx
```

### Настройка ключей (сервер)

`DIGIO_API_KEYS` — JSON-массив:

```json
[
  {
    "key": "dg_live_partner_abc123",
    "name": "Partner CRM",
    "scopes": ["usage", "billing", "meta"],
    "user_id": 42
  }
]
```

| Поле | Описание |
|------|----------|
| `key` | Секрет (только server-to-server) |
| `name` | Метка для аудита |
| `scopes` | `usage`, `billing`, `meta`; `*` / `all` — все защищённые методы |
| `user_id` | Опционально: привязка для `account-wallet` |

Разработка: `DIGIO_API_DEV_KEY=dg_dev_only_on_localhost`

### Scopes (v1)

| Scope | Эндпоинты |
|-------|-----------|
| `usage` | `POST /usage-estimate.php` |
| `billing` | `GET /account-wallet.php` |
| `meta` | `GET /me.php` |

---

## Общий формат ответа (v1)

Успех: `{ "ok": true, "api_version": "1.0.0", "request_id": "…", … }`  
Ошибка: `{ "ok": false, "error": "…", "message": "…", … }`

| HTTP | `error` | Значение |
|------|---------|----------|
| 400 | `invalid_json`, `invalid_*` | Неверные параметры |
| 401 | `unauthorized` | Нет или неверный API-ключ |
| 403 | `forbidden` | Нет scope / чужой `user_id` |
| 405 | `method_not_allowed` | Неверный HTTP-метод |
| 503 | `db_not_configured` | БД не настроена (только v1 public) |
| 500 | `server` | Внутренняя ошибка |

CORS: `Access-Control-Allow-Origin: *` (без cookies). Для продакшена вызывайте **с бэкенда партнёра**.

---

## Эндпоинты Public API v1

### `GET /health.php`

Проверка живости. Поля: `service`, `status`, `time_utc`, `docs`, `openapi`.

### `GET /catalog.php`

Публичный каталог: `plans`, `token_packs`, `ai_models[]` (`id`, `provider`, `pricing_per_million_usd` с `input` / `output` / `cached_input`), `pricing_notes` (`token_markup` 1.15, `min_charge_usd`, …).

**Единый конфиг (тарифы моделей и URL эндпоинтов):** [`config/public-api.json`](../config/public-api.json)  
При `npm run build` в `dist` копируются тот же файл и снимок для статики / `file://`: [`assets/data/public-api-catalog.json`](../assets/data/public-api-catalog.json).  
Страница **Digio Tokens** (`tokens.html`) подключает `tokens-page.js`: сначала live `catalog.php`, при ошибке или при открытии через `file://` — JSON-снимок.

### `GET /locales.php`

Коды языков UI: `locales[]` с `code`, `label`; `count`.

### `POST /usage-estimate.php`

Оценка списания Digio Tokens (scope `usage`).

| Поле | Тип | Обязательно |
|------|-----|-------------|
| `model_id` | string | да |
| `input_tokens` | int | нет (0) |
| `output_tokens` | int | нет (0) |
| `cached_input_tokens` | int | нет (0) |

Ответ: `estimate` с `cost_provider_usd`, `digio_charge_usd` (наценка 15%, минимум $0.01 при output > 0).

### `GET /referrals-validate.php`

Проверка invite-кода **без сессии**.

**Query:** `code` или `invite_code` (a-z, 0-9, `_`, `-`, до 64 символов)

```json
{
  "ok": true,
  "code": "abc12def34",
  "valid": true
}
```

Без БД: `valid: null`, `db_configured: false`.

### `GET /account-wallet.php`

Снимок кошелька (scope `billing`, server-to-server). Query `user_id` если ключ не привязан к пользователю.

### `GET /me.php`

Метаданные API-ключа (scope `meta`).

---

# Site JSON API (`/api/`)

Эндпоинты **сайта** с cookie-сессией. Базовый URL: `https://digio.me/api/` (локально `http://127.0.0.1:8080/api/`).

**Сессия:** после `POST /auth-login.php` или `POST /auth-register.php` браузер получает `PHPSESSID`.  
`GET /auth-me.php` **не** создаёт сессию без cookie (чтобы статические страницы не раздавали лишние `PHPSESSID`).

| Метод | Путь | Auth | Назначение |
|-------|------|------|------------|
| `GET` | `auth-me.php` | Cookie (опционально) | Текущий пользователь `{ user }` или `401` |
| `POST` | `auth-login.php` | — | Вход: `email`, `password`, `captcha` |
| `POST` | `auth-register.php` | — | Регистрация: `name`, `email`, `password`, `captcha`, опц. `referral_code` |
| `GET` | `auth-logout.php` | Cookie | Редирект на главную (302) |
| `POST` | `validate-captcha.php` | — | Проверка капчи для форм |
| `POST` | `quiz.php` | — | Демо-квиз на лендинге (CORS `*`) |
| `GET` | `referral-me.php` | Cookie + БД | **Рекомендуется:** код, ссылка, баланс рефералки |
| `GET` | `referral-ledger.php` | Cookie + БД | Баланс + `entries[]`; query `limit` (1–100) |
| `GET` | `referral-dashboard.php` | Cookie + БД | Агрегат (legacy); предпочтите `referral-me` + `referral-ledger` |
| `GET` | `billing-account.php` | Cookie + БД | Кошелёк, ledger, каталог для UI pricing |
| `POST` | `billing-checkout.php` | Cookie + БД | Оформление плана / пакета |
| `POST` | `billing-cancel.php` | Cookie + БД | Отмена подписки |
| `POST` | `billing-reset-demo.php` | Cookie + БД | Сброс демо-кошелька (dev) |
| `GET`/`POST` | `billing-wallet.php` | `X-Digio-Billing-Secret` | Снимок кошелька для agent-api |
| `POST` | `billing-debit-usage.php` | `X-Digio-Billing-Secret` | Списание usage после run агента |

### `GET /referral-me.php` (профиль рефералки)

```json
{
  "ok": true,
  "invite_code": "ABC12DEF",
  "register_url": "https://digio.me/register/?ref=ABC12DEF",
  "referral_balance_cents": 2500,
  "commission_percent": 10,
  "min_payout_cents": 5000
}
```

Используется страницей `referral` (`assets/js/referral-page.js`). URL регистрации строится через `digio_register_invite_url()` (учитывает `.html` в `dist/`).

### Ошибки Site API

| HTTP | `error` | Когда |
|------|---------|--------|
| 401 | `unauthorized` | Нет сессии или БД не настроена (session API) |
| 400 | `invalid_json`, `captcha`, … | Валидация формы |
| 503 | `db_not_configured` | Login/register без `DIGIO_DB_*` |
| 405 | `method_not_allowed` | Неверный метод |

---

# OAuth и `window.DIGIO_OAUTH`

Соцвход (Google, Apple, Telegram) настраивается в **`config/social-auth.php`** (копируется в `dist/config/`). Секреты только на сервере; см. [OAUTH_SETUP.md](../OAUTH_SETUP.md).

### Публичный объект в браузере

На `login.php` / `register.php` и в статическом `dist` после сборки:

```html
<script>window.DIGIO_OAUTH={...};</script>
```

Собирается `digio_oauth_public_json()` (`config.php` → `lib/SocialAuthConfig.php`). При `npm run build` подставляется через `scripts/export-social-auth-public.php`.

| Поле | Описание |
|------|----------|
| `googleClientId` | Client ID (пусто если `google.enabled` = false) |
| `googleRedirectUri` | Callback URL |
| `appleClientId` | Services ID |
| `appleRedirectUri` | Callback URL |
| `telegramBotUsername` | @бот |
| `telegramAuthUrl` | `…/oauth/telegram-callback.php` |

Переопределение env: `DIGIO_GOOGLE_CLIENT_ID`, `DIGIO_PUBLIC_ORIGIN`, … — таблица в OAUTH_SETUP.

### Маршруты OAuth (GET, редиректы)

| Путь | Назначение |
|------|------------|
| `/oauth/google-start.php` | Старт Google OAuth |
| `/oauth/google-callback.php` | Callback Google |
| `/oauth/apple-start.php` | Старт Sign in with Apple |
| `/oauth/apple-callback.php` | Callback Apple |
| `/oauth/telegram-callback.php` | Callback Telegram Login Widget |

После успеха — сессия и редирект в продукт; ошибки — query `social=…` (см. `assets/js/auth-oauth.js`).

---

# Billing secret (agent stack)

Для agent-api и внутренних списаний:

```http
X-Digio-Billing-Secret: <DIGIO_BILLING_DEBIT_SECRET>
```

| Эндпоинт | Метод | Тело / query |
|----------|-------|----------------|
| `billing-wallet.php` | GET | `user_id` |
| `billing-wallet.php` | POST | JSON `{ "user_id": 42 }` |
| `billing-debit-usage.php` | POST | JSON с `user_id`, поля usage (см. `BillingAccount::debitUsage`) |

Публичный аналог кошелька для партнёров: `GET /api/v1/account-wallet.php` с `dg_live_*` (другой auth).

---

# Сборка и статика

- `npm run build` копирует `api/`, `oauth/`, `config/social-auth.php`, `docs/` → `dist/`.
- Маркетинговые ссылки предпочитают `*.html` в `dist/` (`digio_marketing_page_path()`).
- Превью `file://`: CSS через `assets/js/file-protocol.js` в `<head>`; OAuth на статике — только если в HTML вшит актуальный `DIGIO_OAUTH`.

---

# Ограничения и roadmap

- Rate limiting v1 — на reverse proxy; ограничивайте клиент.
- Webhooks для партнёров — не в v1.
- Создание/Run задач агентов — [Agent API](./API_АГЕНТОВ.md), не Public API v1.

По ключам Public API: [digio.me](https://digio.me).