API для разработчиков

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

Откройте в кабинете Настройки → Для разработчиков. Раздел доступен владельцу и администраторам проекта.
На вкладке «API-ключи» нажмите «Новый ключ», выберите доступы и скопируйте ключ и секрет — секрет показывается один раз.
Отправьте первый запрос — метод app.info вернёт данные проекта и права ключа.

curl -X POST "https://<поддомен>.miramica.ru/api/v1/app.info" \
  -H "X-Api-Key: mk_live_3f9c2a71d04b8e6a15c0f2d9" \
  -H "X-Api-Secret: mks_Q2xh...секрет"

Авторизация

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

Способ	Как передать
Заголовки (рекомендуется)	`X-Api-Key: mk_live_…` и `X-Api-Secret: mks_…`
Bearer	`Authorization: Bearer mk_live_….mks_…` — ключ и секрет через точку
Входящий вебхук	Токен уже в URL: `/api/rest/<ID проекта>/<токен>/<метод>` — заголовки не нужны. ID проекта — поддомен кабинета (например `zdorovie`), его видно в разделе «Для разработчиков».

При создании ключа выбираются доступы (scopes). Право на запись включает чтение того же раздела.

Scope	Что разрешает
`crm:read`	Чтение лидов, сделок и активностей; контактов и компаний — только при включённом доступе к персональным данным
`crm:write`	Создание, изменение и удаление CRM-сущностей
`tasks:read`	Чтение задач
`tasks:write`	Создание, изменение и удаление задач
`catalog:read`	Чтение каталога товаров, услуг и категорий
`catalog:write`	Создание и изменение товаров / услуг
`bookings:read`	Чтение бронирований, записей и объектов
`bookings:write`	Создание и изменение бронирований и записей
`calendar:read`	Чтение событий обычного календаря компании
`calendar:write`	Создание, изменение и удаление событий календаря компании
`drive:read`	Чтение файлов и папок диска компании
`drive:write`	Загрузка/удаление файлов и создание/удаление папок диска
`payments:read`	Чтение оплат (ссылки, folio, клиника)
`staff:read`	Чтение сотрудников (без паролей и секретов)

Не размещайте секрет в коде сайта или мобильного приложения — вызывайте API только со своего сервера. Для форм на сайте используйте входящий вебхук с минимальными правами.

Персональные данные (152-ФЗ)

По умолчанию персональные данные клиентов и компаний через API недоступны. Анонимного доступа к данным проекта нет: каждый запрос требует API-ключа или секретного токена входящего вебхука с нужными правами.

Что	Доступ к ПДн выключен (по умолчанию)	Доступ к ПДн включён
`crm.contact.`, `crm.company.`	HTTP 403, `PII_ACCESS_DISABLED` — и чтение, и запись	Работают при наличии `crm:read` / `crm:write`
`booking.`, `calendar.appointment.`	Работают; ФИО, телефон, e-mail и комментарий клиента в ответе — `null`, добавлено `"piiRedacted": true`	Полные данные (без паспорта / документов / base64)
`calendar.event.*`	`description` и `meta` — `null`; `title` — телефоны/e-mail убраны (`"piiRedacted": true`)	Полные поля события (без секретов в meta)
`crm.lead.`, `crm.deal.`, `crm.task.*`	Свободный текст (`notes` / `description` / `subject` / `body` / `comment` / `note`) — `null`; `title` — телефоны/e-mail убраны, авто-заголовки виджетов с ФИО заменены на `[ПДн]`; суммы, стадии, id и даты сохраняются	Полные данные из whitelist полей
`crm.activity.*`	`phone`, `subject`, `body` — `null`	Полные данные
Платежи (`payment.*` / вебхуки `payment.received`)	`note` / `description` — `null`; суммы, статусы, id связей	Whitelist полей (без паспорта / банковских реквизитов / токенов)
Вебхуки `contact.`, `company.`	Только `id`, `crmId`, связи и даты, `"piiRedacted": true`	Поля из списка методов (без паспортных и банковских данных)
Вебхуки `booking.`, `appointment.`	ФИО, телефон, e-mail и комментарий — `null`	Полные данные (whitelist)
Вебхуки `lead.`, `deal.`, `task.*`	Только id, стадии/статусы, суммы, связи и даты (`title` / `notes` / `description` не отдаются)	Whitelist полей
Прочие сущности в вебхуках	Только безопасный allowlist (id, связи `*Id`, статусы, суммы, даты) — полные строки БД не отправляются	Тот же бизнес-allowlist (полные строки БД не отправляются)

Включить доступ может только владелец проекта: кабинет → Настройки → Для разработчиков → блок «Персональные данные клиентов и компаний» → «Разрешить доступ через API». Выключить может любой сотрудник с правом «API-ключи и вебхуки»; после выключения неотправленные вебхуки с персональными данными отменяются. Текущее состояние возвращает app.info (personalDataAccess), а app.methods помечает такие методы флагом personalData.

{
  "error": "PII_ACCESS_DISABLED",
  "error_description": "Доступ к персональным данным клиентов и компаний через API отключён. Владелец проекта может включить его в разделе «Для разработчиков» → «Персональные данные»."
}

Даже при включённом доступе API и вебхуки не передают паспортные данные и документы клиентов, банковские реквизиты компаний, токены гостевых ссылок и служебные секреты.

Включая доступ, владелец проекта как оператор персональных данных отвечает за законность их передачи во внешние системы: правовое основание и согласия субъектов, договор поручения обработки с получателем, хранение ключей и адресов вебхуков, а также локализацию данных граждан РФ (ч. 5 ст. 18 152-ФЗ). Формы на сайте могут создавать лиды без доступа к ПДн — используйте crm.lead.add.

Запросы и ответы

Базовый адрес: https://<поддомен>.miramica.ru/api/v1/<метод>. Точный адрес вашего проекта показан в кабинете. Поддерживаются GET (параметры в query) и POST (JSON-тело, Content-Type: application/json). Параметры query и тела объединяются. Суффикс .json в имени метода допускается: crm.deal.list.json.

