Первый запрос за пять минут

API бесплатен на всех тарифах. Отдельная подписка на API не нужна: действуют доступ компании, права, ограничения модулей и общие квоты нагрузки. Ключ выдаётся для одной компании и не открывает чужие проекты. Владелец компании управляет токенами, а разработчик получает от него токен для своей интеграции.

1. Владелец выбирает нужную компанию и открывает «Настройки → Интеграции и API». Только владелец видит список токенов, создаёт и отзывает их; роль администратора или доступ к настройкам этого права не дают.
2. Владелец создаёт отдельный ключ для системы: «1С — производство», «CRM» или «BI». Оставьте только read, пока интеграция ничего не изменяет, и задайте срок действия.
3. Владелец сохраняет токен в защищённом хранилище секретов и сам передаёт его разработчику по защищённому каналу. Токен показывается только при создании; передавайте полное значение, а не короткий префикс из списка.
4. Разработчик открывает /api-console без входа в кабинет компании, вставляет токен и нажимает «Добавить токен». В настройках новый ключ подключается к консоли автоматически и хранится только в памяти страницы.
5. Нажмите «Проверить токен»: консоль выполнит GET /v1/me. Проверьте companyId и scopes. До проверки или отправки запроса обращений к данным нет; вход в кабинет не заменяет токен.
6. Выполните GET /v1/capabilities для возможностей и квот, GET /v1/projects?limit=10 для данных. Сверьте результат с компанией в интерфейсе.

Как работать с API с помощью ИИ

Нажмите «Скачать инструкции для ИИ» в настройках API или в этом руководстве. Прикрепите Markdown-файл к чату с ИИ и опишите задачу: получить данные, подготовить запросы или разработать приложение. В файле есть порядок работы, примеры, ограничения и правила безопасной интеграции.

Инструкция не содержит ключей и данных компании. Не добавляйте в неё токен и не отправляйте секрет в чат. Разработчик настраивает токен отдельно в защищённой среде приложения; ИИ пишет код с переменной SMETRUM_API_TOKEN. Перед использованием новых методов нужно сверяться с актуальной OpenAPI-схемой своего сервера.

Каталог методов API

Каталог загружается из OpenAPI именно этого сервера. Найдите ресурс или метод, раскройте строку и проверьте параметры, поля, ответы и разрешённые операции. Кнопка «Проверить в консоли» переносит метод и путь без токена; значения {id} и других параметров замените своими.

Наличие метода в каталоге не даёт права на операцию. Для записи дополнительно нужны scope write, поддержка операции самим ресурсом и проверки бизнес-правил.

Авторизация и права

Используйте HTTPS и заголовок Authorization: Bearer TOKEN. Для совместимых серверных клиентов поддерживаются X-API-Key и X-Smetrum-Api-Key. Передавайте ровно один способ авторизации; не помещайте ключ в URL, тело запроса, публичный JavaScript или журналы.

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

• Только текущий владелец компании может видеть список токенов, создавать и отзывать ключи. Сотрудники, администраторы компании и приглашённые разработчики не получают эти права через роль или матрицу разрешений.
• Создавайте отдельный ключ для каждой интеграции и среды. По умолчанию выбран только read.
• В компании допускается до 20 неотозванных ключей. Истёкший или замороженный ключ занимает место до отзыва. Между созданиями выдерживайте не менее 10 секунд.
• Срок действия можно задать при создании; максимум 366 дней. В API управления срок задаётся ISO 8601 с часовым поясом. Пустой срок означает отсутствие автоматического истечения.
• При ротации создайте новый ключ, переключите интеграцию, проверьте /v1/me и отзовите старый. Удалённый или потерянный токен восстановить нельзя.
• Создание и отзыв ключей выполняются только из сессии владельца с CSRF-защитой. Сам API-ключ не может создавать новые ключи, читать список ключей или повышать свои права.
• При смене владельца ключи, выпущенные прежним владельцем, перестают проходить авторизацию. Новый владелец должен выпустить и передать интеграторам новые ключи.

Контроль и остановка доступа

Администратор сервиса контролирует использование API в разделе админки «Токены»: статистику запросов, ошибки, исчерпание квот и предупреждения о повышенной нагрузке. Предупреждение — повод проверить интеграцию, а не доказательство атаки. Само значение секрета из списка токенов получить нельзя.

