Открытый API
Назначение
Сервис обеспечивает интеграцию Dinext с внешними системами через программный интерфейс (REST API). Позволяет вызывать whitelisted-методы, читать и создавать документы, выполнять отчеты и автоматизировать обмен данными.
Цели и задачи
- Предоставлять доступ к данным и операциям по HTTP (REST).
- Вызывать разрешенные (whitelisted) методы из внешних систем и скриптов.
- Интегрировать Dinext с учетными системами, порталами, скриптами и сервисами.
- Обеспечивать аутентификацию (токен, API key) и контроль доступа по ролям.
- Документировать и поддерживать стабильные эндпоинты для партнеров и интеграций.
Для кого
- Разработчики интеграций и внешних систем.
- Администраторы, настраивающие API-ключи и права.
- Партнеры и заказчики, подключающие свои системы к Dinext.
- Пользователи скриптов и автоматизации (вызов API из командной строки или сервисов).
Основные понятия
- REST API — интерфейс по HTTP: GET (чтение), POST (создание/действия), PUT/PATCH (обновление), DELETE (удаление при поддержке).
- Whitelisted method — метод, явно разрешенный для вызова извне; без whitelist вызов из API может быть запрещен из соображений безопасности.
- Токен / API key — средство аутентификации запроса (например, API Key в заголовке или токен OAuth).
- тип документа API — доступ к документам по путям вида
/api/resource/тип документаи/api/resource/тип документа/name.
Основные сущности / объекты
- Dinext — REST API и whitelisted methods (init.py, app.py и маршруты).
- Аутентификация: логин по
/api/method/login, использование сессии или токена в последующих запросах.
Основные сценарии / процессы
Аутентификация
- Отправить POST на
/api/method/loginс полямиusrиpwd(или использовать API Key / OAuth при настройке). - Получить cookie сессии или токен в ответе; использовать в заголовках последующих запросов.
- Для долгоживущих интеграций предпочтительно использовать API Key или токен с ограниченным сроком действия по политике компании.
Чтение и запись документов
- GET
/api/resource/тип документа— список документов (с параметрами filters, fields, limit). - GET
/api/resource/тип документа/name— один документ по имени. - POST
/api/resource/тип документа— создание документа (тело JSON с полями). - PUT
/api/resource/тип документа/name— обновление документа. - Ответы в JSON; права доступа применяются так же, как для текущего пользователя сессии/токена.
Вызов методов
- POST
/api/method/путь.к.методус телом запроса (аргументы в JSON). - Метод должен быть whitelisted в коде приложения ` и разрешение на вызов).
- Использовать для сложных операций: отчеты, массовые действия, бизнес-логика.
Правила и ограничения
- Только whitelisted-методы доступны для вызова из API; остальные возвращают ошибку доступа.
- Права на документы и методы определяются пользователем, от имени которого выполняется запрос (сессия/токен).
- Лимиты запросов (rate limiting) могут быть настроены на веб-сервере или в приложении; учитывайте при проектировании интеграций.
- Не передавайте учетные данные в URL; используйте заголовки и HTTPS.
Результаты / отчетность
- Успешные ответы API (JSON с данными или статусом).
- Журналы доступа и ошибок на стороне сервера для отладки и аудита интеграций.
Типовые вопросы и ошибки (FAQ)
Ошибка 403 при вызове метода
Метод не в whitelist или у пользователя нет прав на его выполнение. Добавьте декоратор @Dinext.whitelist() в коде и назначьте права роли; при вызове от имени пользователя убедитесь, что у него есть нужная роль.
Как передать фильтры в GET /api/resource/тип документа?
Используйте query-параметры: filters=[["field","=","value"]], fields=["field1","field2"], limit_page_length=20. Синтаксис в документации Dinext REST API.
Где настраивается API Key?
В зависимости от версии: в профиле пользователя (Generate Keys) или в отдельном тип документа для API Keys. Используйте ключ в заголовке (например, Authorization: token key:secret) вместо логина по паролю для скриптов и сервисов.