Поля для создания и изменения можно передать как в объекте fields (как в Битрикс24), так и плоско на верхнем уровне.

{ "fields": { "title": "Заявка с сайта", "amount": 15000 } }

Успешный ответ — HTTP 200 с полем result. Списки дополнительно возвращают total и next — смещение следующей страницы (отсутствует на последней). Поле time — время обработки запроса.

Постраничная выборка: limit — от 1 до 100 (по умолчанию 50), start (или offset) — смещение. Списки отсортированы от новых к старым.

{
  "result": [ { "id": "cm8x…", "title": "Поставка оборудования", "stage": "new" } ],
  "total": 134,
  "next": 50,
  "time": { "start": "…", "finish": "…", "duration": 12 }
}

Даты передаются и возвращаются в ISO-8601 (UTC), суммы — числами, идентификаторы — строками.

Ошибки

При ошибке возвращается соответствующий HTTP-статус и JSON с кодом и описанием на русском языке.

{
  "error": "INSUFFICIENT_SCOPE",
  "error_description": "Недостаточно прав: метод crm.deal.add требует scope crm:write"
}

HTTP	error	Когда
400	`INVALID_PARAMS`	Не заполнено обязательное поле, неверный формат, несуществующая стадия
401	`UNAUTHORIZED`	Нет ключа, неверный секрет, ключ отозван, вебхук выключен
402	`PAYMENT_REQUIRED`	Достигнут лимит тарифа (например, по числу клиентов)
403	`INSUFFICIENT_SCOPE`	У ключа нет нужного доступа
403	`PII_ACCESS_DISABLED`	Метод контактов / компаний, а доступ к персональным данным через API в проекте выключен
404	`NOT_FOUND`	Метод или запись не найдены
405	`METHOD_NOT_ALLOWED`	HTTP-метод кроме GET и POST
409	`CONFLICT`	Конфликт данных
429	`RATE_LIMITED`	Превышен лимит запросов
500	`INTERNAL_ERROR`	Внутренняя ошибка — повторите позже

Лимиты

120 запросов в минуту на каждый ключ или входящий вебхук (окно — календарная минута).
В каждом ответе: X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунд до сброса окна).
При превышении — HTTP 429 и заголовок Retry-After (секунды).
До 20 активных API-ключей, 20 входящих и 20 исходящих вебхуков на проект.
Списки — не больше 100 записей за запрос.

Методы REST API

Адрес метода: https://<поддомен>.miramica.ru/api/v1/<метод> или https://<поддомен>.miramica.ru/api/rest/<ID проекта>/<токен>/<метод> для входящего вебхука. Список методов доступен и через API — app.methods.

Метод	Scope	Описание
Приложение
`app.info`	—	Информация о проекте
`app.methods`	—	Список методов
Контакты
`crm.contact.list`	`crm:read`	Список контактов
`crm.contact.get`	`crm:read`	Контакт по ID
`crm.contact.add`	`crm:write`	Создать контакт
`crm.contact.update`	`crm:write`	Изменить контакт
`crm.contact.delete`	`crm:write`	Удалить контакт
Компании
`crm.company.list`	`crm:read`	Список компаний
`crm.company.get`	`crm:read`	Компания по ID
`crm.company.add`	`crm:write`	Создать компанию
`crm.company.update`	`crm:write`	Изменить компанию
Лиды
`crm.lead.list`	`crm:read`	Список лидов
`crm.lead.get`	`crm:read`	Лид по ID
`crm.lead.add`	`crm:write`	Создать лид
`crm.lead.update`	`crm:write`	Изменить лид
`crm.lead.delete`	`crm:write`	Удалить лид
Сделки
`crm.deal.list`	`crm:read`	Список сделок
`crm.deal.get`	`crm:read`	Сделка по ID
`crm.deal.add`	`crm:write`	Создать сделку
`crm.deal.update`	`crm:write`	Изменить сделку
`crm.deal.delete`	`crm:write`	Удалить сделку
Активности
`crm.activity.list`	`crm:read`	Список активностей
`crm.activity.add`	`crm:write`	Добавить активность / заметку
Задачи
`tasks.task.list`	`tasks:read`	Список задач
`tasks.task.get`	`tasks:read`	Задача по ID
`tasks.task.add`	`tasks:write`	Создать задачу
`tasks.task.update`	`tasks:write`	Изменить задачу
`tasks.task.complete`	`tasks:write`	Завершить задачу
`tasks.task.delete`	`tasks:write`	Удалить задачу
Каталог
`catalog.product.list`	`catalog:read`	Каталог товаров и услуг
`catalog.product.get`	`catalog:read`	Товар / услуга по ID
`catalog.product.add`	`catalog:write`	Создать товар / услугу
`catalog.product.update`	`catalog:write`	Изменить товар / услугу
`catalog.category.list`	`catalog:read`	Категории каталога
Бронирования
`booking.list`	`bookings:read`	Бронирования · Отели
`booking.get`	`bookings:read`	Бронирование по ID · Отели
`booking.add`	`bookings:write`	Создать бронирование · Отели
`booking.update`	`bookings:write`	Изменить бронирование · Отели
`booking.cancel`	`bookings:write`	Отменить бронирование · Отели
`property.list`	`bookings:read`	Объекты · Отели, автосервис и др. с точками
Записи
`calendar.appointment.list`	`bookings:read`	Записи на приём · Клиники, салоны, фитнес, автосервисы
`calendar.appointment.get`	`bookings:read`	Запись по ID · Клиники, салоны, фитнес, автосервисы
`calendar.appointment.add`	`bookings:write`	Создать запись · Клиники, салоны, фитнес, автосервисы
`calendar.appointment.update`	`bookings:write`	Изменить запись · Клиники, салоны, фитнес, автосервисы
`calendar.appointment.cancel`	`bookings:write`	Отменить запись · Клиники, салоны, фитнес, автосервисы
Календарь
`calendar.get`	`calendar:read`	Календарь компании
`calendar.event.list`	`calendar:read`	События календаря компании
`calendar.event.get`	`calendar:read`	Событие календаря по ID
`calendar.event.add`	`calendar:write`	Создать событие календаря
`calendar.event.update`	`calendar:write`	Изменить событие календаря
`calendar.event.delete`	`calendar:write`	Удалить событие календаря
Диск
`drive.browse`	`drive:read`	Диск: содержимое папки
`drive.folder.add`	`drive:write`	Диск: создать папку
`drive.folder.delete`	`drive:write`	Диск: удалить папку
`drive.file.get`	`drive:read`	Диск: метаданные файла
`drive.file.add`	`drive:write`	Диск: загрузить файл
`drive.file.download`	`drive:read`	Диск: скачать файл
`drive.file.delete`	`drive:write`	Диск: удалить файл
Оплаты
`payment.list`	`payments:read`	Список оплат
`payment.get`	`payments:read`	Оплата по ID
Сотрудники
`user.list`	`staff:read`	Сотрудники

