Документация API для модуля SenDev: Инозапрет 168-ФЗ

Страница «Документация API» предназначена для настройки и использования программного интерфейса модуля. Она нужна в тех случаях, когда модуль должен использоваться не только через административный интерфейс, но и из внешних систем, скриптов или интеграций.

На этой странице можно:

включить или выключить API;
создать или пересоздать API-ключ;
посмотреть адрес API;
узнать, как передавать авторизацию;
посмотреть доступные методы API;
использовать готовые примеры запросов;
ознакомиться с возможными ошибками.

Эта страница в первую очередь полезна администраторам и специалистам, которые настраивают интеграцию модуля с другими системами.

[Скриншот 1: Статус API, ключ и адрес подключения]

Когда использовать страницу

Страница особенно полезна в следующих случаях:

когда нужно подключить модуль к внешней системе;
при настройке автоматической проверки текста, файлов или страниц;
при передаче результатов проверки в другой сервис;
при тестировании API;
при замене или отзыве API-ключа.

Что находится на странице

Страница состоит из нескольких основных блоков:

управление API;
аутентификация;
правила вызова API;
описание доступных методов;
примеры запросов;
описание ошибок;
пример клиентского подключения.

Управление API

В верхней части страницы расположен блок управления API.

В этом блоке пользователь может:

Посмотреть статус API

Показывает, доступен ли API в данный момент.

Включить или выключить API

Позволяет управлять доступностью API.

Если API выключен, внешние системы не смогут выполнять запросы к модулю.

Посмотреть API-ключ

API-ключ используется для авторизации при обращении к API.

Скопировать API-ключ

Позволяет быстро скопировать ключ для передачи в настройки внешней системы.

Создать или пересоздать API-ключ

Используется, если ключ ещё не был создан или если нужно заменить действующий ключ.

Важно учитывать, что после пересоздания старый ключ перестаёт работать.

Адрес API

На странице также отображается адрес API, который определяется автоматически для текущей установки.

Это тот адрес, по которому внешняя система должна отправлять запросы к модулю.

На странице могут быть показаны:

основной адрес API;
вариант с HTTPS;
вариант с HTTP.

Для пользователя это означает, что не нужно искать путь вручную — система показывает его прямо в интерфейсе.

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

В блоке «Аутентификация» описано, как передавать API-ключ при запросах.

Обычно поддерживаются несколько способов передачи ключа:

через заголовок запроса;
через параметр запроса;
через тело запроса;
через данные в формате JSON.

Для практической работы рекомендуется использовать тот способ, который указан на странице как предпочтительный.

Как правильно вызывать API

На странице отдельно выделены правила работы с API.

Основная идея этого блока — помочь избежать типовых ошибок при подключении.

Здесь объясняется, что:

API принимает только запросы определённого типа;
параметры можно передавать разными способами;
некоторые запросы нужно отправлять не через обычное открытие ссылки, а через корректный программный вызов;
при наличии защищённого подключения лучше использовать HTTPS-адрес.

Этот раздел особенно полезен на этапе первой настройки интеграции.

Доступные методы API

На странице приведено описание основных методов API, которые поддерживает модуль.

Проверка текста

Используется для проверки произвольного текста и получения списка найденных совпадений.

Этот метод подходит, когда внешний сервис должен отправить текст на проверку без участия пользователя в административной панели.

Проверка страницы по адресу

Используется для загрузки страницы по адресу и проверки её содержимого.

Этот метод удобен, когда нужно проверить отдельную страницу сайта автоматически.

Проверка файла

Используется для передачи файла в API и анализа его текстового содержимого.

Подходит для интеграций, где документы проверяются автоматически после загрузки.

Информация о сервисе

Используется для получения общей информации о состоянии API и его возможностях.

Такой запрос удобен для диагностики и проверки доступности сервиса.

Примеры запросов

Для каждого метода на странице приведены готовые примеры запросов.