Статистика хранится дневными агрегатами за 30 дней по UTC: количество запросов, успешные ответы, ошибки, 401/403/429/5xx, объём данных и среднее время. Учитываются запросы после распознавания известного ключа; это не полный журнал сетевого трафика. Тексты запросов и ответов и секреты в эту статистику не записываются.

В реестре сигнал появляется при использовании не менее 80% минутной или суточной квоты, не менее 10 ответах 401/403/429/5xx за сутки либо доле ошибок от 25% при хотя бы 50 запросах. При стандартных квотах 80% — это 48 запросов в минуту или 8 000 в сутки. Подборка вверху показывает до 10 токенов с высокой суточной нагрузкой или повторяющимися ошибками; минутную квоту и долю ошибок проверяйте в реестре. Автоматической заморозки из-за этих сигналов нет: решение принимает администратор сервиса.

Весь контур приложения

Интеграция строится вокруг бизнес-ресурсов, а не прямого доступа к базе. Начните с GET /v1/capabilities и GET /v1/collections: сервер сообщает поддерживаемые ресурсы и разрешённые способы работы. Названия, поля и ограничения конкретного метода проверяйте в актуальной OpenAPI-схеме.

Виджеты и их данные

GET /v1/widgets возвращает каталог виджетов, apiMode, available, methods, recordsPath и ограничения. Проверяйте эти поля, а не наличие виджета на экране. Права и доступность модуля продолжают действовать.

Для disk, spreadsheets, electronic-documents и floor-plans поддерживается чтение доступных метаданных: GET /v1/widgets/{widget}/records и GET /v1/widgets/{widget}/records/{id}. Список принимает limit, skip и необязательный projectId. По умолчанию 25 записей, максимум 100. Переходите к следующей странице по meta.nextSkip, пока он не равен null: пустая страница возможна из-за фильтрации прав и не означает конец списка.

Заметки и калькуляторы, которые хранят данные локально в браузере, обозначаются local: серверу нечего выгружать. Защищённые виджеты, например ИИ и почта, обозначаются restricted: каталог не предоставляет их секреты и содержимое.

GET /v1/widgets/disk/records?limit=25&projectId=PROJECT_ID
Authorization: Bearer YOUR_TOKEN

Запросы, ответы и пагинация

Базовый адрес — https://smetrum.ru/v1. Формат — JSON в UTF-8. GET читает список или одну запись; POST создаёт, PATCH/PUT изменяет, DELETE удаляет только там, где это явно разрешено контрактом. У GET нет тела. Для записи нужен Content-Type: application/json и Idempotency-Key.

Успешный список содержит ok, data и meta; запись — ok и data. Обрабатывайте HTTP-статус до использования данных. Не считайте пустой массив ошибкой: у текущего ключа может не быть доступных записей.

Для обычных ресурсов limit по умолчанию равен 50, максимум 100; skip — от 0 до 10000. Выберите устойчивую сортировку, например sort=_id. Используйте meta.nextSkip для следующего skip и остановитесь, когда nextSkip равен null. Сервер просматривает порцию записей, затем фильтрует её по правам; короткая и даже пустая data не означает конец. Чтение нескольких страниц не является снимком базы: записи могут измениться между запросами.

filter — URL-кодированный JSON-объект. Поддерживаются безопасные сравнения $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists и логические $and, $or, $nor. Регулярные выражения, $where, $expr, произвольные операторы и исполняемый код запрещены. sort — имя поля, -имя для обратного порядка или JSON до четырёх полей.

const url = new URL('https://smetrum.ru/v1/projects');
url.searchParams.set('limit', '50');
url.searchParams.set('skip', '0');
url.searchParams.set('sort', '_id');
// Используйте поле, поддерживаемое выбранным ресурсом.
url.searchParams.set('filter', JSON.stringify({name: 'Мой проект'}));

REST, совместимость и браузер

Для новых интеграций используйте REST /v1. Существующие серверные клиенты могут применять POST /api.php с JSON-командами find, findOne, insert, update и delete. Этот режим проверяет те же права, ресурсы и квоты, не поддерживает произвольные MongoDB-команды, массовые изменения, count или sum. Ответ совместимости имеет поле data, без конверта ok/meta.