Приложение

`app.info`

без scope

Информация о проекте

Название, направление, валюта, часовой пояс проекта, публичный projectId (поддомен кабинета), способ авторизации, доступы текущего ключа и personalDataAccess — открыт ли доступ к персональным данным. Поле tenantId совпадает с projectId.

curl -X POST "https://<поддомен>.miramica.ru/api/v1/app.info" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

`app.methods`

без scope

Список методов

Все методы API с требуемым scope, флагом personalData (метод работает с персональными данными) и allowed — доступен ли метод текущему ключу с учётом настройки персональных данных.

curl -X POST "https://<поддомен>.miramica.ru/api/v1/app.methods" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

Контакты

`crm.contact.list`

crm:read

Список контактов

Контакты проекта, от новых к старым. Обезличенные по 152-ФЗ записи не возвращаются. Нужен включённый доступ к персональным данным, иначе HTTP 403 PII_ACCESS_DISABLED.

Параметр	Тип	Описание
`q`	string	Поиск по имени, фамилии, телефону, email
`updatedSince`	string (ISO-8601)	Только записи, изменённые не раньше этой даты
`limit`	number	1–100, по умолчанию 50
`start`	number	Смещение (offset)

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.contact.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "q": "Иванов", "limit": 20 }'

`crm.contact.get`

crm:read

Контакт по ID

Один контакт. Ответ — объект в том же формате, что в списке. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`id`обязательный	string	ID контакта

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.contact.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8xc01…" }'

`crm.contact.add`

crm:write

Создать контакт

Создаёт контакт; ответственный — владелец ключа. Учитывает лимит клиентов по тарифу (HTTP 402). Нужен доступ к персональным данным; без него для заявок используйте crm.lead.add.

Параметр	Тип	Описание
`firstName`обязательный	string	Имя (до 120 символов)
`lastName`	string	Фамилия
`phone`	string	Основной телефон
`email`	string	Основной email
`companyId`	string	ID компании проекта
`notes`	string	Комментарий (до 5000 символов)

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.contact.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "firstName": "Анна",
    "lastName": "Смирнова",
    "phone": "+79991234567",
    "email": "anna@example.com"
  }
}'

`crm.contact.update`

crm:write

Изменить контакт

Меняет только переданные поля. Новый phone/email становится основным, остальные телефоны и адреса сохраняются. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`id`обязательный	string	ID контакта
`fields`обязательный	object	firstName, lastName, phone, email, companyId, notes

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.contact.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8xd77…", "fields": { "phone": "+79990000000", "notes": "VIP-клиент" } }'

`crm.contact.delete`

crm:write

Удалить контакт

Удаляет контакт проекта. Вызывает событие contact.deleted. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`id`обязательный	string	ID контакта

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.contact.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8xd77…" }'

Компании

`crm.company.list`

crm:read

Список компаний

Компании проекта. Нужен доступ к персональным данным, иначе HTTP 403 PII_ACCESS_DISABLED.

Параметр	Тип	Описание
`q`	string	Поиск по названию и ИНН
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.company.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "q": "7701" }'

`crm.company.get`

crm:read

Компания по ID

Одна компания. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`id`обязательный	string	ID компании

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.company.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8y…" }'

`crm.company.add`

crm:write

Создать компанию

Создаёт компанию; ответственный — владелец ключа. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`name`обязательный	string	Название
`legalName`	string	Полное юридическое название
`inn`	string	ИНН
`kpp`	string	КПП
`phone`	string	Телефон
`email`	string	Email
`website`	string	Сайт
`notes`	string	Комментарий

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.company.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "name": "ООО «Ромашка»", "inn": "7701234567" } }'

`crm.company.update`

crm:write

Изменить компанию

Меняет только переданные поля. Нужен доступ к персональным данным.

Параметр	Тип	Описание
`id`обязательный	string	ID компании
`fields`обязательный	object	name, legalName, inn, kpp, phone, email, website, notes

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.company.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8y…", "fields": { "phone": "+74951112233", "website": "https://romashka.ru" } }'

Лиды

`crm.lead.list`

crm:read

Список лидов

Лиды проекта.

Параметр	Тип	Описание
`status`	string	Код статуса воронки, например `new`
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.lead.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "new" }'

`crm.lead.get`

crm:read

Лид по ID

Один лид.

Параметр	Тип	Описание
`id`обязательный	string	ID лида

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.lead.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8z…" }'

`crm.lead.add`

crm:write

Создать лид

Создаёт лид в воронке по умолчанию (или в funnelId). Статус по умолчанию — new; источник по умолчанию — api.

Параметр	Тип	Описание
`title`обязательный	string	Название
`status`	string	Код статуса воронки лидов
`funnelId`	string	ID воронки
`source`	string	Источник, например `website`
`amount`	number	Сумма
`currency`	string	Код валюты ISO, например `RUB`
`contactId`	string	ID контакта
`companyId`	string	ID компании
`notes`	string	Комментарий

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.lead.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "title": "Заявка с сайта", "source": "website", "amount": 25000 } }'

`crm.lead.update`

crm:write

Изменить лид

