Публичный API

Основы

База

https://kpage.ru/api/v1/ext

Все адреса ниже — относительно неё.

Аутентификация

Authorization: Bearer $KPAGE_API_KEY

Ключ создаётся в кабинете: Настройки → «API · вебхуки».

Лимит запросов

120 запросов в минуту

Считается на ключ, а не на IP. При превышении — 429.

Тариф

Business и старше

На младших тарифах ключ отвечает 402 — это «нужен апгрейд», а не отказ в доступе.

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

# Ключ создаётся в кабинете: Настройки → «API · вебхуки».
# Показывается один раз — сохраните его в переменную окружения, а не в код.
export KPAGE_API_KEY="kp_live_вставьте_сюда_свой_ключ"

Быстрый старт

Полный путь «сделка в CRM → ссылка клиенту → событие о прочтении» — пять запросов. Примеры переключаются на ваш язык одной кнопкой.

1. 1

   Проверяем ключ

   Заодно видно тариф и остатки лимитов.
   cURLPythonJavaScriptPHP

   curl "https://kpage.ru/api/v1/ext/me" \
     -H "Authorization: Bearer $KPAGE_API_KEY"

2. 2

   Находим КП-шаблон

   Шаблон — обычное КП, собранное в кабинете один раз на услугу.
   cURLPythonJavaScriptPHP

   curl "https://kpage.ru/api/v1/ext/proposals?q=шаблон" \
     -H "Authorization: Bearer $KPAGE_API_KEY"

3. 3

   Копируем его под сделку

   В ответе — id новой копии.
   cURLPythonJavaScriptPHP

   curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_shablon/duplicate" \
     -H "Authorization: Bearer $KPAGE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "КП для Ромашки",
       "client": "ООО Ромашка"
     }'

4. 4

   Просим клиента представиться и публикуем

   После публикации в ответе появится url — это и есть ссылка для клиента.
   cURLPythonJavaScriptPHP

   curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/publish" \
     -H "Authorization: Bearer $KPAGE_API_KEY"

5. 5

   Подписываемся на события

   Дальше API опрашивать не нужно — КПейдж сам придёт с новостями.
   cURLPythonJavaScriptPHP

   curl -X POST "https://kpage.ru/api/v1/ext/webhooks" \
     -H "Authorization: Bearer $KPAGE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://hooks.company.ru/kpage",
       "events": [
         "proposal.lead",
         "proposal.opened"
       ]
     }'

Тело предложения можно собрать двумя путями. Копия шаблона — одно собранное КП на услугу, копия на каждую сделку, без расхода ИИ-квоты. Или бриф: отправьте описание сделки в /generate, ИИ соберёт черновик за несколько минут и сообщит вебхуком proposal.generated. Проверьте черновик в кабинете, прежде чем публиковать: КП уходит клиенту.

Аккаунт

С этого начинается любая интеграция: проверить ключ и узнать, что доступно аккаунту, не дожидаясь отказа на боевом запросе.

curl "https://kpage.ru/api/v1/ext/me" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "account": { "id": "u_a12f", "email": "you@company.ru", "plan": "business", "org": null },
  "features": { "api": true, "customDomain": true, "team": true },
  "limits": {
    "proposals": { "used": 12, "limit": null },
    "ai": { "used": 34, "limit": 400, "resetAt": "2026-08-19T10:00:00.000Z" },
    "storage": { "usedBytes": 10485760, "limitBytes": 5368709120 }
  },
  "brand": {
    "publicDomain": "kpgo.ru",
    "personal": { "domain": "kp.company.ru", "subdomain": null },
    "team": null
  },
  "key": { "id": "ak_31c8", "name": "amoCRM", "lastUsedAt": null }
}

Команда

Сводка по всей команде — те же цифры, что видит руководитель в кабинете. Доступно владельцу команды и руководителю.

curl "https://kpage.ru/api/v1/ext/team" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "org": { "id": "org_5b31", "name": "Агентство" },
  "totals": { "proposals": 48, "published": 31, "views": 214, "opened": 22 },
  "members": [
    {
      "userId": "u_c74e",
      "email": "manager@company.ru",
      "name": "Пётр",
      "role": "manager",
      "status": "active",
      "proposals": 12,
      "published": 9,
      "views": 63,
      "opened": 7
    }
  ]
}

Коммерческие предложения

Жизненный цикл КП: черновик → правка полей и гейтов → публикация → архив или удаление. Тело КП (текст, структура, дизайн) собирается в кабинете в диалоге с ИИ — API его не генерирует. Рабочий путь для интеграции: держите готовое КП-шаблон и копируйте его. Права те же, что в кабинете: свои предложения плюс командные предложения участников, если ключ принадлежит владельцу команды или руководителю.

curl "https://kpage.ru/api/v1/ext/proposals?status=published&limit=50" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "data": [ { "id": "p_7f3a2b", "title": "КП для Ромашки", "status": "published" } ],
  "meta": { "total": 137, "limit": 50, "offset": 0 }
}

curl -X POST "https://kpage.ru/api/v1/ext/proposals" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "КП для Ромашки",
    "client": "ООО Ромашка"
  }'

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_shablon/duplicate" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "КП для Ромашки",
    "client": "ООО Ромашка"
  }'

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/generate" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Внедрение CRM для отдела продаж из 8 человек, срок 6 недель, бюджет до 600 000 ₽",
    "urls": [
      "https://romashka.ru"
    ]
  }'

{
  "jobId": "j_4kQ9",
  "proposalId": "p_7f3a2b",
  "status": "pending",
  "statusUrl": "https://kpage.ru/api/v1/ext/jobs/j_4kQ9",
  "editorUrl": "https://kpage.ru/cp/proposals/p_7f3a2b"
}

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/revise" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Добавь этап обучения сотрудников и пересчитай итог"
  }'

