Объекты запросов и ответов

Каждое сообщение — обычный JSON-объект. Поле id выбираете вы, ядро возвращает его без изменения. Поэтому ответы можно сопоставлять с запросами даже при параллельной работе.

Минимальная последовательность

{"id":"ping-1","cmd":"ping"}
{"id":"open-1","cmd":"open","path":"/absolute/input.docx","document_id":"my-document"}
{"id":"model-1","cmd":"model"}
{"id":"insert-1","cmd":"mutate","operation_kind":"insert-text","paragraph_index":0,"offset":0,"text":"Привет из API. ","document_id":"my-document","transaction_order":1,"transition_kind":"api-insert"}
{"id":"save-1","cmd":"save","path":"/absolute/output.docx"}
{"id":"shutdown-1","cmd":"shutdown"}

Обязательные и рекомендуемые поля

Поле	Назначение	Правило
id	Корреляция запроса и ответа	Необязательно. Любое значение JSON — строка, число. Возвращается без изменений, поэтому должно быть уникальным среди запросов, ответ на которые ещё не получен
cmd	Имя команды сеанса	Одно из имён, перечисленных в поле supported_commands приветственного сообщения
path	Входной или выходной файл	Только абсолютный путь
document_id	Стабильная идентичность документа	Передавайте в open и в правках
transaction_order	Порядок изменений	Монотонно растёт: 1, 2, 3…
transition_kind	Причина или тип перехода	Короткая диагностическая метка
operation_kind	Семантическая операция	Обязательно для mutate. Например insert-text
paragraph_index	Номер абзаца, к которому относится правка	Обязательно для mutate. Нумерация с нуля

Формат ответа

Успех:

{"id":"ping-1","ok":true,"cmd":"ping","elapsed_ms":0,"result":{"pong":true}}

Отказ:

{"id":"bad-1","ok":false,"cmd":"mutate","elapsed_ms":0,"error":"..."}

Обработка ошибок

То, что ответ дошёл, ещё не значит, что команда выполнена: это разные вещи. Всегда проверяйте ok === true; при false сохраняйте id, cmd и error в журнал интеграции.

Для mutate одного ok мало. Правка, которую ядро не приняло — например с неизвестным operation_kind, — возвращает ok: true, а исход называет полем result.mutation.result_kind: applied, если правка применена, invalid-request, если отклонена. Проверяйте и его: иначе отклонённая правка сойдёт за выполненную, документ останется прежним, и вы об этом не узнаете.

Состав ответа

Поле	Когда есть	Что означает
id	всегда	Метка запроса, возвращается без изменений. Равна null, если запрос её не нёс или не был разобран.
ok	всегда	true — команда выполнена, false — отклонена.
cmd	почти всегда	Имя команды. Отсутствует у ответа на shutdown и при ошибке разбора запроса — в этом случае имя команды неизвестно.
elapsed_ms	почти всегда	Время обработки. Отсутствует у ответа на shutdown.
result	при ok: true	Результат команды.
error	при ok: false	Строка с причиной отказа.
result.mutation.result_kind	в ответе на mutate	Исход правки: applied — применена, invalid-request — отклонена. Конверт при этом остаётся ok: true.
shutdown	в ответе на shutdown	true. Признак того, что сеанс закрывается: другие поля, кроме id и ok, в этом ответе не приходят.

Разбирая ответ, не считайте cmd и elapsed_ms обязательными: на завершении сеанса и на неразобранном запросе их не будет.

Какие бывают operation_kind

Правка текста абзаца принимает восемь видов: insert-text и delete-text, их варианты с записью исправлений insert-text-tracked и delete-text-tracked, split-paragraph и merge-with-next для разрыва и склейки абзацев, insert-line-break и delete-line-break для переноса строки. Вид replace-text тоже принимается: ядро само раскладывает его на удаление и вставку.

Форматирование выделения идёт теми же запросами с другими видами: set-bold, set-italic, set-underline, set-font-family, set-font-size, set-font-color, set-text-highlight, set-strikethrough и другие свойства символа.

Для сложных изменений вместо mutate предназначена команда apply-text-transaction — см. Типы типизированной правки.