Для записи в совместимом режиме нужен Idempotency-Key в заголовке либо idempotencyKey в JSON. Наличие POST само по себе не делает find операцией записи. Этот интерфейс не предназначен для произвольных portal-api маршрутов или неописанных команд приложения.

Серверные интеграции не зависят от CORS. Для обращений из другого браузерного origin нужен явно разрешённый администратором origin; универсального разрешения * нет. CORS не заменяет авторизацию. Предпочитайте свой серверный посредник, чтобы секрет компании не попадал посетителю сайта.

POST /api.php
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"op":"find","col":"projects","options":{"limit":10}}

Примеры: cURL, JavaScript, Python, 1С

Замените идентификаторы на свои. Примеры обращаются к рабочим данным компании: для экспериментов используйте отдельную тестовую компанию. Переменная SMETRUM_API_TOKEN должна поступать из хранилища секретов среды исполнения. Не сохраняйте её значение в репозитории.

curl --fail-with-body --max-time 30 \
  'https://smetrum.ru/v1/projects?limit=10&sort=_id' \
  -H "Authorization: Bearer ${SMETRUM_API_TOKEN}" \
  -H 'Accept: application/json'

# Сохраните этот идентификатор вместе с исходящим заданием.
# При повторе ТОГО ЖЕ запроса используйте ТОТ ЖЕ ключ.
curl --fail-with-body --max-time 30 \
  'https://smetrum.ru/v1/counterparties' \
  -H "Authorization: Bearer ${SMETRUM_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: crm-counterparty-20260831-0001' \
  --data '{"name":"Тестовый контрагент"}'

