Перейти к основному содержимому

Интеграции

Обзор​

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

Общие правила API-интеграций​

  • Для шаблонов URL, имен методов и параметров HTTP/API использовать kebab-case.
  • Именование методов и параметров API выполнять на латинице.
  • В шаблонах URL не использовать глаголы (get, add, update, delete и т.п.) — действие определяется HTTP-методом.
  • В модуле HTTP-сервиса размещать только маршрутизацию и вызов целевого общего модуля; бизнес-логику в модуле сервиса не реализовывать.
  • При проектировании HTTP-сервисов руководствоваться практиками REST API: Best practices for REST API design.
  • Для каждого публичного API-сервиса поддерживать актуальную документацию в формате OpenAPI/Swagger.

Технические имена в контрактах​

  • Все технические имена полей JSON, параметров API, заголовков и кодов ошибок должны быть на латинице.
  • Русские синонимы объектов 1С не переносятся в контракт как технические имена. Для каждого поля выбирается устойчивое английское или транслитерированное имя.
  • Если имя реквизита в 1С содержит отраслевой термин, его перевод фиксируется в контракте и не меняется без версии API или схемы сообщения.
  • Сокращения допускаются только для общеупотребимых терминов или уже закрепленных проектных обозначений. Локальные сокращения разработчика в контракт не попадают.
  • Для ссылочных полей в JSON используйте единый суффикс, например id или ref, и не смешивайте разные варианты в одном контракте.

Именование полей с единицами измерения​

  • Если единица измерения фиксирована по контракту, включать единицу в имя поля (например: weight-kg, length-mm, volume-l).
  • Если единица измерения может меняться, не включать единицу в имя поля; передавать значение и единицу отдельными полями (например: weight: { value: 12.5, unit: "kg" }).
  • Не использовать локальные сокращения и кириллицу в технических именах полей; использовать только латиницу.

Коды ошибок HTTP API​

  • 400 Bad Request — синтаксическая ошибка запроса, некорректный формат тела или параметров.
  • 401 Unauthorized — запрос не аутентифицирован или переданы недействительные учетные данные.
  • 403 Forbidden — пользователь аутентифицирован, но не имеет прав на выполнение операции.
  • 404 Not Found — ресурс не существует или недоступен по указанному URI.
  • 405 Method Not Allowed — для ресурса не поддерживается указанный HTTP-метод.
  • 409 Conflict — конфликт состояния ресурса (например, нарушение ограничений или конкурентное изменение).
  • 412 Precondition Failed — не выполнены предварительные условия запроса (например, по If-Match/If-Unmodified-Since).
  • 415 Unsupported Media Type — неподдерживаемый тип содержимого (Content-Type) запроса.
  • 422 Unprocessable Entity — синтаксис запроса корректен, но данные не проходят бизнес-валидацию.
  • 503 Service Unavailable — сервис временно недоступен; в ответе должен передаваться заголовок Retry-After.

Разделы​

  • Брокеры сообщений — RabbitMQ, Kafka и другие брокеры сообщений для асинхронного обмена данными