Меняет переданные поля. Смена status вызывает событие lead.status_changed.

Параметр	Тип	Описание
`id`обязательный	string	ID лида
`fields`обязательный	object	title, status, source, amount, currency, notes, contactId, companyId

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.lead.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8z…", "fields": { "status": "qualified", "amount": 30000 } }'

`crm.lead.delete`

crm:write

Удалить лид

Удаляет лид. Вызывает событие lead.deleted.

Параметр	Тип	Описание
`id`обязательный	string	ID лида

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.lead.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm8z…" }'

Сделки

`crm.deal.list`

crm:read

Список сделок

Сделки проекта (в автосервисе — заказ-наряды).

Параметр	Тип	Описание
`stage`	string	Код стадии
`funnelId`	string	ID воронки
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.deal.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "negotiation", "limit": 100 }'

`crm.deal.get`

crm:read

Сделка по ID

Одна сделка.

Параметр	Тип	Описание
`id`обязательный	string	ID сделки

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.deal.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm90…" }'

`crm.deal.add`

crm:write

Создать сделку

Создаёт сделку в воронке по умолчанию (или в funnelId). Стадия по умолчанию — new; код стадии проверяется по настройкам воронки.

Параметр	Тип	Описание
`title`обязательный	string	Название
`stage`	string	Код стадии
`funnelId`	string	ID воронки
`amount`	number	Сумма
`currency`	string	Код валюты
`contactId`	string	ID контакта
`companyId`	string	ID компании
`notes`	string	Комментарий

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.deal.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "title": "Поставка оборудования", "amount": 480000, "contactId": "cm8xc01…" } }'

`crm.deal.update`

crm:write

Изменить сделку

Меняет переданные поля. Смена stage вызывает событие deal.stage_changed.

Параметр	Тип	Описание
`id`обязательный	string	ID сделки
`fields`обязательный	object	title, stage, amount, currency, notes, contactId

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.deal.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm90…", "fields": { "stage": "won" } }'

`crm.deal.delete`

crm:write

Удалить сделку

Удаляет сделку. Вызывает событие deal.deleted. Отдельного «cancel» нет — используйте смену стадии или удаление.

Параметр	Тип	Описание
`id`обязательный	string	ID сделки

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.deal.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm90…" }'

Активности

`crm.activity.list`

crm:read

Список активностей

Заметки, звонки, письма и встречи, привязанные к CRM-сущностям. Без доступа к персональным данным поле phone — null.

Параметр	Тип	Описание
`type`	string	`note`, `call`, `email`, `meeting`, `system`
`contactId`	string	Фильтр по контакту
`leadId`	string	Фильтр по лиду
`dealId`	string	Фильтр по сделке
`companyId`	string	Фильтр по компании
`bookingId`	string	Фильтр по бронированию
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.activity.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "type": "note", "contactId": "cm8xc01…" }'

`crm.activity.add`

crm:write

Добавить активность / заметку

Создаёт активность. Тип по умолчанию — note (заметка). Автор — владелец ключа / вебхука.

Параметр	Тип	Описание
`subject`обязательный	string	Тема
`type`	string	`note` (по умолчанию), `call`, `email`, `meeting`, `system`
`body`	string	Текст
`phone`	string	Телефон (для звонка)
`durationSec`	number	Длительность в секундах
`contactId`	string	Контакт
`leadId`	string	Лид
`dealId`	string	Сделка
`companyId`	string	Компания
`bookingId`	string	Бронирование

curl -X POST "https://<поддомен>.miramica.ru/api/v1/crm.activity.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "type": "note", "subject": "Согласовали смету", "body": "Клиент ок", "contactId": "cm8xc01…" } }'

Задачи

`tasks.task.list`

tasks:read

Список задач

Задачи проекта.

Параметр	Тип	Описание
`status`	string	`open`, `in_progress`, `done` или `cancelled`
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "open" }'

`tasks.task.get`

tasks:read

Задача по ID

Одна задача.

Параметр	Тип	Описание
`id`обязательный	string	ID задачи

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm91…" }'

`tasks.task.add`

tasks:write

Создать задачу

Создаёт задачу. Без assigneeId исполнитель — владелец ключа.

Параметр	Тип	Описание
`title`обязательный	string	Название
`description`	string	Описание
`dueAt`	string (ISO-8601)	Срок
`assigneeId`	string	ID сотрудника-исполнителя
`contactId`	string	Связанный контакт
`dealId`	string	Связанная сделка
`leadId`	string	Связанный лид

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "title": "Перезвонить клиенту", "dueAt": "2026-10-16T10:00:00Z", "contactId": "cm8xc01…" } }'

`tasks.task.update`

tasks:write

Изменить задачу

Меняет переданные поля. Смена status вызывает событие task.status_changed.

Параметр	Тип	Описание
`id`обязательный	string	ID задачи
`fields`обязательный	object	title, description, status, dueAt, assigneeId, contactId

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm91…", "fields": { "status": "in_progress" } }'

`tasks.task.complete`

tasks:write

Завершить задачу

Устанавливает статус done (эквивалент tasks.task.update с status: "done").

Параметр	Тип	Описание
`id`обязательный	string	ID задачи

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.complete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm91…" }'

`tasks.task.delete`

tasks:write

Удалить задачу

Удаляет задачу. Вызывает событие task.deleted.

Параметр	Тип	Описание
`id`обязательный	string	ID задачи

curl -X POST "https://<поддомен>.miramica.ru/api/v1/tasks.task.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm91…" }'

Каталог

`catalog.product.list`

catalog:read

Каталог товаров и услуг

Товары и услуги проекта, по алфавиту. Поле stockQty — текущий остаток.

Параметр	Тип	Описание
`q`	string	Поиск по названию, артикулу, штрихкоду
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/catalog.product.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "q": "масло" }'

`catalog.product.get`

catalog:read

Товар / услуга по ID

Один товар или услуга (можно передать числовой crmId).

Параметр	Тип	Описание
`id`обязательный	string	ID или crmId товара