const token = process.env.SMETRUM_API_TOKEN;
if (!token) throw new Error('Не задан API-токен');
const response = await fetch('https://smetrum.ru/v1/projects?limit=10', {
  headers: {Authorization: `Bearer ${token}`, Accept: 'application/json'},
  redirect: 'error',
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(`HTTP ${response.status}; Retry-After=${retryAfter ?? '—'}`);
}
const result = await response.json();
// Передайте result.data в свою бизнес-логику.
// Не записывайте заголовок Authorization и полные данные в журналы.

import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
from urllib.error import HTTPError

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = Request(
    'https://smetrum.ru/v1/projects?limit=10',
    headers={
        'Authorization': 'Bearer ' + os.environ['SMETRUM_API_TOKEN'],
        'Accept': 'application/json',
    },
)
try:
    with build_opener(NoRedirect).open(request, timeout=30) as response:
        result = json.load(response)
        # Обработайте result['data']; не журналируйте секреты.
except HTTPError as error:
    # Для 429 учтите Retry-After, для 401/403 исправьте доступ.
    raise RuntimeError('HTTP ' + str(error.code)) from None

// Токен получите из защищённого хранилища вашей конфигурации.
// Выполняйте на сервере, не на клиентском рабочем месте.
Соединение = Новый HTTPСоединение(
    "smetrum.ru", 443, , , , 30,
    Новый ЗащищенноеСоединениеOpenSSL());
Запрос = Новый HTTPЗапрос("/v1/projects?limit=10");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Запрос.Заголовки.Вставить("Accept", "application/json");
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
    Чтение = Новый ЧтениеJSON;
    Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
    Данные = ПрочитатьJSON(Чтение);
    Чтение.Закрыть();
Иначе
    // Разберите код и Retry-After. Не повторяйте запись вслепую.
    ВызватьИсключение "API HTTP " + Строка(Ответ.КодСостояния);
КонецЕсли;

Запись, повторы и синхронизация

Каждый POST, PUT, PATCH и DELETE к ресурсам требует Idempotency-Key: строку длиной 8–160 символов из букв A–Z/a–z, цифр и . _ : -. Сформируйте её один раз для одного логического действия и сохраните вместе с заданием до отправки. При сетевом таймауте повторите тот же метод, путь, тело и ключ; новый ключ означает новое действие.

Одинаковый ключ нельзя использовать для другого тела или операции. При 409 прочитайте код ошибки: конфликтующий запрос нельзя исправлять слепой генерацией нового ключа. Срок хранения защиты от повторов ограничен; перед повтором старых заданий сверяйте наличие записи в вашей системе и СМЕТРУМ.

Синхронизация должна вести соответствие внешних и внутренних идентификаторов и очередь заданий. Для получения изменений периодически читайте ограниченные выборки, сохраняйте собственную отметку обработки и устраняйте дубликаты у себя. Публичные исходящие webhook-подписки, OAuth, GraphQL, WebSocket и массовые транзакции не входят в этот контракт.

• При 401/403 остановите автоматические повторы: сначала исправьте ключ, срок или права.
• При 429 дождитесь Retry-After; при временных сетевых ошибках используйте ограниченное число повторов с растущей задержкой и случайной добавкой.
• Запись повторяйте только с исходным Idempotency-Key. После неоднозначного результата сначала проверьте, что операция не выполнилась.
• Не опрашивайте все ресурсы раз в секунду. Используйте небольшие порции, кэш своего приложения, очередь и не более нескольких одновременных запросов.

Квоты и защита от нагрузки

Бесплатный API не означает неограниченные запросы. Сервер учитывает нагрузку по ключу и компании; дополнительные ключи не обходят общий лимит компании. Лимиты могут быть настроены администратором, поэтому актуальные значения берите из /v1/capabilities и заголовков ответа. Ниже — исходные значения конфигурации.

Ошибки и диагностика

Для обращения в поддержку сохраните время, метод, путь без секретных параметров, HTTP-статус, безопасный текст ошибки и идентификатор запроса из ответа, если он есть. Не прикладывайте API-токен, заголовок Authorization, финансовые выгрузки и персональные данные. Консоль показывает ответ именно вашего запроса; по нему проще проверить права и формат.

Статус добавленного, но ещё не проверенного токена означает только наличие значения в памяти страницы. Нажмите «Проверить токен»: действительность подтверждает успешный ответ /v1/me и статус «Доступ подтверждён». При 401 проверьте, что вставлен полный токен без кавычек и слова Bearer; префикс из таблицы не подходит. Если срок и статус верны, проверьте передачу заголовка Authorization через сервер или прокси; не переносите секрет в URL ради обхода ошибки.

Как устроена API-консоль

Консоль доступна разработчику, которому владелец компании передал токен: учётная запись, роль сотрудника и вход в кабинет не нужны. Сама страница не раскрывает данные без успешной авторизации. Только владелец управляет токенами в настройках. Новый ключ автоматически подставляется во встроенную консоль; на отдельной странице /api-console разработчик вставляет его вручную.

Слева выбираются пример, метод, относительный путь, тело JSON и ключ идемпотентности. Справа видны HTTP-статус, время, размер, тело и заголовки ответа. Предпросмотр и копируемая команда скрывают токен. Консоль не использует авторизацию открытой сессии и отправляет запрос только после нажатия кнопки.

Ключ остаётся в памяти страницы, не сохраняется в URL, localStorage, sessionStorage или истории запросов. Перезагрузка, закрытие либо кнопка «Забыть» очищают его в консоли. Тело ответа может содержать конфиденциальные данные: не показывайте экран посторонним и используйте «Очистить» в ответе сервера перед записью видео.

Для изменяющего запроса требуется отдельное подтверждение. Кнопка отмены останавливает ожидание в браузере, но уже отправленная операция могла выполниться на сервере. Это рабочий API, не песочница и не откат транзакции.

Что делать нельзя

• Нельзя использовать ключ другой компании или подставлять чужие companyId, projectId и связанные документы.
• Нельзя обходить роли, права на финансовые данные, ограничения модуля, подписи, согласования, проведение документов и складские инварианты прямой записью.
• Нельзя передавать ключ в браузерный код публичного сайта, мобильное приложение для всех клиентов, URL, аналитические события, внешние отладчики и общие логи.
• Нельзя отправлять произвольные MongoDB-операторы, исполняемый код, файловые пути, внутренние идентификаторы доступа и служебные поля.
• Нельзя подключаться к внутренним маршрутам приложения как к стабильному публичному API. Совместимость api.php ограничена теми же правилами и не является способом обойти /v1.
• Нельзя создавать дополнительные ключи для обхода квот, устраивать массовый перебор или нагрузочные испытания рабочего сервера без согласования.
• Нельзя считать бесплатность API разрешением на экспорт любых данных: соблюдайте права пользователей, договорённости вашей компании и правила обработки персональных данных.