Kommo + Formstack Documents: автоматическая генерация документов из карточки сделки

Formstack Documents (бывший WebMerge) - платформа для автоматической генерации документов: заполняет шаблоны Word, PDF, Excel данными из любого источника и отправляет результат по email, в облако или на подпись. Интеграция с Kommo позволяет автоматически создавать коммерческие предложения, договоры, счета и онбординговые пакеты в момент перехода сделки на нужный этап воронки - без ручного копирования данных.

Ручное создание документов - скрытый потребитель времени продавца. Менеджер открывает шаблон Word, копирует имя клиента, сумму, список услуг, дату, реквизиты. На один документ уходит 10-20 минут. При 20 сделках в месяц - это 4-7 часов только на заполнение шаблонов. Плюс ошибки: неверная сумма, устаревшие условия, опечатка в названии компании.

Formstack Documents решает это через merge-поля: создаёте шаблон с плейсхолдерами {ClientName}, {DealAmount}, {DueDate}, вызываете API с данными сделки из Kommo - получаете готовый PDF.

Как работает интеграция

Formstack Documents - облачный сервис автоматической генерации документов: принимает данные через API или webhook, заполняет заданный шаблон (Word/PDF/Excel), отправляет результат на email, в Dropbox, Google Drive или возвращает ссылку для скачивания.

Архитектура интеграции:

Kommo: сделка переходит в этап "КП отправлено"
  -> Kommo webhook (lead.status.changed)
  -> Ваш сервер: извлечь данные сделки из /api/v4/leads/{id}?with=contacts
  -> POST /api/v1/documents/{document_id}/merge (Formstack Documents)
     body: {ClientName, DealAmount, ServiceList, ...}
  <- Response: {file_url: "https://...pdf"}
  -> Сохранить ссылку в кастомное поле сделки в Kommo
  -> Отправить email клиенту с PDF или ссылкой

Реализация

Шаг 1. Настройка шаблона в Formstack Documents

Создайте шаблон Word (.docx) с плейсхолдерами:

Коммерческое предложение для {ClientName}
Дата: {ProposalDate}
Действительно до: {ExpiryDate}

Услуги:
{ServiceList}

Итого: {TotalAmount} USD

После загрузки шаблона в Formstack Documents получите document_id из URL.

Шаг 2. Обработчик Kommo webhook

import requests, os
from flask import Flask, request, jsonify
from datetime import datetime, timedelta

app = Flask(__name__)

KOMMO_DOMAIN = os.environ["KOMMO_DOMAIN"]
KOMMO_TOKEN  = os.environ["KOMMO_TOKEN"]
FS_API_KEY   = os.environ["FORMSTACK_API_KEY"]
FS_DOC_ID    = os.environ["FS_DOCUMENT_ID"]    # ID вашего шаблона

KOMMO_BASE   = f"https://{KOMMO_DOMAIN}/api/v4"
KOMMO_HDR    = {"Authorization": f"Bearer {KOMMO_TOKEN}"}
FS_BASE      = "https://www.formstack.com/api/v1"

KP_STATUS_ID = 12345   # ID стадии "КП отправлено" в вашей воронке
CF_DOC_URL   = 67890   # ID кастомного поля "Ссылка на КП" в Kommo

@app.route("/webhooks/kommo", methods=["POST"])
def kommo_webhook():
    data = request.json or {}
    leads = data.get("leads", {}).get("status", [])

    for lead in leads:
        if lead.get("status_id") == KP_STATUS_ID:
            generate_proposal(lead["id"])

    return jsonify({"status": "ok"}), 200

def get_lead_data(lead_id: int) -> dict:
    # Fetch lead with contacts from Kommo.
    r = requests.get(
        f"{KOMMO_BASE}/leads/{lead_id}",
        headers=KOMMO_HDR,
        params={"with": "contacts,catalog_elements"},
    )
    return r.json() if r.ok else {}

def get_contact_data(contact_id: int) -> dict:
    r = requests.get(f"{KOMMO_BASE}/contacts/{contact_id}", headers=KOMMO_HDR)
    return r.json() if r.ok else {}

def get_custom_field(entity: dict, field_code: str) -> str:
    for f in entity.get("custom_fields_values") or []:
        if f.get("field_code") == field_code:
            vals = f.get("values", [])
            return str(vals[0]["value"]) if vals else ""
    return ""

