Kommo + Dropbox Sign: автоматическая отправка контрактов на подпись

Dropbox Sign (ранее HelloSign) — платформа электронных подписей с REST API на Basic Auth, без сложного OAuth для серверных интеграций. Это одно из главных отличий от SignNow и DocuSign — сервисные интеграции работают с API-ключом напрямую. Связка с Kommo автоматизирует цикл: сделка перешла на нужный этап -> документ отправлен клиенту -> после подписания CRM обновляется автоматически.

Dropbox Sign vs SignNow vs DocuSign: когда Dropbox Sign

Dropbox Sign выигрывает по простоте аутентификации: один API-ключ в заголовке, никакого OAuth flow. Это существенно упрощает разработку серверной интеграции. Цена ниже DocuSign при сопоставимом функционале.

Что синхронизируется

Kommo -> Dropbox Sign:
— Email и имя контакта сделки -> signer в signature request
— Название сделки -> title документа
— Данные из кастомных полей -> custom_fields в шаблоне (merge fields)
— Срок подписания -> expiration_date
— ID сделки Kommo -> metadata (для обратной трассировки)

Dropbox Sign -> Kommo:
— Событие signature_request_signed -> поле «Документ подписан» в сделке
— Перевод сделки на следующий этап воронки
— Ссылка на подписанный документ -> Note на сделке
— Дата подписания -> кастомное поле

Архитектура

Kommo Webhook: сделка перешла на этап «Подписание»
  ↓ Backend
  1. GET /api/v4/leads/{id} + contacts
     -> имя, email, данные из кастомных полей
  2. Dropbox Sign API: POST /signature_request/send_with_template
     -> template_id + signers + custom_fields + metadata
     -> получить signature_request_id
  3. Kommo: PATCH /leads/{id}
     -> обновить поля: ds_signature_request_id, document_sent = true

Dropbox Sign Webhook: signature_request_signed
  ↓ Backend
  1. Извлечь signature_request_id из payload
  2. Найти kommo_deal_id через metadata
  3. Dropbox Sign: GET /signature_request/{id}
     -> получить ссылку на подписанный документ
  4. Kommo: PATCH /leads/{deal_id}
     -> document_signed = true, этап -> «Договор получен»
  5. Kommo: POST /notes
     -> дата подписания + ссылка на документ

Dropbox Sign REST API: ключевые запросы

Base URL: https://api.hellosign.com/v3/. Аутентификация: HTTP Basic Auth, где username = API_KEY, password — пусто.

Отправка через шаблон (рекомендуемый подход):

import requests
from requests.auth import HTTPBasicAuth

DS_API_KEY = 'your_api_key'
TEMPLATE_ID = 'template_id_from_dropbox_sign'
BASE_URL = 'https://api.hellosign.com/v3'

def send_for_signature(deal_id: int, client_name: str, client_email: str,
                       deal_name: str, amount: float) -> str:
    payload = {
        'template_ids': [TEMPLATE_ID],
        'subject': f'Договор по сделке: {deal_name}',
        'message': f'Уважаемый {client_name}, направляем договор для подписания.',
        'signers': [
            {
                'role': 'Client',
                'name': client_name,
                'email_address': client_email
            }
        ],
        'custom_fields': [
            {'name': 'ClientName', 'value': client_name},
            {'name': 'DealAmount', 'value': f'${amount:,.2f}'},
            {'name': 'DealDate', 'value': str(date.today())}
        ],
        'metadata': {
            'kommo_deal_id': str(deal_id)  # для обратной трассировки
        }
    }

    resp = requests.post(
        f'{BASE_URL}/signature_request/send_with_template',
        auth=HTTPBasicAuth(DS_API_KEY, ''),
        data=payload  # form-encoded, не JSON
    )
    return resp.json()['signature_request']['signature_request_id']

Важный нюанс: Dropbox Sign API принимает application/x-www-form-urlencoded или multipart/form-data, а не application/json для большинства endpoint’ов. Это частая ошибка при первом подключении.

Отправка документа напрямую (без шаблона):

def send_document_directly(client_name: str, client_email: str,
                           pdf_path: str, deal_name: str) -> str:
    with open(pdf_path, 'rb') as f:
        resp = requests.post(
            f'{BASE_URL}/signature_request/send',
            auth=HTTPBasicAuth(DS_API_KEY, ''),
            files={'file[0]': (pdf_path, f, 'application/pdf')},
            data={
                'title': deal_name,
                'signers[0][email_address]': client_email,
                'signers[0][name]': client_name,
                'signers[0][order]': 0
            }
        )
    return resp.json()['signature_request']['signature_request_id']