curl -X POST "https://<поддомен>.miramica.ru/api/v1/catalog.product.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "prd_…" }'

`catalog.product.add`

catalog:write

Создать товар / услугу

Создаёт позицию каталога. stockQty — начальный остаток; durationMin — длительность услуги в минутах.

Параметр	Тип	Описание
`name`обязательный	string	Название
`catalogId`	string	ID категории
`sku`	string	Артикул
`barcode`	string	Штрихкод
`description`	string	Описание
`price`	number	Цена
`currency`	string	Валюта
`vatRate`	number	НДС %, по умолчанию 20
`unit`	string	Ед. изм., по умолчанию `шт`
`stockQty`	number	Остаток
`durationMin`	number	Длительность услуги, мин
`isActive`	boolean	Активен, по умолчанию true

curl -X POST "https://<поддомен>.miramica.ru/api/v1/catalog.product.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "name": "Масло моторное 5W-30", "sku": "OIL-530", "price": 3200, "stockQty": 14 } }'

`catalog.product.update`

catalog:write

Изменить товар / услугу

Меняет переданные поля, в том числе остаток stockQty.

Параметр	Тип	Описание
`id`обязательный	string	ID товара
`fields`обязательный	object	name, catalogId, sku, barcode, description, price, currency, vatRate, unit, stockQty, durationMin, isActive

curl -X POST "https://<поддомен>.miramica.ru/api/v1/catalog.product.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "prd_…", "fields": { "stockQty": 20, "price": 3400 } }'

`catalog.category.list`

catalog:read

Категории каталога

Дерево категорий (parentId — родитель).

Параметр	Тип	Описание
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/catalog.category.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

Бронирования

`booking.list`

bookings:readОтели

Бронирования

Бронирования номеров. Фильтр по датам — пересечение периода проживания с интервалом from–to. Без доступа к персональным данным guestName, guestPhone, guestEmail и notes возвращаются как null ("piiRedacted": true); создавать и менять брони с данными гостя можно.

Параметр	Тип	Описание
`from`	string (ISO-8601)	Начало периода
`to`	string (ISO-8601)	Конец периода
`status`	string	`new`, `confirmed`, `checked_in`, `checked_out`, `cancelled`, `no_show`
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/booking.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-10-01", "to": "2026-10-31", "status": "confirmed" }'

`booking.get`

bookings:readОтели

Бронирование по ID

Одно бронирование.

Параметр	Тип	Описание
`id`обязательный	string	ID бронирования

curl -X POST "https://<поддомен>.miramica.ru/api/v1/booking.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm92…" }'

`booking.add`

bookings:writeОтели

Создать бронирование

Создаёт бронь. propertyId и roomTypeId должны принадлежать проекту; статус по умолчанию — confirmed. Не проверяет тарифные правила и пересечения номеров — для полной логики используйте кабинет.

Параметр	Тип	Описание
`propertyId`обязательный	string	ID объекта
`roomTypeId`обязательный	string	ID типа номера
`checkIn`обязательный	string (ISO-8601)	Заезд
`checkOut`обязательный	string (ISO-8601)	Выезд
`guestName`обязательный	string	ФИО гостя
`totalAmount`обязательный	number	Сумма
`roomId`	string	Конкретный номер
`contactId`	string	Контакт
`guestsCount`	number	Число гостей, по умолчанию 1
`guestPhone`	string	Телефон
`guestEmail`	string	Email
`prepaidAmount`	number	Предоплата
`status`	string	Статус брони
`source`	string	Источник, по умолчанию `api`
`notes`	string	Комментарий

curl -X POST "https://<поддомен>.miramica.ru/api/v1/booking.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "propertyId": "cm6p…", "roomTypeId": "cm6t…",
    "checkIn": "2026-10-20", "checkOut": "2026-10-23",
    "guestName": "Иван Иванов", "totalAmount": 24000, "guestsCount": 2
  }
}'

`booking.update`

bookings:writeОтели

Изменить бронирование

Меняет переданные поля. Смена status вызывает событие booking.status_changed.

Параметр	Тип	Описание
`id`обязательный	string	ID бронирования
`fields`обязательный	object	status, guestName, guestPhone, guestEmail, notes, totalAmount, prepaidAmount, guestsCount, contactId, checkIn, checkOut

curl -X POST "https://<поддомен>.miramica.ru/api/v1/booking.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm92…", "fields": { "status": "checked_in" } }'

`booking.cancel`

bookings:writeОтели

Отменить бронирование

Устанавливает статус cancelled.

Параметр	Тип	Описание
`id`обязательный	string	ID бронирования

curl -X POST "https://<поддомен>.miramica.ru/api/v1/booking.cancel" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm92…" }'

`property.list`

bookings:readОтели, автосервис и др. с точками

Объекты

Список объектов / точек проекта (отели, площадки).

Параметр	Тип	Описание
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/property.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 20 }'

Записи

`calendar.appointment.list`

bookings:readКлиники, салоны, фитнес, автосервисы

Записи на приём

Записи календаря (приёмы, визиты, тренировки). Фильтр по времени начала. Без доступа к персональным данным patientName, patientPhone, patientEmail и notes возвращаются как null ("piiRedacted": true).

Параметр	Тип	Описание
`from`	string (ISO-8601)	Начало не раньше
`to`	string (ISO-8601)	Начало не позже
`status`	string	`new`, `confirmed`, `arrived`, `completed`, `cancelled`, `no_show`
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.appointment.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-10-15T00:00:00Z", "to": "2026-10-16T00:00:00Z" }'

`calendar.appointment.get`

bookings:readКлиники, салоны, фитнес, автосервисы

Запись по ID

Одна запись календаря.

Параметр	Тип	Описание
`id`обязательный	string	ID записи

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.appointment.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm93…" }'

`calendar.appointment.add`

bookings:writeКлиники, салоны, фитнес, автосервисы

Создать запись

Создаёт запись к специалисту (doctorId). Если указан serviceId, длительность и сумма берутся из услуги (если totalAmount не передан). Статус по умолчанию — confirmed.

