StomPro API · Документация для интеграций

Обзор

API для партнёров и интеграторов

StomPro — облачная CRM для стоматологий Узбекистана и СНГ: карточки пациентов, расписание, зубная карта, склад, финансы, лиды. API даёт сторонним сервисам контролируемый доступ к данным клиники с явного разрешения владельца — через scopes и отзываемые токены.

Bearer-токен на клинику — без хранения паролей и без OAuth overhead для базовых сценариев.
Idempotency-Key на всех записывающих эндпоинтах — безопасные повторы при сетевых сбоях.
Webhooks с HMAC-подписью и retry до 5 раз с экспоненциальным backoff.
Sandbox-окружение — отдельный токен для разработки, не влияет на боевые данные.
Стабильное версионирование — поддержка предыдущей мажорной версии минимум 12 месяцев.

Телефония

МоиЗвонки, Mango Office, Sipuni — приём звонков, всплывающая карточка пациента, авто-создание лида из неизвестного номера.

Мессенджеры

Telegram, Instagram, Facebook — отправка/приём сообщений из аккаунта клиники, автоматическое создание лида.

Marketplace-виджеты

OAuth-flow «Подключить в один клик» прямо из интерфейса партнёра, как в amoCRM Market.

Webhooks

Real-time уведомления о событиях клиники: новый пациент, запись на приём, оплата, новый лид.

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

3 шага до первого запроса

1

Подайте партнёрскую заявку

Свяжитесь с командой StomPro: Telegram StomPro или email legal@stompro.uz. В заявке укажите название сервиса, требуемые scopes и callback-URL. Ответ в течение одного рабочего дня. Sandbox-токен выдаём сразу для разработки.

2

Получите токен клиники

Через OAuth Marketplace-flow (см. ниже) или напрямую от владельца клиники для одиночных интеграций. Один токен = одна клиника, бессрочный, отзывается клиникой в любой момент в разделе «Настройки → Интеграции».

3

Первый запрос

curl https://app.stompro.uz/api/v1/clinic/me \
  -H "Authorization: Bearer YOUR_CLINIC_TOKEN"

Авторизация

Bearer-токен в каждом запросе

Все запросы к API требуют заголовок Authorization: Bearer <clinic_token>. Токен выдаётся для конкретной клиники при подключении интеграции и действует пока клиника не отозвала доступ.

Пример запроса с авторизацией

POST /api/v1/calls/event HTTP/1.1
Host: app.stompro.uz
Authorization: Bearer st_clinic_a8f3d9e2c4b1f7e6d5a4c3b2a1f0e9d8
Content-Type: application/json

{
  "phone": "+998901234567",
  "type": "incoming",
  "started_at": "2026-04-28T14:32:15+05:00",
  "duration": 0,
  "status": "ringing"
}

Если токен невалидный

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "ok": false,
  "error": "invalid_token",
  "message": "Clinic token is invalid or has been revoked"
}

Безопасность

Только HTTPS. Запросы по HTTP отклоняются.
Не храните токены в open-source репозиториях и frontend-коде.
Если токен утёк — клиника может отозвать его в разделе «Настройки → Интеграции».
Rate-limit: 120 запросов/минуту на токен. При превышении — 429 Too Many Requests.

Эндпоинты

Основные методы для телефонии и CRM

GET /api/v1/clinic/me

Информация о клинике, к которой выдан токен. Используется для проверки авторизации.

{
  "ok": true,
  "clinic": {
    "id": "clinic2026_demo",
    "name": "Smile Dental Clinic",
    "city": "Tashkent",
    "phone": "+998 71 200 11 22",
    "timezone": "Asia/Tashkent",
    "plan": "pro",
    "patients_count": 1685
  }
}

GET /api/v1/patients/find?phone=+998901234567

Поиск пациента по номеру телефона. Используется для on-call popup — моментальной карточки пациента при входящем звонке. Возвращает patient: null если номер не найден в базе.

{
  "ok": true,
  "patient": {
    "id": "p_a1b2c3",
    "name": "Каримова Мадина",
    "phone": "+998 91 456-78-90",
    "age": 34,
    "doctor": "д-р Юсупов",
    "last_visit": "2026-04-09",
    "next_appt": "2026-05-12T11:00:00+05:00",
    "balance": 0,
    "tags": ["VIP", "имплантация"],
    "url": "https://app.stompro.uz/?patient=p_a1b2c3"
  }
}