Обычно здесь показываются:

пример вызова из командной строки;
пример на PHP;
пример передачи данных в формате JSON;
пример ответа API.

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

Пример ответа API

На странице также показывается пример структуры ответа API.

Из него можно понять:

успешно ли выполнен запрос;
сколько найдено совпадений;
какие слова были обнаружены;
какой контекст вернулся в ответе;
какие настройки использовались при проверке.

Этот блок полезен при подключении внешней системы, чтобы правильно обработать результат запроса.

Коды ошибок

На странице есть отдельный раздел с кодами ошибок.

Он помогает понять, почему запрос не выполнился. Например:

API отключено;
передан неверный ключ;
использован неверный тип запроса;
не передан обязательный параметр;
словарь не готов к работе;
не удалось загрузить страницу или файл.

Для интегратора этот раздел особенно важен, потому что он помогает быстро найти причину проблемы и исправить её.

Пример подключения клиента

В нижней части страницы размещён пример клиентского подключения.

[Скриншот 2: Список доступных операций API]

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

В пользовательской документации нет необходимости приводить этот код полностью, так как он уже доступен непосредственно на странице.

Что нужно настроить перед подключением

Включите API на странице документации или в общих настройках.
Создайте API-ключ, если он ещё не создан.
Передайте ключ специалисту, который настраивает интеграцию, по защищённому каналу.
Используйте адрес API, показанный непосредственно на странице модуля.
После первого подключения выполните тестовый запрос и проверьте ответ.

API-ключ предоставляет доступ к проверке, поэтому его не следует публиковать в открытом коде страницы или передавать посторонним. Если ключ мог стать известен третьим лицам, пересоздайте его.

Доступные операции

check_text — проверить переданный текст.
check_url — загрузить страницу по адресу и проверить её содержимое.
check_file — проверить один переданный файл.
info — получить сведения о готовности API и словарей.

Для проверки текста и URL анализируется не более 200 000 символов извлечённого текста. Параметр отключения белого списка можно передать для контрольной проверки без исключений.

Форматы файлов через API

Набор форматов API уже, чем на административной странице «Проверка файлов». Через API принимаются TXT, HTML, HTM и DOCX. PDF, DOC и XLSX через метод проверки файла API не обрабатываются. Если интеграции нужны эти форматы, подготовьте текст во внешней системе либо используйте административную проверку файлов.

Правила доступа

Запросы к API выполняются методом POST. API-ключ можно передать несколькими поддерживаемыми способами; рекомендуемый вариант указан в интерфейсе — отдельный заголовок запроса. Обычное открытие endpoint-ссылки в браузере отправляет GET-запрос и не является проверкой работы API.

Если API выключено, ключ неверный, не передано обязательное поле, словари не готовы или передан неподдерживаемый формат, сервис возвращает понятный код ошибки. Полный список кодов и готовые примеры вызовов уже находятся на административной странице; в базе знаний достаточно использовать их как справочник при диагностике интеграции.

Пересоздание ключа

После пересоздания новый ключ начинает использоваться вместо старого. Все системы со старым значением потеряют доступ, поэтому сначала определите список интеграций, а после замены сразу обновите их настройки.

Как работать со страницей

Рекомендуемый порядок работы:

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

Когда пересоздавать API-ключ

Пересоздание ключа рекомендуется выполнять в следующих случаях:

если ключ стал известен посторонним;
если нужно отозвать старый доступ;
если интеграция переводится на новый ключ;
если требуется обновить настройки безопасности.

После пересоздания обязательно нужно обновить ключ во всех внешних системах, которые используют API.

Что важно учитывать

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

[Скриншот 3: Справочник ошибок и примеры запросов в интерфейсе]

Итог

Страница «Документация API» используется для включения API, управления ключом доступа и подключения внешних систем к модулю. Она содержит всю основную информацию для интеграции: адрес API, правила авторизации, описание методов, примеры запросов и список возможных ошибок.