Параметр	Тип	Описание
`doctorId`обязательный	string	ID специалиста
`startsAt`обязательный	string (ISO-8601)	Начало
`patientName`обязательный	string	ФИО пациента / клиента
`endsAt`	string (ISO-8601)	Конец (иначе +длительность услуги или 30 мин)
`serviceId`	string	ID услуги клиники
`contactId`	string	Контакт
`patientPhone`	string	Телефон
`patientEmail`	string	Email
`totalAmount`	number	Сумма
`status`	string	Статус
`source`	string	Источник, по умолчанию `api`
`notes`	string	Комментарий

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.appointment.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "doctorId": "cm6d…", "serviceId": "cm6s…",
    "startsAt": "2026-10-15T07:00:00Z", "patientName": "Анна Смирнова",
    "patientPhone": "+79991234567"
  }
}'

`calendar.appointment.update`

bookings:writeКлиники, салоны, фитнес, автосервисы

Изменить запись

Меняет переданные поля. Смена status вызывает событие appointment.status_changed.

Параметр	Тип	Описание
`id`обязательный	string	ID записи
`fields`обязательный	object	status, patientName, patientPhone, patientEmail, notes, totalAmount, startsAt, endsAt, doctorId, contactId

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.appointment.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm93…", "fields": { "status": "arrived" } }'

`calendar.appointment.cancel`

bookings:writeКлиники, салоны, фитнес, автосервисы

Отменить запись

Устанавливает статус cancelled.

Параметр	Тип	Описание
`id`обязательный	string	ID записи

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.appointment.cancel" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm93…" }'

Календарь

`calendar.get`

calendar:read

Календарь компании

Метаданные общего календаря компании (type: company). Это не записи клиники/салона (calendar.appointment.*) и не бронирования отеля (booking.*). Персональные и внешние календары сотрудников через API недоступны.

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

`calendar.event.list`

calendar:read

События календаря компании

События только общего календаря компании. Фильтр по пересечению интервала [from, to] (как в UI). Без доступа к ПДн description и meta — null, title очищается от телефонов/e-mail.

Параметр	Тип	Описание
`from`	string (ISO-8601)	Событие пересекает момент (endsAt ≥ from)
`to`	string (ISO-8601)	Событие пересекает момент (startsAt ≤ to)
`updatedSince`	string (ISO-8601)	Только изменённые не раньше даты
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.event.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-10-01T00:00:00Z", "to": "2026-10-31T23:59:59Z" }'

`calendar.event.get`

calendar:read

Событие календаря по ID

Одно событие общего календаря компании.

Параметр	Тип	Описание
`id`обязательный	string	ID события

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.event.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmev…" }'

`calendar.event.add`

calendar:write

Создать событие календаря

Создаёт событие в общем календаре компании. Поле meta — произвольный JSON без секретов (пароли/токены отбрасываются).

Параметр	Тип	Описание
`title`обязательный	string	Заголовок
`startsAt`обязательный	string (ISO-8601)	Начало
`endsAt`обязательный	string (ISO-8601)	Конец
`description`	string	Описание
`allDay`	boolean	Целый день
`userId`	string	Ответственный (сотрудник проекта)
`meta`	object	Доп. данные (location, ссылки CRM и т.п.)

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.event.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "title": "Планерка",
    "startsAt": "2026-10-15T09:00:00Z",
    "endsAt": "2026-10-15T10:00:00Z",
    "allDay": false
  }
}'

`calendar.event.update`

calendar:write

Изменить событие календаря

Меняет переданные поля события общего календаря.

Параметр	Тип	Описание
`id`обязательный	string	ID события
`fields`обязательный	object	title, description, startsAt, endsAt, allDay, userId, meta

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.event.update" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmev…", "fields": { "title": "Планерка (перенос)" } }'

`calendar.event.delete`

calendar:write

Удалить событие календаря

Удаляет событие общего календаря компании.

Параметр	Тип	Описание
`id`обязательный	string	ID события

curl -X POST "https://<поддомен>.miramica.ru/api/v1/calendar.event.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmev…" }'

Диск

`drive.browse`

drive:read

Диск: содержимое папки

Папки и файлы в каталоге диска. folderId пустой или root — корень. Путь storagePath в ответах не возвращается.

Параметр	Тип	Описание
`folderId`	string	ID папки или `root`
`entityType`	string	`general` (по умолчанию), `booking`, `lead`, `contact`, `deal`, `feed_post`
`entityId`	string	Привязка к сущности CRM / брони

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.browse" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "root" }'

`drive.folder.add`

drive:write

Диск: создать папку

Создаёт папку на диске компании.

Параметр	Тип	Описание
`name`обязательный	string	Название папки
`parentId`	string	Родительская папка
`entityType`	string	Тип привязки, по умолчанию `general`
`entityId`	string	ID сущности

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.folder.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "name": "Договоры" } }'

`drive.folder.delete`

drive:write

Диск: удалить папку

Удаляет папку и всё содержимое (вложенные папки и файлы) каскадом.

Параметр	Тип	Описание
`id`обязательный	string	ID папки

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.folder.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "df…" }'

`drive.file.get`

drive:read

Диск: метаданные файла

Метаданные файла без содержимого. Для содержимого используйте drive.file.download.

Параметр	Тип	Описание
`id`обязательный	string	ID файла

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.file.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmat…" }'

`drive.file.add`

drive:write

Диск: загрузить файл

Загрузка файла через JSON: содержимое в contentBase64 (допускается data-URL). Лимит размера — 15 МБ (как в кабинете). Учитывается квота хранилища тарифа. Путь на диске сервера клиенту не отдаётся.

Параметр	Тип	Описание
`fileName`обязательный	string	Имя файла
`contentBase64`обязательный	string	Содержимое в base64
`mimeType`	string	MIME, по умолчанию `application/octet-stream`
`folderId`	string	Папка или `root`
`entityType`	string	Тип привязки, по умолчанию `general`
`entityId`	string	ID сущности

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.file.add" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "fileName": "note.txt",
    "mimeType": "text/plain",
    "contentBase64": "SGVsbG8="
  }
}'