POST /api/v1/calls/event

Регистрация события звонка: ringing, answered, missed, ended. Звонок появится в журнале клиники в разделе «Звонки» с привязкой к карточке пациента (если найден).

phone · string · обязательно · номер в E.164

type · enum · incoming / outgoing

status · enum · ringing / answered / missed / ended

started_at · ISO 8601 · время начала звонка

duration · integer · секунды (для ended)

recording_url · string · опц. ссылка на запись разговора

operator · string · опц. имя сотрудника, принявшего звонок

external_id · string · опц. ID звонка в вашей системе (для дедупликации)

{
  "ok": true,
  "call_id": "call_x9y8z7",
  "patient_matched": true,
  "patient_id": "p_a1b2c3"
}

POST /api/v1/leads

Создание лида (потенциального клиента). Используйте если звонок пришёл с неизвестного номера — StomPro создаст лид в воронке продаж клиники с источником «Звонок».

POST /api/v1/leads
{
  "phone": "+998901112233",
  "name": "Неизвестный (звонок)",
  "source": "call",
  "channel": "moizvonki",
  "comment": "Входящий звонок 14:32, не дозвонились"
}

{
  "ok": true,
  "lead_id": "lead_q1w2e3",
  "url": "https://app.stompro.uz/?lead=lead_q1w2e3"
}

GET /api/v1/users

Список сотрудников клиники (врачи, администраторы, ассистенты) — для маппинга «номер → оператор».

{
  "ok": true,
  "users": [
    {"id": "u_1", "name": "д-р Юсупов",  "role": "doctor",  "phone": "+998 90 111 22 33"},
    {"id": "u_2", "name": "д-р Назаров", "role": "doctor",  "phone": "+998 90 444 55 66"},
    {"id": "u_3", "name": "Алиса",       "role": "admin",   "phone": "+998 91 777 88 99"}
  ]
}

POST /api/v1/integration/disconnect

Отзыв токена с вашей стороны (например, пользователь отписался от вашего сервиса). После вызова токен становится невалидным, все последующие запросы вернут 401.

Marketplace-виджет

«Подключить в один клик» — как у amoCRM

Сценарий для партнёров, которые хотят размещение в Marketplace StomPro. Владелец клиники в интерфейсе StomPro открывает «Настройки → Интеграции → Marketplace», находит ваш сервис и нажимает «Подключить». StomPro перенаправляет его на сайт партнёра для авторизации (или оплаты подписки). После успешного OAuth-обмена пользователь возвращается обратно в StomPro — интеграция активна, токен клиники сохранён на стороне партнёра.

1Клиника жмёт «Подключить»
в Marketplace StomPro

→

2Redirect на ваш сайт
с state и redirect_uri

→

3Авторизация на сайте партнёра
логин или оплата подписки

4Партнёр → StomPro
token exchange с partner_secret

→

5StomPro возвращает clinic_token
и подтверждает интеграцию

→

6Redirect клиента в StomPro
клиника видит «Подключено»

Шаг 1-2 — Authorize URL (StomPro открывает на стороне партнёра)

GET https://your-service.com/oauth/stompro?
    partner_id=stompro_partner_xxx
    &clinic_id=clinic2026_demo
    &clinic_name=Smile+Dental+Clinic
    &state=random_state_string
    &redirect_uri=https://app.stompro.uz/integrations/callback

Шаг 4 — Token exchange (вы → нам)

POST https://app.stompro.uz/api/v1/oauth/token
Content-Type: application/json

{
  "partner_id": "stompro_partner_xxx",
  "partner_secret": "ps_secret_8f3d9e2c4b1f7e6d",
  "clinic_id": "clinic2026_demo",
  "state": "random_state_string",
  "external_account_id": "moizvonki_user_42",
  "scopes": ["calls:write", "patients:read", "leads:write"]
}

→ HTTP 200
{
  "ok": true,
  "clinic_token": "st_clinic_a8f3d9e2c4b1f7e6d5a4c3b2a1f0e9d8",
  "expires_at": null,
  "redirect_url": "https://app.stompro.uz/integrations/callback?status=connected&state=random_state_string"
}

Шаг 6 — Redirect клиента обратно

Партнёр перенаправляет браузер пользователя на redirect_url из ответа token exchange. В StomPro клиника увидит сервис партнёра в списке «Подключено» — с возможностью настройки scopes и моментального отзыва доступа.