Обработка webhook:

from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhooks/dropbox-sign', methods=['POST'])
def dropbox_sign_webhook():
    # Dropbox Sign отправляет JSON в поле 'json'
    payload = json.loads(request.form.get('json', '{}'))

    event_type = payload.get('event', {}).get('event_type')
    sr_id = payload.get('signature_request', {}).get('signature_request_id')
    metadata = payload.get('signature_request', {}).get('metadata', {})

    if event_type == 'signature_request_signed':
        deal_id = metadata.get('kommo_deal_id')
        if deal_id:
            update_kommo_deal(int(deal_id), signed=True)

    return 'Hello API Event Received'  # Dropbox Sign требует именно этот ответ

Критично: Dropbox Sign требует ответ 200 OK с телом Hello API Event Received — иначе будет повторять webhook до 5 раз.

Настройка шаблона в Dropbox Sign

Шаблоны создаются в UI Dropbox Sign. Для автоматического заполнения нужно:

1. Добавить текстовые поля с именами: ClientName, DealAmount, DealDate
2. Назначить поле «Подпись» роли Client
3. Сохранить Template ID — он используется в API-запросах

Шаблонный подход исключает генерацию PDF на стороне backend — данные из Kommo подставляются в шаблон через custom_fields.

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

IT-компания (EU-рынок, 25–35 контрактов в месяц, клиенты в Германии и Нидерландах):

• До: менеджер вручную скачивал шаблон договора, заполнял данные, загружал в Dropbox Sign, добавлял получателя, отправлял. Обновление Kommo — вручную после подписания.
• После: Won в Kommo -> менеджер видит поле «Документ подписан» через 30 минут (время подписания клиентом) -> этап переходит автоматически. Менеджер не делает ничего кроме закрытия сделки.
• Дополнительный эффект: юрист получает подписанные договоры автоматически на email — не запрашивает у менеджеров.

Аналогичная логика реализована для Adobe Sign и Kommo — там аутентификация через OAuth, здесь проще: API Key.

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

• Используется Dropbox Sign или рассматривается как более доступная альтернатива DocuSign
• 10+ контрактов в месяц, отправляемых вручную
• Нужна простая API-интеграция без OAuth-сложности (для небольшой команды)
• eIDAS (EU) или ESIGN (US) — юридически значимые подписи
• Двусторонний цикл: Won -> документ -> подпись -> следующий этап воронки

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

Dropbox Sign API принимает JSON или form-data?

По умолчанию — multipart/form-data или application/x-www-form-urlencoded. Это частая ошибка: разработчик отправляет JSON и получает 400. Исключение: некоторые GET-запросы. Проверяйте Content-Type перед отладкой.

Как настроить webhook в Dropbox Sign?

В UI Dropbox Sign: Settings -> API -> API Apps -> выбрать или создать API App -> Callback URL. Webhook можно ограничить конкретными событиями: signature_request_signed, signature_request_declined, signature_request_all_signed. Для тестирования — поле Test Mode: 1 в запросах.

Dropbox Sign поддерживает несколько подписантов?

Да. В массиве signers можно указать нескольких с order (порядок подписания). Каждый получает собственное письмо. Webhook signature_request_all_signed срабатывает когда подписали все — удобно для двустороннего подписания (клиент + менеджер).

Dropbox Sign поддерживает embedded signing?

Да. Через POST /embedded/sign_url/{signature_id} получается временный URL для iframe-подписания внутри вашего приложения. Требует API App с настроенным Embedded Signing доменом.

Итого

• Dropbox Sign REST API: Basic Auth (API Key), multipart/form-data, шаблоны с custom_fields
• Рекомендуемый подход: send_with_template — данные из Kommo -> шаблон, без генерации PDF
• Webhook signature_request_signed -> обновление Kommo; ответ Hello API Event Received обязателен
• Проще в разработке чем OAuth-based e-signature платформы
• Типовой срок — 1–2 недели

Если вы используете Dropbox Sign и хотите автоматизировать отправку документов из Kommo — опишите ваши шаблоны и схему подписания. Exceltic.dev разберёт custom_fields и предложит архитектуру.