def generate_proposal(lead_id: int):
    lead = get_lead_data(lead_id)
    if not lead:
        return

    # Получить контакт
    contacts = lead.get("_embedded", {}).get("contacts", [])
    contact_id = contacts[0]["id"] if contacts else None
    contact = get_contact_data(contact_id) if contact_id else {}

    # Собрать данные для шаблона
    merge_data = {
        "ClientName":    contact.get("name", lead.get("name", "")),
        "ClientEmail":   get_custom_field(contact, "EMAIL"),
        "ClientCompany": get_custom_field(contact, "COMPANY"),
        "DealAmount":    f"{lead.get('price', 0):,.0f}",
        "ProposalDate":  datetime.now().strftime("%d.%m.%Y"),
        "ExpiryDate":    (datetime.now() + timedelta(days=14)).strftime("%d.%m.%Y"),
        "ServiceList":   get_custom_field(lead, "SERVICES"),
        "ManagerName":   "Ваш менеджер",
        "KommoLeadId":   str(lead_id),
    }

    # Вызвать Formstack Documents API
    r = requests.post(
        f"{FS_BASE}/documents/{FS_DOC_ID}/merge",
        headers={"Authorization": f"Bearer {FS_API_KEY}"},
        json={"data": merge_data, "test": False},
        timeout=30,
    )

    if not r.ok:
        print(f"FS error {r.status_code}: {r.text}")
        return

    result = r.json()
    file_url = result.get("file_url") or result.get("pdf")

    if not file_url:
        return

    # Сохранить URL документа в кастомное поле сделки
    requests.patch(
        f"{KOMMO_BASE}/leads",
        headers=KOMMO_HDR,
        json=[{
            "id": lead_id,
            "custom_fields_values": [{
                "field_id": CF_DOC_URL,
                "values": [{"value": file_url}]
            }]
        }],
    )

    # Добавить заметку
    requests.post(
        f"{KOMMO_BASE}/leads/{lead_id}/notes",
        headers=KOMMO_HDR,
        json=[{"note_type": "common", "params": {"text": f"КП сгенерировано: {file_url}"}}],
    )

Доставка документа клиенту

Formstack Documents поддерживает несколько вариантов доставки напрямую из merge-запроса:

• Email delivery: укажите "email": {"to": client_email, "subject": "Коммерческое предложение"} в теле запроса - FS отправит PDF автоматически
• Google Drive / Dropbox: настраивается в FS dashboard как delivery rule - файл появится в папке при каждом merge
• Return URL: response содержит file_url - сохраняете в Kommo и отправляете вручную или через интеграцию с email

Какие документы генерировать автоматически

Типовые сценарии для B2B-продаж:

Реальный кейс

Компания по внедрению CRM-систем, 8 менеджеров. Каждый создавал КП вручную в Word: копировал название компании, список услуг, стоимость, дату. Среднее время - 18 минут на КП. При 30+ КП в месяц это около 9 часов потерянного времени плюс регулярные ошибки в суммах.

После автоматизации через Kommo + Formstack Documents:

• КП генерируется за 8 секунд при смене статуса сделки
• URL документа сохраняется в карточке автоматически
• Менеджер получает заметку в Kommo с ссылкой
• Ошибок в документах - 0 (данные берутся из CRM, не копируются вручную)

Для кого актуально

Компании с повторяющимися документами в продажах: консалтинг, агентства, SaaS-продажи с кастомным ценообразованием, юридические услуги. Если менеджер создаёт >5 документов в неделю по шаблону - автоматизация окупится за первый месяц.

Статья об общих подходах к кастомным интеграциям в Kommo CRM поможет оценить архитектуру под ваш стек.

Часто задаваемые вопросы

Поддерживает ли Formstack Documents русский язык и кириллицу?

Да. Шаблоны Word с кириллическим текстом обрабатываются корректно при условии, что шрифт в шаблоне поддерживает кириллицу (Arial, Times New Roman, любой системный шрифт). PDF-вывод сохраняет форматирование оригинального шаблона.

Можно ли генерировать документы с таблицами и изображениями?

Да. Formstack Documents поддерживает merge в таблицы (повторяющиеся строки через специальные теги), вставку изображений по URL, условные блоки (показывать/скрывать секции в зависимости от значения поля). Для сложных шаблонов доступен режим предпросмотра в FS Dashboard.

Как обеспечить идемпотентность - не генерировать КП дважды?

Перед вызовом Formstack API проверьте кастомное поле сделки в Kommo: если поле “Ссылка на КП” уже заполнено - пропустить генерацию. Дополнительно: лог всех сгенерированных документов в своей БД с ключом lead_id + status_id.

Итог

Kommo + Formstack Documents автоматизирует создание документов в воронке продаж:

• Kommo webhook на смену статуса сделки
• Получить данные сделки + контакта через Kommo API (?with=contacts)
• POST /documents/{id}/merge с данными -> получить URL готового PDF
• Сохранить URL в кастомное поле сделки, добавить заметку
• Отдельно: настроить email delivery прямо из Formstack Documents

Если хотите автоматизировать документооборот в своей Kommo-воронке - опишите задачу команде Exceltic.dev. Спроектируем под ваш шаблон и стек.