HTTP-сервис 1С своими руками: endpoint, JSON и коды ответа

HTTP сервис 1С своими руками создаётся в ветке Общие, HTTP-сервисы: добавьте шаблон URL, метод GET или POST и обработчик, который возвращает HTTPСервисОтвет с кодом, заголовком Content-Type и телом JSON. Публикуйте сервис только после настройки аутентификации, прав и безопасной обработки входных данных.

Платформа позволяет создавать произвольные HTTP-сервисы дополнительно к автоматическому REST-интерфейсу. URL сопоставляется с шаблоном и методом. Если совпадения нет, платформа возвращает 404. Обработчик получает объект HTTPСервисЗапрос с URL, заголовками и телом, а затем формирует HTTPСервисОтвет. Сервис ориентируйте на ресурсы, используйте стандартные методы и возвращайте однозначные статусы. До публикации опишите контракт в таблице: метод, путь, авторизация, входные поля, успешный ответ и ошибки. Версионируйте несовместимые изменения в URL или заголовке, чтобы старые клиенты не получили внезапно другую структуру. Для диагностики добавьте correlation id, но не включайте персональные данные в открытые журналы.

HTTP сервис 1С своими руками: первый обработчик GET

Создайте сервис Api, шаблон status и метод GET с обработчиком GetStatus. Пример возвращает постоянный ответ, поэтому подходит для health-check учебной публикации. Строка JSON должна быть корректно экранирована во встроенном языке, а Content-Type должен указывать кодировку.

Функция GetStatus(Запрос)

    ТелоОтвета = "{""status"":""ok"",""service"":""1c""}";

    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить(
        "Content-Type",
        "application/json; charset=utf-8"
    );
    Ответ.УстановитьТелоИзСтроки(
        ТелоОтвета,
        КодировкаТекста.UTF8
    );

    Возврат Ответ;

КонецФункции

Для сложного JSON используйте ЗаписьJSON и ЗаписатьJSON, а не ручную конкатенацию. Параметр {id} получите из параметров URL и проверьте до обращения к данным. Не возвращайте текст исключения или стек клиенту: запишите технические детали в защищённый журнал, а наружу дайте стабильный код ошибки и request id. Для неверного ввода используйте 400, для отсутствующего ресурса 404, для конфликта 409.

Минимальный контракт endpoint

Проверьте сервис через curl с заголовком Accept, затем негативные сценарии и неизвестный путь. Аутентификацию не заменяйте секретом в URL: адрес попадает в журналы и историю. Используйте HTTPS, отдельного пользователя с минимальными правами, ограничения размера тела и таймауты. Идемпотентность и повторные запросы особенно важны для интеграций, где сеть может оборваться после выполнения операции.

Практика: соберите endpoint status и получите 200 и 404 в curl

Соберите в тестовой конфигурации HTTP-сервис Api с шаблоном status и методом GET. Успехом считайте ответ 200 с телом {"status":"ok","service":"1c"} на опубликованный адрес и 404 на неизвестный путь. Работайте на копии базы: учебная публикация не должна попадать в рабочую.

Сломайте ответ намеренно: уберите вставку заголовка Content-Type или оставьте кодировку по умолчанию в УстановитьТелоИзСтроки. Клиент получит те же 200, но тип будет не application/json, а кириллица приедет испорченной, и разбор JSON на стороне вызывающей системы упадёт. Это ровно тот случай, когда статус 200 прячет проблему внутри строки. Верните заголовок и UTF8 и убедитесь, что curl снова показывает application/json; charset=utf-8.

Дальше добавьте шаблон products/{id} и достаньте параметр из URL. Проверяйте id до обращения к данным: на нечисловое значение отвечайте 400 с указанием поля, на ненайденный объект 404 со стабильным кодом not_found. Сложное тело перестаньте склеивать строками и соберите через ЗаписьJSON и ЗаписатьJSON. Для сервиса заведите отдельного пользователя с минимальными правами, чтобы endpoint не работал в базе под полным доступом.

Частые ошибки и почему они появляются

Опасный сервис принимает произвольное имя объекта и выполняет переданный код. Другая ошибка: все ответы имеют статус 200, а проблема спрятана в строке. Третья: обработчик выполняет долгую массовую операцию синхронно и держит соединение. Для тяжёлой задачи лучше принять запрос, создать задание и вернуть идентификатор статуса.

Самопроверка