Документация API

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

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

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

  • включить или выключить API;
  • создать или пересоздать API-ключ;
  • посмотреть адрес API;
  • узнать, как передавать авторизацию;
  • посмотреть доступные методы 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 и анализа его текстового содержимого.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Коды ошибок

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Итог

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

Блок с методами API и примерами запросов