Подпись OAuth-запросов: всё взаимодействие с /oauth/token требует обязательного TLS 1.2+ и валидного partner_secret. Параметр state проверяется на дубли (защита от CSRF) и истекает через 10 минут.

Webhooks

Real-time события от StomPro вашему сервису

Если ваш сервис должен реагировать на события клиники (например, отправить SMS-напоминание перед приёмом), укажите webhook_url при подключении интеграции. StomPro будет слать POST с JSON.

События

patient.created — новый пациент в базе клиники
appointment.created — записан на приём
appointment.completed — приём завершён
appointment.cancelled — приём отменён
payment.received — получена оплата
lead.created — создан лид
lead.stage_changed — лид перешёл на следующий этап воронки
integration.revoked — клиника отозвала ваш токен

Пример webhook payload

POST https://your-service.com/webhooks/stompro HTTP/1.1
X-StomPro-Event: appointment.created
X-StomPro-Signature: sha256=8f3d9e2c4b1f7e6d5a4c3b2a1f0e9d8...
Content-Type: application/json

{
  "event": "appointment.created",
  "clinic_id": "clinic2026_demo",
  "timestamp": "2026-04-28T14:32:15+05:00",
  "data": {
    "appointment_id": "appt_z1x2c3",
    "patient": {
      "id": "p_a1b2c3",
      "name": "Каримова Мадина",
      "phone": "+998 91 456-78-90"
    },
    "doctor": "д-р Юсупов",
    "starts_at": "2026-05-12T11:00:00+05:00",
    "duration": 60,
    "service": "Имплантация",
    "price": 8500000
  }
}

Подпись X-StomPro-Signature = HMAC-SHA256 от тела запроса с ключом partner_secret. Проверяйте её перед обработкой.

Retry-политика

Если ваш endpoint вернул 5xx или таймаут (10 сек), StomPro повторит запрос по схеме: 30 сек → 2 мин → 10 мин → 1 час → 6 часов. После 5 неудачных попыток — событие отбрасывается.

Идемпотентность · Версионирование · SLA

Что вы получаете в продакшене

Idempotency-Key

Все записывающие эндпоинты (POST) принимают заголовок Idempotency-Key: <uuid>. При сетевом сбое можно безопасно повторить запрос с тем же ключом — StomPro вернёт результат первой попытки, без дублей в БД. Окно дедупликации — 24 часа.

Стабильное версионирование

Текущая версия — v1. Breaking changes — только в новой мажорной версии. После анонса v2 предыдущая поддерживается минимум 12 месяцев — у вас гарантированный запас на миграцию.

Sandbox-окружение

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

Поддержка партнёров

Прямой канал с инженером StomPro: Telegram, email. Время ответа в рабочие часы — до 4 часов. Критические инциденты в Production — 24/7. Часовой пояс — Asia/Tashkent (UTC+5).

Ошибки и лимиты

HTTP-коды и формат ошибок

Код	Когда возникает
`200`	Запрос выполнен успешно
`400`	Невалидный JSON или отсутствует обязательное поле
`401`	Неверный или отсутствующий токен
`403`	Токен валидный, но без нужного scope
`404`	Ресурс не найден (например, пациент по ID)
`409`	Конфликт (например, дубль `external_id`)
`429`	Превышен rate-limit (120 req/min на токен)
`500`	Внутренняя ошибка StomPro — повторите запрос

Формат ошибки

{
  "ok": false,
  "error": "missing_field",
  "message": "Field 'phone' is required",
  "field": "phone"
}

StomPro Public API

API для партнёров и интеграторов

Телефония

Мессенджеры

Marketplace-виджеты

Webhooks

3 шага до первого запроса

Подайте партнёрскую заявку

Получите токен клиники

Первый запрос

Bearer-токен в каждом запросе

Если токен невалидный

Безопасность

Основные методы для телефонии и CRM

«Подключить в один клик» — как у amoCRM

Шаг 1-2 — Authorize URL (StomPro открывает на стороне партнёра)

Шаг 4 — Token exchange (вы → нам)

Шаг 6 — Redirect клиента обратно

Real-time события от StomPro вашему сервису

События

Пример webhook payload

Retry-политика

Что вы получаете в продакшене

Idempotency-Key

Стабильное версионирование

Sandbox-окружение

Поддержка партнёров

HTTP-коды и формат ошибок

Формат ошибки

Запросить доступ к API