ФармМонитор.Опросы — Public API

1. 1

   Получите ключ у команды ФармМонитор — платформенный ключ выдаётся вручную (панель /admin/integrations) и показывается один раз при создании. Формат: brf_live_<случайная строка>.

2. 2

   Список опросов, доступных ключу:

   curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
     https://surveys.pharmmonitor.ru/api/v1/surveys

3. 3

   Структура анкеты — чтобы сопоставить block_id из ответов с текстом вопроса и вариантами:

   curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
     https://surveys.pharmmonitor.ru/api/v1/surveys/42/structure

4. 4

   Первая страница ответов — про постраничную и инкрементальную догрузку целиком см. раздел «Пагинация и инкрементал» ниже:

   curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
     "https://surveys.pharmmonitor.ru/api/v1/surveys/42/responses?limit=500"

Каждый запрос к /api/v1/* требует заголовок Authorization: Bearer brf_live_<ключ>. Ключ — платформенный (не привязан к пользовательской сессии), выдаётся командой ФармМонитор вручную в панели /admin/integrations и показывается один раз в момент создания.

• Один ключ может быть выдан на конкретный список организаций или на все организации сразу («мультитенантный» доступ) — эндпоинт GET /api/v1/organizations возвращает, какие именно организации видит ваш ключ.
• Отсутствие заголовка, схема, отличная от Bearer, пустой токен, а также неизвестный/отозванный/истёкший ключ — все эти случаи дают ОДИН и тот же ответ 401 {"code": "unauthorized"}. Наружу не раскрывается, какая именно из причин сработала — это осознанное решение, чтобы не давать атакующему различить «ключа не существует» от «ключ истёк».
• Запрос к ресурсу чужой организации — это НЕ ошибка авторизации, а 404: платформа не подтверждает и не опровергает существование чужого опроса.

Форма прохождения (ResponseObject) и каждого отдельного ответа (AnswerEntry) — ниже, вместе с полным словарём схем. Форма поля value зависит от типа блока (ChoiceValue, MatrixRowValue, DiaryAnswerValue и т.д.) — см. AnswerValue в словаре.

option_id (opt_<index>) вычисляется по ТЕКУЩЕЙ позиции варианта в block.options на момент КАЖДОГО запроса, а не замораживается на момент сбора ответа. Если автор анкеты переименовывает вариант — option_id остаётся стабильным (по внутренней истории rename). Если автор удаляет вариант из середины списка — option_id всех вариантов ПОСЛЕ удалённого сдвигается: один и тот же исторический ответ на неизменившийся лейбл может получить РАЗНЫЙ opt_<index> в двух выгрузках, сделанных до и после правки анкеты.

Гарантия, которую API даёт: structure[].options[].id и responses[].answers[].value.option_id взаимно согласованы В РАМКАХ ОДНОГО запроса (один и тот же opt_<index> в обеих частях одного ответа API всегда указывает на один и тот же лейбл). Гарантии стабильности opt_<index> МЕЖДУ выгрузками, разделёнными редактированием анкеты, НЕТ.

Если вашей интеграции нужно сопоставлять ответы одного и того же варианта между выгрузками за разное время — используйте label, а не option_id, как ключ сопоставления, либо запрашивайте structure заново перед каждой сверкой и не кэшируйте option_id дольше одного запроса.

То же самое относится к row_id строк matrix_scale с динамическими строками (settings.rowsFrom, ответ на другой блок определяет набор строк в рантайме): row_id стабилен только в рамках одного ответа — между респондентами и между выгрузками сопоставляйте строки по row_label.

row_id строк distribution («Распределение 100%») динамических строк не знает — набор строк всегда статичен (block.options), как у matrix_scale без rowsFrom, поэтому row_id здесь стабилен между респондентами и между выгрузками (совпадает с row_<index> в structure). Тем не менее для сопоставления строк рекомендуем row_label — тот же принцип, что и для остальных типов с построчными ответами.

Иммутабельность и анонимизация: завершённое прохождение не меняется после completed_at — за одним исключением. Анонимизация респондента меняет respondent.id (тот же псевдоним, что был у прохождений этого респондента, перестаёт совпадать между выгрузками «до» и «после» анонимизации). Если для вашей интеграции важна такая консистентность — периодически делайте полный пересбор выгрузки, а не полагайтесь на инкрементал бесконечно.

respondent.id стабилен во всех опросах ОДНОЙ организации — один и тот же псевдоним у всех прохождений одного человека внутри опросов одного владельца. МЕЖДУ организациями псевдонимы одного и того же респондента НЕ совпадают: если ваш ключ видит несколько организаций, не полагайтесь на respondent.id как на кросс-организационный идентификатор — это намеренное ограничение, а не артефакт.

Эндпоинт GET /api/v1/surveys/{id}/responses отдаёт завершённые прохождения через keyset-пагинацию: страница ответа содержит has_more (есть ли ещё данные) и next_cursor — opaque base64url-курсор, который нужно подставить в следующий запрос параметром cursor.

Важный нюанс: next_cursor приходит в ответе ВСЕГДА, даже когда has_more: false — это resume-курсор «после последней уже отданной строки». Именно его нужно сохранять для следующего запуска интеграции, а не полагаться на дату/время локально.

curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
  "https://surveys.pharmmonitor.ru/api/v1/surveys/42/responses?limit=500"

# сохраните next_cursor из тела ответа и подставьте в следующий запрос:
curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
  "https://surveys.pharmmonitor.ru/api/v1/surveys/42/responses?limit=500&cursor=<next_cursor>"

# повторяйте, пока has_more не станет false

Инкрементальная догрузка (следующий запуск загрузчика — например раз в час): сохраните ПОСЛЕДНИЙ полученный next_cursor и на следующем запуске продолжите с него, без ручного управления датами:

curl -H "Authorization: Bearer brf_live_ВАШ_КЛЮЧ" \
  "https://surveys.pharmmonitor.ru/api/v1/surveys/42/responses?cursor=<сохранённый_next_cursor>"

Альтернатива для первого запуска/пересбора данных за период — параметр completed_after (ISO 8601, строго «после»); её нельзя комбинировать с cursor в одном запросе.

Лимиты считаются на ключ API. При превышении сервер отвечает 429 с заголовком Retry-After (секунд до следующей попытки).

GET /api/v1/surveys и GET /api/v1/surveys/{id}/structure кэшируются 60 секунд на стороне сервера (в разрезе ключа) — повторный запрос в это окно не расходует лимит на новую выборку из БД, но по-прежнему учитывается в rate limit.

Изменение доступа ключа (сужение или расширение списка организаций) применяется не мгновенно — до 60 секунд, пока не истечёт кэш surveys/structure для этого ключа: организация, только что добавленная/убранная в панели «Интеграции», может ещё минуту оставаться видимой/невидимой по-старому в этих двух эндпоинтах. Отзыв ключа — исключение: он действует мгновенно (следующий же запрос получает 401), кэш здесь ни при чём — авторизация проверяется на каждый запрос заново, до чтения из кэша.