`drive.file.download`

drive:read

Диск: скачать файл

Возвращает содержимое файла в contentBase64. Файлы больше 15 МБ через REST недоступны (ответ 400). Подписанных URL нет — только этот метод или кабинет.

Параметр	Тип	Описание
`id`обязательный	string	ID файла

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.file.download" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmat…" }'

`drive.file.delete`

drive:write

Диск: удалить файл

Удаляет запись файла и пытается удалить объект с диска сервера.

Параметр	Тип	Описание
`id`обязательный	string	ID файла

curl -X POST "https://<поддомен>.miramica.ru/api/v1/drive.file.delete" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cmat…" }'

Оплаты

`payment.list`

payments:read

Список оплат

Объединённый список: ссылки на оплату (payment_link), оплаты folio отеля (booking_payment) и оплаты клиники (clinic_payment). У каждой записи есть поле source.

Параметр	Тип	Описание
`source`	string	`payment_link`, `booking_payment` или `clinic_payment`
`status`	string	Для ссылок/клиники: `pending`, `paid`, `cancelled` (+ `expired` для ссылок)
`bookingId`	string	Фильтр по бронированию
`dealId`	string	Фильтр по сделке (ссылки)
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/payment.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "source": "payment_link", "status": "paid" }'

`payment.get`

payments:read

Оплата по ID

Ищет оплату среди ссылок, folio и клиники. В ответе — поле source.

Параметр	Тип	Описание
`id`обязательный	string	ID оплаты

curl -X POST "https://<поддомен>.miramica.ru/api/v1/payment.get" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": "cm94…" }'

Сотрудники

`user.list`

staff:read

Сотрудники

Сотрудники проекта. Пароли, хеши и push-подписки не возвращаются.

Параметр	Тип	Описание
`active`	boolean	Только активные (`true`) или неактивные (`false`)
`limit`	number	1–100
`start`	number	Смещение

curl -X POST "https://<поддомен>.miramica.ru/api/v1/user.list" \
  -H "X-Api-Key: $MIRAMICA_KEY" \
  -H "X-Api-Secret: $MIRAMICA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

Входящие вебхуки

Входящий вебхук — это готовая ссылка с секретным токеном, по которой можно вызывать те же методы без заголовков авторизации. Удобно для форм на сайте, Zapier, Make, Albato и скриптов. Создаётся во вкладке «Входящие вебхуки»; права выбираются так же, как для ключа. Действия выполняются от имени сотрудника, создавшего вебхук. В URL используется ID проекта — поддомен кабинета (zdorovie.miramica.ru → zdorovie); старые ссылки с внутренним cuid продолжают работать.

https://<поддомен>.miramica.ru/api/rest/<ID проекта>/<токен>/<метод>

Токен — 160 бит случайных данных, хранится только в виде хеша и показывается один раз. Ссылка равносильна паролю: не публикуйте её в коде страниц. Если она попала в чужие руки — нажмите «Новый URL» или выключите вебхук: старый адрес перестанет работать сразу.

Исходящие вебхуки

Исходящий вебхук сообщает вашему серверу о событиях в проекте. Укажите URL обработчика и отметьте события во вкладке «Исходящие вебхуки». При каждом событии MirAmica отправит POST с JSON-телом. Одно событие — один запрос; если на событие подписано несколько вебхуков, каждый получит свою копию с одинаковым id события.

Заголовок	Значение
`Content-Type`	`application/json; charset=utf-8`
`User-Agent`	`MirAmica-Webhooks/1.0`
`X-MirAmica-Event`	Код события, например `deal.stage_changed`
`X-MirAmica-Event-Id`	ID события — используйте для защиты от дублей
`X-MirAmica-Delivery`	ID конкретной доставки (меняется между вебхуками)
`X-MirAmica-Timestamp`	Unix-время отправки в секундах
`X-MirAmica-Signature`	`sha256=<hex>` — HMAC-подпись запроса

{
  "id": "evt_m2b7k1x9f3a2c4d5e6f7",
  "event": "deal.stage_changed",
  "projectId": "demo-crm",
  "tenantId": "demo-crm",
  "occurredAt": "2026-10-15T09:30:12.004Z",
  "data": {
    "object": {
      "id": "cm90…",
      "title": "Поставка оборудования",
      "stage": "won",
      "amount": 480000,
      "currency": "RUB",
      "contactId": "cm8xc01…",
      "updatedAt": "2026-10-15T09:30:10.881Z"
    },
    "previous": { "stage": "negotiation" }
  },
  "auth": { "application_token": "9b1f0c7e2a6d48c3b5e1f0a9d7c6b5a4" }
}

data.object — запись после изменения (служебные поля вроде токенов и хешей не передаются). auth.application_token — токен приложения из карточки вебхука, как в Битрикс24: простая проверка, что запрос пришёл от вашего вебхука. Для надёжной проверки используйте подпись.

События

Выберите нужные события при создании исходящего вебхука. Код события приходит в поле event и заголовке X-MirAmica-Event.

