Kommo + Formstack Documents: Automatic Document Generation from a Deal Card

Formstack Documents (formerly WebMerge) is a platform for automatic document generation: it populates Word, PDF, and Excel templates with data from any source and sends the result by email, to cloud storage, or for e-signature. The integration with Kommo lets you automatically create proposals, contracts, invoices, and onboarding packages the moment a deal moves to the right pipeline stage - without manually copying data.

Manual document creation is a hidden consumer of a salesperson’s time. A manager opens a Word template, copies the client name, amount, list of services, date, and company details. One document takes 10-20 minutes. With 20 deals per month, that’s 4-7 hours spent just filling in templates. Add to that errors: wrong amounts, outdated terms, typos in the company name.

Formstack Documents solves this with merge fields: you create a template with placeholders like {ClientName}, {DealAmount}, {DueDate}, call the API with deal data from Kommo, and get a finished PDF.

How the Integration Works

Formstack Documents is a cloud service for automatic document generation: it accepts data via API or webhook, populates a given template (Word/PDF/Excel), and sends the result by email, to Dropbox, Google Drive, or returns a download link.

Integration architecture:

Kommo: deal moves to "Proposal Sent" stage
  -> Kommo webhook (lead.status.changed)
  -> Your server: extract deal data from /api/v4/leads/{id}?with=contacts
  -> POST /api/v1/documents/{document_id}/merge (Formstack Documents)
     body: {ClientName, DealAmount, ServiceList, ...}
  <- Response: {file_url: "https://...pdf"}
  -> Save the link to a custom field on the deal in Kommo
  -> Send the client an email with the PDF or link

Implementation

Step 1. Set up the template in Formstack Documents

Create a Word (.docx) template with placeholders:

Proposal for {ClientName}
Date: {ProposalDate}
Valid until: {ExpiryDate}

Services:
{ServiceList}

Total: {TotalAmount} USD

After uploading the template to Formstack Documents, get the document_id from the URL.

Step 2. Kommo webhook handler

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}"}}],
    )

Delivering the Document to the Client

Formstack Documents supports several delivery options directly from the merge request:

• Email delivery: include "email": {"to": client_email, "subject": "Proposal"} in the request body - FS will send the PDF automatically
• Google Drive / Dropbox: configured in the FS dashboard as a delivery rule - the file appears in the designated folder on every merge
• Return URL: the response contains file_url - save it in Kommo and send manually or via an email integration

What Documents to Generate Automatically

Typical scenarios for B2B sales:

Real-World Case

A CRM implementation company with 8 managers. Each one created proposals manually in Word: copying the company name, list of services, cost, date, and company details. Average time - 18 minutes per proposal. With 30+ proposals per month, that’s around 9 hours of lost time plus frequent errors in amounts.

After automating with Kommo + Formstack Documents:

• Proposal generated in 8 seconds when deal status changes
• Document URL saved to the deal card automatically
• Manager receives a note in Kommo with the link
• Errors in documents - 0 (data comes from the CRM, not copied manually)

Who This Is For

Companies with recurring documents in their sales process: consulting firms, agencies, SaaS sales with custom pricing, legal services. If a manager creates more than 5 templated documents per week, automation pays for itself within the first month.

The article on general approaches to custom integrations in Kommo CRM will help you evaluate the architecture for your stack.

Frequently Asked Questions

Does Formstack Documents support non-Latin character sets?

Yes. Word templates with non-Latin text are processed correctly as long as the font in the template supports those characters (Arial, Times New Roman, any standard system font). PDF output preserves the formatting of the original template.

Can documents with tables and images be generated?

Yes. Formstack Documents supports merging into tables (repeating rows via special tags), image insertion by URL, and conditional blocks (show/hide sections based on a field value). For complex templates, a preview mode is available in the FS Dashboard.

How do you ensure idempotency - avoid generating a proposal twice?

Before calling the Formstack API, check the custom field on the deal in Kommo: if the “Proposal Link” field is already populated, skip the generation. Additionally, keep a log of all generated documents in your own database with a lead_id + status_id key.

Summary

Kommo + Formstack Documents automates document creation in your sales pipeline:

• Kommo webhook on deal status change
• Fetch deal + contact data via the Kommo API (?with=contacts)
• POST /documents/{id}/merge with data -> receive the URL of the finished PDF
• Save the URL to a custom field on the deal, add a note
• Separately: configure email delivery directly from Formstack Documents

If you want to automate document workflows in your Kommo pipeline - describe the task to the Exceltic.dev team. We will design a solution for your template and stack.