curl "https://kpage.ru/api/v1/ext/jobs/p_7f3a2b" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "id": "p_7f3a2b",
  "number": "417",
  "title": "КП для Ромашки",
  "client": "ООО Ромашка",
  "status": "published",
  "scope": "personal",
  "url": "https://kp.company.ru/aB3xY9",
  "link": "aB3xY9",
  "guards": ["email"],
  "views": 4,
  "expiresAt": "2026-08-03T10:00:00.000Z",
  "createdAt": "2026-07-27T09:00:00.000Z",
  "updatedAt": "2026-07-27T10:12:00.000Z",
  "publishedAt": "2026-07-27T10:00:00.000Z"
}

curl -X PATCH "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emailId": {
      "enabled": true
    },
    "expiry": {
      "enabled": true,
      "preset": "7d"
    }
  }'

curl -X DELETE "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/publish" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/unpublish" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl -X POST "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/archive" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

Аналитика и лиды

Что произошло со ссылкой после отправки. Тестовые заходы автора и боты (почтовые сканеры, краулеры превью) в цифры не попадают.

curl "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/analytics" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "proposalId": "p_7f3a2b",
  "sessions": 6,
  "visitors": 2,
  "avgTimeSeconds": 214,
  "opened": true,
  "lastActivity": "2026-07-27T09:12:44.000Z",
  "topSections": [
    { "name": "Цена", "seconds": 190 },
    { "name": "Сроки", "seconds": 88 }
  ]
}

curl "https://kpage.ru/api/v1/ext/proposals/p_7f3a2b/visitors" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{
  "data": [
    {
      "id": "v_9d21",
      "email": "buyer@romashka.ru",
      "totalSeconds": 421,
      "sessions": 3,
      "firstVisit": "2026-07-26T14:02:11.000Z",
      "lastVisit": "2026-07-27T09:12:44.000Z",
      "online": false
    }
  ],
  "meta": { "total": 1 }
}

Управление вебхуками

Подписки можно вести и из кабинета (Настройки → «API · вебхуки»), и через API — например, чтобы разворачивать интеграцию скриптом.

curl "https://kpage.ru/api/v1/ext/webhook-events" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl "https://kpage.ru/api/v1/ext/webhooks" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl -X POST "https://kpage.ru/api/v1/ext/webhooks" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.company.ru/kpage",
    "events": [
      "proposal.lead",
      "proposal.opened"
    ]
  }'

{
  "id": "wh_2c9d",
  "url": "https://hooks.company.ru/kpage",
  "secret": "whsec_4f21c8a9e05b7d3612fa8c40",
  "events": ["proposal.lead", "proposal.opened"],
  "active": true,
  "lastDeliveryAt": null,
  "lastStatus": null,
  "failureCount": 0,
  "createdAt": "2026-07-27T10:00:00.000Z"
}

curl -X PATCH "https://kpage.ru/api/v1/ext/webhooks/wh_2c9d" \
  -H "Authorization: Bearer $KPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "proposal.lead"
    ],
    "active": true
  }'

curl -X DELETE "https://kpage.ru/api/v1/ext/webhooks/wh_2c9d" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

curl -X POST "https://kpage.ru/api/v1/ext/webhooks/wh_2c9d/test" \
  -H "Authorization: Bearer $KPAGE_API_KEY"

{ "ok": true, "status": 200, "event": "ping", "durationMs": 143, "error": null }

События (вебхуки)

Не опрашивайте аналитику по расписанию — подпишитесь. КПейдж сам придёт POST-запросом, когда с предложением что-то произошло.

Как выглядит доставка

POST https://hooks.company.ru/kpage
Content-Type: application/json
X-KPage-Event: proposal.lead
X-KPage-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015

{
  "id": "evt_5c1a",
  "event": "proposal.lead",
  "createdAt": "2026-07-27T09:12:44.000Z",
  "data": {
    "proposalId": "p_7f3a2b",
    "number": "417",
    "title": "КП для Ромашки",
    "client": "ООО Ромашка",
    "email": "buyer@romashka.ru",
    "visitorId": "v_9d21"
  }
}

Проверка подписи

Тело подписано HMAC-SHA256 по секрету вебхука. Считайте подпись по сырому телу до разбора JSON и сравнивайте постоянным по времени сравнением — иначе приёмник можно обмануть подделкой или подобрать подпись по замерам.

# Подпись проверяется на вашей стороне — вот тот же расчёт в шелле.
# $BODY — сырое тело запроса, $SECRET — секрет вебхука.
printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1

• Событие получает автор предложения, а если предложение командное — ещё и владелец команды с руководителями. Рядовому участнику чужие события не уходят.
• Отвечайте 2xx сразу, а тяжёлую работу делайте фоном: на ответ отведено 8 секунд.
• Неудачная доставка повторяется трижды с нарастающей паузой. После 15 подряд неуспешных адрес отключается — включить обратно можно в кабинете.
• Доставка может повториться: событие несёт поле id, используйте его для защиты от повторной обработки.
• Принимаются только адреса https на публичных хостах; переадресации не выполняются.
• Проверить приёмник, не дожидаясь реального события, — кнопкой «Проверить» в кабинете или запросом POST /webhooks/{id}/test.

Ошибки

Любая ошибка — JSON одного вида. Поле details появляется у ошибок валидации и перечисляет поля, которые не подошли.

{
  "message": "Пустое КП опубликовать нельзя: сначала соберите содержимое.",
  "code": "BAD_REQUEST"
}