API v1

Medsend API

Интегрируйте передачу медицинских документов в вашу информационную систему. REST API с авторизацией по ключу, вебхуками и загрузкой документов.

Интерактивная документация Быстрый старт

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

API-ключи и заголовки авторизации

Эндпоинты

Пациенты, документы, компания

Вебхуки

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

Rate Limits

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

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

Три шага для начала работы с API.

1

Получите API-ключ

Перейдите в личный кабинет клиники → API-ключи → создайте новый ключ с нужными правами доступа.

2

Сделайте первый запрос

Проверьте подключение, запросив информацию о вашей компании:

curl 
curl -X GET https://medsend.ru/api/v1/external/company \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
3

Получите ответ

Успешный ответ содержит данные вашей компании:

JSON 
{
  "data": {
    "id": 1,
    "name": "Клиника «Здоровье»",
    "email": "info@zdorovie.ru",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

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

Все запросы к API требуют аутентификации через API-ключ, передаваемый в заголовке Authorization.

HTTP Header 
Authorization: Bearer YOUR_API_KEY

Создание API-ключа

  1. Войдите в личный кабинет клиники
  2. Перейдите в раздел API-ключи
  3. Нажмите «Создать ключ» и выберите нужные права доступа
  4. Скопируйте ключ — он отображается только один раз

Храните ключ в безопасности

Никогда не передавайте API-ключ в клиентском коде, URL-параметрах или публичных репозиториях. Используйте переменные окружения на сервере.

Права доступа (abilities)

Право Описание
patients:read Просмотр списка пациентов и их данных
patients:write Приглашение пациентов
documents:read Просмотр документов и информации о компании
documents:write Загрузка и удаление документов
webhooks:manage Управление подписками на вебхуки

Базовый URL и формат ответов

Базовый URL

https://medsend.ru/api/v1/external

Все эндпоинты ниже указаны относительно базового URL.

Успешный ответ

200 OK 
{
  "data": { ... },
  "meta": { ... }
}

Ответ с ошибкой

4xx / 5xx 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found.",
    "details": { ... }
  }
}

Заголовки ответа

Заголовок Описание
X-Api-Version Версия API (текущая: 1)
X-RateLimit-Limit Максимум запросов в текущем окне
X-RateLimit-Remaining Оставшееся количество запросов

Эндпоинты

Полное описание параметров и примеры ответов — в интерактивной документации.

Компания

Методы для получения данных текущей компании и сводной статистики.

Метод Путь Описание
GET /company Возвращает данные текущей компании: название, email, дата создания и другие поля.
GET /company/stats Возвращает сводку: количество привязанных пациентов и общее количество загруженных документов.

Пациенты

Получение списка привязанных пациентов, данных по одному пациенту, приглашение по UID и поиск по UID.

Метод Путь Описание
GET /patients Пагинированный список пациентов компании. Параметры: search (поиск по имени, email, UID), per_page (1–50).
GET /patients/{id} Полные данные связи «компания — пациент»: данные пациента, дата принятия приглашения, количество документов.
POST /patients/invite Отправляет приглашение пациенту по его UID (пациент должен быть уже зарегистрирован). Тело: uid (обязательный).
POST /patients/find Поиск среди пациентов компании по UID. Возвращает данные связи или 404, если пациент не привязан. Тело: uid.

Документы

Список документов пациента, загрузка файлами или по URL, получение метаданных и удаление.

Метод Путь Описание
GET /patients/{id}/documents Список документов пациента с курсорной пагинацией (в meta: next_cursor, prev_cursor).
POST /patients/{id}/documents Загрузка файлов (PDF, DOC, DOCX). До 10 файлов за запрос, до 20 МБ на файл. Тело: multipart/form-data, поле files[].
POST /patients/{id}/documents/from-url Постановка в очередь загрузки по URL. Тело: массив documents с полями url и original_name. До 10 за запрос; файлы подгружаются асинхронно.
GET /documents/{id} Метаданные документа (название, размер, дата загрузки, ссылка на скачивание).
DELETE /documents/{id} Удаление документа. Ответ 204 No Content.

Вебхуки (управление)

Создание и удаление подписок на события; при наступлении события на ваш URL отправляется POST с телом и заголовком X-Medsend-Signature.

Метод Путь Описание
GET /webhooks Список всех подписок компании: URL, события, активность, дата создания.
POST /webhooks Создание подписки. Тело: url, events (массив). В ответе возвращается secret для проверки подписи.
DELETE /webhooks/{id} Удаление подписки. Ответ 204 No Content.

Вебхуки

Подпишитесь на события и получайте уведомления на ваш URL в реальном времени.

Доступные события

patient.invitation.accepted

Пациент принял приглашение клиники

patient.invitation.declined

Пациент отклонил приглашение

patient.disconnected

Пациент отвязался от клиники

document.downloaded

Пациент скачал документ

Создание подписки

curl 
curl -X POST https://medsend.ru/api/v1/external/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/medsend",
    "events": ["document.downloaded", "patient.disconnected"]
  }'

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

При создании подписки вы получите secret. Каждый входящий запрос содержит заголовок X-Medsend-Signature — HMAC-SHA256 тела запроса, подписанный вашим секретом.

PHP 
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_MEDSEND_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $payload, $webhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Rate Limits

Лимиты применяются на один API-ключ в скользящем окне в 1 минуту.

60
запросов/мин
Чтение

GET-запросы к пациентам, документам, компании

30
запросов/мин
Запись

Загрузка документов, приглашение пациентов

10
запросов/мин
Вебхуки

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

При превышении лимита

API вернёт ответ 429 Too Many Requests. Заголовок Retry-After укажет, через сколько секунд можно повторить запрос.

Примеры интеграции

Загрузка документов (файлы)

curl 
curl -X POST https://medsend.ru/api/v1/external/patients/42/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[]=@/path/to/mri-results.pdf" \
  -F "files[]=@/path/to/blood-test.pdf"

Загрузка документов по URL

Если файлы уже доступны по ссылке — передайте URL вместо файлов. Документы загрузятся асинхронно.

curl 
curl -X POST https://medsend.ru/api/v1/external/patients/42/documents/from-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "url": "https://mis.example.com/files/mri.pdf", "original_name": "МРТ головного мозга.pdf" },
      { "url": "https://mis.example.com/files/blood.pdf", "original_name": "Анализ крови.pdf" }
    ]
  }'

Пример на PHP

PHP 
$apiKey  = getenv('MEDSEND_API_KEY');
$baseUrl = 'https://medsend.ru/api/v1/external';

$ch = curl_init("{$baseUrl}/patients");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer {$apiKey}",
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

foreach ($data['data'] as $patient) {
    echo "{$patient['patient']['name']} — {$patient['patient']['uid']}\n";
}

Готовы к интеграции?

Откройте интерактивную документацию, чтобы протестировать эндпоинты прямо в браузере, или создайте API-ключ в личном кабинете.

Интерактивная документация Кабинет клиники