Встроить в настольное приложение

Первые шаги для программы на компьютере — учётной системы, 1С, отраслевой платформы: что положить рядом, что запустить и какие три строки отправить, чтобы документ открылся, изменился и сохранился.

Ваш продукт — программа, которая стоит у людей на компьютерах: учётная система, отраслевая платформа, надстройка над 1С, система документооборота. Сегодня, чтобы поправить договор, пользователь выгружает файл, открывает его в чужом редакторе и загружает обратно — и по дороге теряются версии, права и следы того, кто что менял.

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

Как это устроено, в двух словах

Рядом с вашей программой работает отдельный процесс — процессор документов. Ваша программа разговаривает с ним обычными строками: отправила строку с заданием, получила строку с ответом. Никаких библиотек внутрь вашего кода встраивать не нужно, и язык, на котором написан ваш продукт, значения не имеет — строки умеет отправлять любой.

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

Три шага

Положите ядро рядом со своей программой. Это один исполняемый файл из поставки — процессор документов. Ни установщика, ни зависимостей. Пути для трёх систем — в Установке и проверке; дальше мы зовём его $CLI.
Запустите его как дочерний процесс. Одна команда, и он ждёт заданий. Первой строкой он сам сообщает, что готов.
Окно терминала
```
"$CLI" serve
```
Ответ — строка о готовности, по ней ваша программа понимает, что можно работать:
```
{"ready": true, "schema": "fastdoc.session-serve.v1"}
```
Отправьте три строки. Открыть документ, изменить, сохранить. На каждую приходит ровно одна строка ответа:
```
{"id":"1","cmd":"open","path":"/путь/договор.docx"}
{"id":"2","cmd":"mutate","operation_kind":"insert-text","paragraph_index":0,"offset":0,"text":"Здравствуйте. "}
{"id":"3","cmd":"save","path":"/путь/договор-новый.docx"}
```
Ответы — такие:
```
{"id":"1","ok":true}
{"id":"2","ok":true}
{"id":"3","ok":true}
```
На диске появляется новый файл с внесённой правкой. Это не пример из головы: именно этот обмен выполнен на установленном A4 при подготовке страницы.

Что важно знать сразу

Поле id возвращается в ответе — по нему вы сопоставляете пару в своих журналах. Отвечает процессор строго по очереди, в том порядке, в каком пришли задания, поэтому долгая операция задерживает всё, что послано после неё. Если нужна параллельность — поднимайте второй процесс.

Запуск, остановка и перезапуск — на вашей стороне. Процесс живёт, пока живёт ваша программа; закрывая окно, закройте и его.

Отказ приходит до изменения, а не после. Если операция не поддержана или документ защищён, вы получите ответ с причиной, и файл останется прежним. Наполовину записанного документа не бывает: файл публикуется одним неделимым действием.

Если нужно показать сам редактор

Три строки выше меняют документ без всякого экрана — этого достаточно для отчётов, шаблонов и пакетной обработки. Когда пользователю нужно увидеть документ и править его руками, у вас два пути:

Окно внутри вашей программы

Ваше приложение открывает адрес поверхности в системном окне просмотра веб-страниц — и получает готовый редактор внутри своего окна.

Встраивание поверхности

Отдельное окно редактора

Проще всего для первой пробы: редактор открывается своим окном, а ваша программа отдаёт ему файл и забирает результат.

Запуск поверхности

То же самое для таблиц

У книг XLSX всё устроено так же: рядом работает свой процессор, и разговор идёт такими же строками. Отличается имя программы и состав заданий — Отдельный процесс ядра рядом с приложением.

Если считать нужно не на компьютере пользователя, а на сервере — тот же процессор работает и там: Процессор на сервере.

Дальше, когда простого станет мало

Что вы хотите сделать	Куда смотреть
Собрать договор по шаблону и подставить данные из своей базы	Что A4 умеет с документом
Выгрузить готовый документ в PDF, в том числе со встроенными шрифтами	Печать и выпуск
Проверить, чем защищён чужой файл и какие в нём макросы, не запуская их	Безопасность файла
Пересчитать книгу, собрать сводную таблицу, обновить запрос к данным	Карта возможностей рядом с Excel
Понять, что приходит в ответе и как читать отказ	Объекты запросов и ответов
Точные имена всех вызовов с полями	Справочник A4, Справочник F1

Встроить в веб-приложениеЕсли ваш продукт живёт в браузере: редактор открывается прямо на вашей странице.

Встроить в мобильное приложениеЧто для телефона и планшета возможно сегодня, а чего пока нет — честно и без обещаний.