API Faktera

Только чтение. Те же цифры, что в кабинете, с указанием файла и строки, откуда они взялись. Входит в тариф «Компания» и выше.

Базовый адресhttps://faktera.uz/api/v1

Спецификация OpenAPI 3.1

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

1. Откройте «Настройки, API-доступ» и создайте ключ. 2. Передайте его в заголовке Authorization. 3. Запросите показатели за месяц.

curl -s https://faktera.uz/api/v1/kpis?period=2026-09 \
  -H "Authorization: Bearer $FAKTERA_API_KEY"

Открыть настройки API

Аутентификация

Каждый запрос подписывается ключом в заголовке Authorization. Ключ принадлежит одной компании: другую компанию через него открыть нельзя, идентификатор компании в запросе не передаётся.

Формат ключа

fkt_AbCd1234_<43 base62 characters>

fkt_ + 8 символов префикса + 43 символа секрета. По префиксу мы находим ключ, секрет храним только в виде хеша SHA-256 и показываем один раз при создании.

Храните ключ на сервере. Браузерные запросы с чужих сайтов запрещены (CORS отключён) и не должны использоваться: ключ в браузере виден всем.

Ключ можно привязать к IP-адресам или сетям (CIDR) и ограничить сроком действия. Отозванный ключ перестаёт работать сразу.

Права ключа

У каждого ключа свой набор прав. Метод без нужного права отвечает 403 insufficient_scope. Метод /me доступен любому действующему ключу.

Показатели18 KPI, разбивки и исходные документы
read:kpi
Вклад департаментовЧто изменило выручку, прибыль, поступления
read:contributions
ДебиторкаКто должен и сколько, по срокам
read:receivables
ДеньгиБанковские движения и категории
read:cash
КлиентыТоп, новые и ушедшие клиенты
read:customers
ПрогнозПрогноз денег на 13 недель
read:forecast
Качество данныхСвежесть источников, сверка, ошибки импорта
read:quality

Форматы данных

Деньги: Десятичная строка, например "1250000.00", без округления до float. Все суммы в узбекских сумах (UZS); документы в валюте пересчитаны по курсу ЦБ.
Даты и периоды: Даты в формате ISO 8601 (2026-09-30). Период это календарный месяц в формате YYYY-MM; без параметра period берётся месяц последней продажи.
Постраничная выдача: Списки отдают page.nextCursor. Передайте его в параметре cursor, чтобы получить следующую страницу; null означает, что страниц больше нет.
Происхождение данных: У каждого показателя есть evidence (fact, calc, stat, model: уровень достоверности) и status (ok, incomplete, proxy, stale, no_data). Метод /kpis/{code}/documents возвращает строки-источники с именем файла и номером строки.
Заголовки ответа: Cache-Control: no-store, X-Request-Id (назовите его в поддержке при вопросах), X-RateLimit-*.

{
  "code": "revenue",
  "unit": "uzs",
  "currency": "UZS",
  "value": "3000000.00",
  "previous": "2500000.00",
  "deltaPct": "20.00",
  "status": "ok",
  "evidence": "fact"
}

Лимиты

запросов в минуту на ключ

запросов подряд (всплеск)

60 запросов в минуту на ключ, всплеск до 20 запросов подряд. При превышении возвращается 429 и заголовок Retry-After со временем ожидания в секундах.

Заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (время в секундах Unix, когда лимит восстановится полностью) приходят в каждом ответе.

Серия неверных ключей с одного адреса тоже ограничивается и попадает в журнал аудита компании.

Ошибки

Ошибка всегда имеет вид JSON с тремя полями. Код стабилен, текст сообщения предназначен для разработчика.

{
  "code": "insufficient_scope",
  "message": "This key lacks the \"read:cash\" scope.",
  "details": { "required": "read:cash" }
}

HTTP	Код	Когда
401	`invalid_api_key`	Ключа нет, он неверного формата или неизвестен
401	`api_key_revoked`	Ключ отозван
401	`api_key_expired`	Срок действия ключа истёк
402	`plan_upgrade_required`	Тариф компании не включает API
403	`insufficient_scope`	У ключа нет нужного права
403	`ip_not_allowed`	Запрос пришёл с IP вне списка ключа
404	`not_found`	Нет такого метода, показателя или данных
422	`validation_error`	Неверные параметры; в details перечислены поля
429	`rate_limited`	Превышен лимит запросов

Методы

Все методы: GET, ответ в JSON. Параметры, которых нет в описании, отклоняются с кодом 422.

GET/api/v1/meПраво: любой ключ
Компания, тариф и права вашего ключа.
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/me"
```
GET/api/v1/kpisПраво: read:kpi
18 показателей за месяц: значение, изменение к прошлому месяцу, статус, уровень достоверности и свежесть источников.
Параметры: period=YYYY-MM, compare=prev|none
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/kpis?period=2026-09&compare=prev"
```
GET/api/v1/kpis/{code}/breakdownПраво: read:kpi
Показатель в разрезе клиентов или товаров, со сравнением с прошлым месяцем.
Параметры: period, by=counterparty|product, limit, cursor
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/kpis/revenue/breakdown?period=2026-09&by=counterparty"
```
GET/api/v1/kpis/{code}/documentsПраво: read:kpi
Строки отчётов, из которых сложен показатель: файл, номер строки, документ, сумма.
Параметры: period, counterparty, product, cursor
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/kpis/revenue/documents?period=2026-09"
```
GET/api/v1/contributionsПраво: read:contributions
Вклад департаментов в изменение выручки, валовой прибыли или поступлений.
Параметры: period, metric=revenue|gross_profit|receipts
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/contributions?period=2026-09&metric=revenue"
```
GET/api/v1/receivables/agingПраво: read:receivables
Дебиторка по срокам просрочки и по должникам на дату среза.
Параметры: as_of=YYYY-MM-DD, limit, cursor
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/receivables/aging?as_of=2026-09-30"
```
GET/api/v1/cash/flowsПраво: read:cash
Банковские движения и итоги по категориям за период до 366 дней.
Параметры: from, to, direction=in|out, cursor
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/cash/flows?from=2026-09-01&to=2026-09-30"
```
GET/api/v1/forecastПраво: read:forecast
Недельный прогноз денег (модель): приток, отток, диапазон остатка и кассовые разрывы.
Параметры: weeks=1..13
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/forecast?weeks=13"
```
GET/api/v1/customersПраво: read:customers
Топ, новые или ушедшие клиенты месяца.
Параметры: period, segment=top|new|churned, limit, cursor
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/customers?period=2026-09&segment=top"
```
GET/api/v1/qualityПраво: read:quality
Свежесть источников, сверка дебиторки, пропуски курсов, состояние импортов.
```
curl -s -H "Authorization: Bearer $FAKTERA_API_KEY" \
  "https://faktera.uz/api/v1/quality"
```

Версионирование

Версия указана в адресе: /api/v1. Внутри версии мы только добавляем: новые поля в ответах, новые необязательные параметры и новые методы. Ваш код должен игнорировать неизвестные поля.

Несовместимые изменения выходят только в новой версии (/api/v2). Предыдущая версия работает не меньше 12 месяцев после выхода новой, о сроках мы предупреждаем владельцев ключей письмом за 6 месяцев.

Текущая спецификация всегда доступна по адресу /api/v1/openapi.json.