Приложение 2: NProtocol

Протокол обмена данными представляет из себя json-объект (далее — контейнер), который содержит ряд обязательных к заполнению свойств (полей):

• MessageId – идентификатор сообщения (GUID). Генерируется отправляющей стороной при создании контейнера.
• CreationDateTime — метка времени в формате DD.MM.YYY HH:MM:SS.
• SourcePoint — алиас проекта, который отправляет сообщение. Некий синоним названия проекта на английском языке. Примеры: «Translator», «1C_BUH», «Supplies» и т. д. Алиас должен быть уникальным в рамках фирмы.
• TargetPoints — лист (массив) алиасов проектов, которым предназначается сообщение.
• MessageType — перечисление. Тип — сообщение. Существуют три типа сообщения:
  • 0 – Request
  • 1 – Response
  • 3 – Event

При первичном создании сообщения системой-отправителем указывается тип 0 — Request. В свою очередь после получения целевой системой сообщения и его обработки она должна сформировать контейнер с типом сообщения 1 — Response. Тип 3 — Event указывается, если требуется уведомить целевую систему о каком—то событии в источнике, без передачи данных.

• BaseRequestId – Guid базового сообщения. Указывается при типе сообщения 1 – Response.
• Properties – лист (массив) элементов типа Property. Property это объект, который содержит в себе два поля: Name и Value. Соответственно, все данные, которые необходимо передать, можно упаковать в этот массив элементов типа Property. Пример массива: "Properties":[{"Name":"object", "Value":"123"},{"Name":"FilePath", "Value":"C:\Users\1.txt"}].
• Attachments – лист (массив) элементов типа Attachment. Attachment это объект, содержащий два поля: Base64String – представление файла в виде base64 строки, FileName – имя файла с расширением. Можно передавать просто расширение.
  Некоторые правила, которых стоит придерживаться при формировании поля Name в элементе типа Property:
  1. Если нужно передать путь к файлу, следует указывать «FilePath»;
  2. Если передаются значения полей документа, в поле Name передается название поля.
• TargetPropertyName – можно указывать, если передается одно свойство и оно является целевым для принимающей системы.
• Errors – лист (массив) элементов типа Error. Error — это объект, содержащий два поля: ErrorReason и ErrorCode. Таблица с кодами ошибок представлена ниже:

Рекомендованные функции для работы с протоколом

• Функция валидации контейнера — перед извлечением данных проверить наличие всех полей. Пустые поля недопустимы (отсутствовать могут лишь списки (массивы)
• Получить значение свойства по имени (полное совпадение).
• Получить значение свойства по имени (частичное совпадение, contains).
• Функция упаковки в контейнер.
• Получение файлов из массива Attachments.

Служебные команды

В Properties можно передавать специальные пары — команды — сигналы, указывающие что нужно делать целевой системе с содержимым контейнера.

Служебный ключ command

Если передать property с полями Name = command, Value = edmxml, то ожидается, что в целевой системе есть обработка, в которой присутствует команда с таким именем.

В совокупности предполагается, что в контейнер собирается максимальное количество информации об объекте, а также максимально требуемый набор команд, которые могут быть использованы в разных системах относительно этого объекта. Например контейнер уходит в системы А и В. В системе А описано поведение при получении команды rawxml, а в системе В описано поведение с командой rawjson. В таком случае в источнике упаковывается контейнер с обеими командами и всеми свойствами, которые нужны для выполнения команд. Именования свойств также должны быть согласованы между целевой и начальной системами.

Пример добавления документа через NProtocol

Рассмотрим пример добавления документа через Nprotocol. В коллекцию Properties обязательно нужно добавить следующие свойства:

• свойство DocumentType (тип документа).
• command (внутренняя команда, чтобы сервис понимал, что от него хотят) со значением “api_addDocument”.
• Fields — сериализованный массив с полями документа и их значениями.

{
  "MessageId": "F4B4AF8D-DF51-4CDA-8A04-CF8BF44A47F5",
  "CreationDateTime": "2025-04-01",
  "SourcePoint": "SourceDataBase",
  "TargetPoints": [
    "BUH_1C",
    "Docoteca"
  ],
  "MessageType": 0,
  "Properties": [
    {
      "Name": "DocumentType",
      "Value": "900"
    },
    {
      "Name": "command",
      "Value": "api_addDocument"
    },
    {
      "Name": "Fields",
      "Value": "[{\"FieldName\":\"Номер документа\", \"FieldValue\":\"105\"},{\"FieldName\":\"Дата документа\", \"FieldValue\":\"30.02.2025\"}]"
    }
  ],
  "Attachments": [
    {
      "Base64String": "Tkjkjujhhjgh",
       "FileName": "C:\\НаименованиеКонтрагента\\Приходы\\Год\\КодСущности\\78600.pdf"
    }
  ]
}