Событие	Когда	Данные
`contact.created`	Контакт создан	`data.object` — контакт; без доступа к ПДн только `id`, `crmId`, связи и даты
`contact.updated`	Контакт изменён	`data.object` — контакт после изменения; без доступа к ПДн только идентификаторы
`contact.deleted`	Контакт удалён	`data.object.id`
`company.created`	Компания создана	`data.object`; без доступа к ПДн только идентификаторы
`company.updated`	Компания изменена	`data.object`; без доступа к ПДн только идентификаторы
`company.deleted`	Компания удалена	`data.object.id`
`lead.created`	Лид создан	`data.object`
`lead.updated`	Лид изменён	`data.object`; при смене статуса — `data.previous.status`
`lead.status_changed`	Лид: смена статуса	`data.object`, `data.previous.status`
`lead.deleted`	Лид удалён	`data.object.id`
`deal.created`	Сделка создана	`data.object`
`deal.updated`	Сделка изменена	`data.object`; при смене стадии — `data.previous.stage`
`deal.stage_changed`	Сделка: смена стадии	`data.object`, `data.previous.stage`
`deal.deleted`	Сделка удалена	`data.object.id`
`task.created`	Задача создана	`data.object`
`task.updated`	Задача изменена	`data.object`
`task.status_changed`	Задача: смена статуса	`data.object`, `data.previous.status`
`task.deleted`	Задача удалена	`data.object.id`
`booking.created`	Бронирование создано	Отели. `data.object`; без доступа к ПДн данные гостя — `null`
`booking.status_changed`	Бронирование: смена статуса	`data.object`, `data.previous.status`
`appointment.created`	Запись создана	Клиники, салоны, фитнес, автосервис. `data.object`; без доступа к ПДн данные клиента — `null`
`appointment.status_changed`	Запись: смена статуса	`data.object`, `data.previous.status`
`payment.received`	Оплата получена	`data.source` (`booking_payment`, `clinic_payment`, `payment_link`), `data.amount`, `data.currency`, `data.object`

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

Подпись = HMAC-SHA256(секрет, "<X-MirAmica-Timestamp>.<сырое тело запроса>") в hex с префиксом sha256=. Секрет подписи (whsec_…) — в карточке вебхука, кнопка «Показать». Считайте HMAC от сырого тела, до парсинга JSON, сравнивайте за постоянное время и отклоняйте запросы старше 5 минут.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.MIRAMICA_WEBHOOK_SECRET; // whsec_…

app.post('/miramica/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-MirAmica-Timestamp');
  const signature = req.get('X-MirAmica-Signature') || '';
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', SECRET).update(`${ts}.${req.body}`).digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!fresh || !valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  // обработайте event.event / event.data, учитывая event.id для защиты от дублей
  res.status(200).json({ ok: true });
});

Доставка и повторы

Успешная доставка — любой ответ 2xx в течение 10 секунд. Редиректы (3xx) не выполняются и считаются ошибкой.
При ошибке или таймауте — повторы через 1 мин, 5 мин, 30 мин, 2 ч и 6 ч: всего до 6 попыток. После последней доставка помечается как «Ошибка».
Порядок доставки не гарантируется, возможны повторы одного события — проверяйте id события (X-MirAmica-Event-Id).
Отвечайте быстро: примите запрос, поставьте задачу в очередь и обработайте её асинхронно.
Журнал доставок (тело запроса, код и ответ вашего сервера) хранится 30 дней — во вкладке «Журнал доставок» карточки вебхука. Там же можно повторить доставку вручную.
Кнопка «Отправить тест» отправляет событие webhook.test сразу, без автоматических повторов.
Адрес обработчика должен быть публичным: http(s), без логина и пароля в URL; локальные и внутренние адреса (localhost, 10.x, 192.168.x, 169.254.x и т. п.) запрещены.

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

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

Партнёрам маркетплейса

Приложения маркетплейса MirAmica по-прежнему работают через Partner API (/api/partner/v1, заголовок X-Api-Key). Для новых интеграций с одним проектом используйте ключи и вебхуки, описанные выше. Подробнее — на странице для партнёров.

REST API и вебхуки MirAmica

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

Авторизация

Персональные данные (152-ФЗ)

Запросы и ответы

Ошибки

Лимиты

Методы REST API

Приложение

app.info

app.methods

Контакты

crm.contact.list

crm.contact.get

crm.contact.add

crm.contact.update

crm.contact.delete

Компании

crm.company.list

crm.company.get

crm.company.add

crm.company.update

Лиды

crm.lead.list

crm.lead.get

crm.lead.add

crm.lead.update

crm.lead.delete

Сделки

crm.deal.list

crm.deal.get

crm.deal.add

crm.deal.update

crm.deal.delete

Активности

crm.activity.list

crm.activity.add

Задачи

tasks.task.list

tasks.task.get

tasks.task.add

tasks.task.update

tasks.task.complete

tasks.task.delete

Каталог

catalog.product.list

catalog.product.get

catalog.product.add

catalog.product.update

catalog.category.list

Бронирования

booking.list

booking.get

booking.add

booking.update

booking.cancel

property.list

Записи

calendar.appointment.list

calendar.appointment.get

calendar.appointment.add

calendar.appointment.update

calendar.appointment.cancel

Календарь

calendar.get

calendar.event.list

calendar.event.get

calendar.event.add

calendar.event.update

calendar.event.delete

Диск

drive.browse

drive.folder.add

drive.folder.delete

drive.file.get

drive.file.add

drive.file.download

drive.file.delete

Оплаты

payment.list

`app.info`

`app.methods`

`crm.contact.list`

`crm.contact.get`

`crm.contact.add`

`crm.contact.update`

`crm.contact.delete`

`crm.company.list`

`crm.company.get`

`crm.company.add`

`crm.company.update`

`crm.lead.list`

`crm.lead.get`

`crm.lead.add`

`crm.lead.update`

`crm.lead.delete`

`crm.deal.list`

`crm.deal.get`

`crm.deal.add`

`crm.deal.update`

`crm.deal.delete`

`crm.activity.list`

`crm.activity.add`

`tasks.task.list`

`tasks.task.get`

`tasks.task.add`

`tasks.task.update`

`tasks.task.complete`

`tasks.task.delete`

`catalog.product.list`

`catalog.product.get`

`catalog.product.add`

`catalog.product.update`

`catalog.category.list`

`booking.list`

`booking.get`

`booking.add`

`booking.update`

`booking.cancel`

`property.list`

`calendar.appointment.list`

`calendar.appointment.get`

`calendar.appointment.add`

`calendar.appointment.update`

`calendar.appointment.cancel`

`calendar.get`

`calendar.event.list`

`calendar.event.get`

`calendar.event.add`

`calendar.event.update`

`calendar.event.delete`

`drive.browse`

`drive.folder.add`

`drive.folder.delete`

`drive.file.get`

`drive.file.add`

`drive.file.download`

`drive.file.delete`

`payment.list`

`payment.get`

`user.list`