#Аудиозапись приёма

Если у клиники подключено своё хранилище, аудиозапись приёма лежит в облаке клиники. Ваша МИС может прослушать или скачать её прямо из карточки приёма. smartica.ai выдаёт короткую ссылку в хранилище клиники по отдельному запросу.

Как клиника подключает хранилище — в статье Своё хранилище для записей.

#Когда аудиозапись доступна

  • У клиники подключено своё хранилище. Без него запрос вернёт 404 audio_unavailable, ссылки нет.
  • Подходит любой сценарий: Launch, Launch Pull и Import, с доставкой push и pull.
  • В протоколе аудиозаписи нет. Ни PUT в вашу МИС, ни ответ с протоколом не содержат файла или ссылки. Ссылку создаём только по запросу, описанному ниже.

#Где взять smartica_encounter_id

Запрос идёт по UUID приёма в smartica.ai, а не по ID приёма в вашей МИС.

Сценарий Откуда приходит smartica_encounter_id
Launch, доставка push Поле в теле PUT. Статья Запись протокола в карту
Launch Pull Список готовых протоколов. Статья Launch Pull
Import Список записей и ответ на привязку. Статья Import

Сохраните UUID рядом с приёмом в своей базе.

#Запрос

GET /api/v1/integrations/{platform}/encounters/{smartica_encounter_id}/audio
Authorization: Bearer <API-ключ клиники>
Accept: application/json

Это тот же API-ключ клиники, что для ссылки входа врача и забора протокола. Лимит — общий с чтением протокола, 120 запросов в минуту. Статья Лимиты.

Этот адрес нельзя ставить в плеер или в ссылку для браузера. Он требует API-ключ и возвращает JSON, а не файл.

#Ответ: аудиозапись готова

{
  "status": "ready",
  "count": 1,
  "duration_sec": 742,
  "recordings": [
    {
      "url": "https://<хранилище клиники>/…",
      "download_url": "https://<хранилище клиники>/…",
      "expires_at": "2026-11-12T15:10:00+00:00",
      "duration_sec": 742,
      "content_type": "audio/mpeg"
    }
  ]
}
Поле Тип Описание
status строка ready — ссылки готовы
count число Сколько аудиозаписей в приёме
duration_sec число или null Общая длина всех аудиозаписей в секундах
recordings массив Аудиозаписи по порядку. Всегда массив, даже из одного элемента
recordings[].url строка Ссылка для прослушивания. Файл открывается и играет в браузере
recordings[].download_url строка Ссылка для скачивания. Браузер сохраняет файл
recordings[].expires_at строка, ISO 8601 До какого момента действуют обе ссылки. Это 10 минут
recordings[].duration_sec число или null Длина этой аудиозаписи в секундах
recordings[].content_type строка audio/mpeg

Обычно в приёме одна аудиозапись: берите recordings[0]. Несколько аудиозаписей бывает, только если врач продолжил приём.

Обе ссылки ведут прямо в хранилище клиники и открываются обычным GET без заголовка Authorization:

  • url ставьте в плеер или открывайте во вкладке. Аудиозапись начнёт играть, перемотка работает.
  • download_url отдайте кнопке «Скачать». Браузер сохранит файл со случайным именем.

Ссылки не сохраняются: перед каждым прослушиванием или скачиванием запрашивайте новые.

#Ответ: аудиозапись ещё копируется

Аудиозапись уходит в хранилище клиники сразу, как врач остановил запись. Обычно она уже там, когда протокол готов. Но при сбое облака копирование может затянуться, и PUT придёт раньше файла.

{
  "status": "copying",
  "message": "Аудиозапись ещё копируется в хранилище клиники.",
  "retry_after_sec": 30,
  "recordings": []
}

Код ответа — 200. Покажите пользователю «Аудиозапись ещё загружается» и повторите запрос не раньше, чем через retry_after_sec секунд.

#Ошибки

Код error Что значит
404 audio_unavailable У клиники не подключено своё хранилище
404 audio_not_found У приёма нет аудиозаписи в хранилище клиники
404 encounter_not_found Приём не найден или принадлежит другой клинике
410 encounter_deleted Приём удалён в smartica.ai
401 invalid_bearer_key Неверный API-ключ
429 — Превышен лимит. Дождитесь Retry-After

Общие правила ошибок — в статье Авторизация и ошибки.

Если ошибку вернул уже адрес из url или download_url, а не smartica.ai, ответ пришёл от хранилища клиники. Проверьте, что ссылка не старше 10 минут и что у МИС есть сетевой доступ к хранилищу.

#Как встроить в интерфейс МИС

  1. В карточке приёма кнопка «Прослушать» или «Скачать» обращается к бэкенду вашей МИС.
  2. Бэкенд вызывает GET …/audio с API-ключом клиники.
  3. Бэкенд возвращает браузеру только url, download_url и expires_at. Ключ в браузер не попадает.
  4. Браузер ставит url в плеер, а download_url открывает по кнопке «Скачать».
  5. На copying покажите, что аудиозапись ещё загружается. На audio_unavailable и audio_not_found спрячьте кнопку или покажите «Аудиозаписи нет».

Ниже бэкенд-обработчик для шагов 2 и 3. Браузер получает available и либо url, download_url и expires_at, либо retry_after_sec. Ключ берётся из окружения, platform — из конфигурации, smartica_encounter_id — из вашей базы.

$response = $http->get(
    'https://app.smartica.ai/api/v1/integrations/'.getenv('SMARTICA_PLATFORM')
        .'/encounters/'.$smarticaEncounterId.'/audio',
    [
        'headers' => [
            'Authorization' => 'Bearer '.getenv('SMARTICA_SSO_KEY'),
            'Accept' => 'application/json',
        ],
        'http_errors' => false,
        'timeout' => 10,
    ],
);

if ($response->getStatusCode() === 404) {
    return ['available' => false];
}

if ($response->getStatusCode() !== 200) {
    throw new RuntimeException('smartica.ai audio: HTTP '.$response->getStatusCode());
}

$data = json_decode((string) $response->getBody(), true);

if ($data['status'] === 'copying') {
    return ['available' => true, 'retry_after_sec' => $data['retry_after_sec']];
}

$recording = $data['recordings'][0];

return [
    'available' => true,
    'url' => $recording['url'],
    'download_url' => $recording['download_url'],
    'expires_at' => $recording['expires_at'],
];
const response = await fetch(
  `https://app.smartica.ai/api/v1/integrations/${process.env.SMARTICA_PLATFORM}`
    + `/encounters/${smarticaEncounterId}/audio`,
  {
    headers: {
      Authorization: `Bearer ${process.env.SMARTICA_SSO_KEY}`,
      Accept: 'application/json',
    },
  },
);

if (response.status === 404) {
  return res.json({ available: false });
}

if (!response.ok) {
  throw new Error(`smartica.ai audio: HTTP ${response.status}`);
}

const data = await response.json();

if (data.status === 'copying') {
  return res.json({ available: true, retry_after_sec: data.retry_after_sec });
}

const [recording] = data.recordings;

return res.json({
  available: true,
  url: recording.url,
  download_url: recording.download_url,
  expires_at: recording.expires_at,
});
response = httpx.get(
    f"https://app.smartica.ai/api/v1/integrations/{os.environ['SMARTICA_PLATFORM']}"
    f"/encounters/{smartica_encounter_id}/audio",
    headers={
        "Authorization": f"Bearer {os.environ['SMARTICA_SSO_KEY']}",
        "Accept": "application/json",
    },
    timeout=10,
)

if response.status_code == 404:
    return {"available": False}

response.raise_for_status()
data = response.json()

if data["status"] == "copying":
    return {"available": True, "retry_after_sec": data["retry_after_sec"]}

recording = data["recordings"][0]

return {
    "available": True,
    "url": recording["url"],
    "download_url": recording["download_url"],
    "expires_at": recording["expires_at"],
}
using var request = new HttpRequestMessage(
    HttpMethod.Get,
    $"https://app.smartica.ai/api/v1/integrations/{platform}/encounters/{smarticaEncounterId}/audio");

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SMARTICA_SSO_KEY"));
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

using var response = await httpClient.SendAsync(request);

if (response.StatusCode == HttpStatusCode.NotFound)
{
    return Results.Json(new { available = false });
}

response.EnsureSuccessStatusCode();

var data = await response.Content.ReadFromJsonAsync<JsonElement>();

if (data.GetProperty("status").GetString() == "copying")
{
    return Results.Json(new
    {
        available = true,
        retry_after_sec = data.GetProperty("retry_after_sec").GetInt32(),
    });
}

var recording = data.GetProperty("recordings")[0];

return Results.Json(new
{
    available = true,
    url = recording.GetProperty("url").GetString(),
    download_url = recording.GetProperty("download_url").GetString(),
    expires_at = recording.GetProperty("expires_at").GetString(),
});
HttpRequest request = HttpRequest.newBuilder(URI.create(
                "https://app.smartica.ai/api/v1/integrations/" + platform
                        + "/encounters/" + smarticaEncounterId + "/audio"))
        .header("Authorization", "Bearer " + System.getenv("SMARTICA_SSO_KEY"))
        .header("Accept", "application/json")
        .GET()
        .build();

HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString());

if (response.statusCode() == 404) {
    return Map.of("available", false);
}

if (response.statusCode() != 200) {
    throw new IllegalStateException("smartica.ai audio: HTTP " + response.statusCode());
}

JsonNode data = objectMapper.readTree(response.body());

if ("copying".equals(data.get("status").asText())) {
    return Map.of("available", true, "retry_after_sec", data.get("retry_after_sec").asInt());
}

JsonNode recording = data.get("recordings").get(0);

return Map.of(
        "available", true,
        "url", recording.get("url").asText(),
        "download_url", recording.get("download_url").asText(),
        "expires_at", recording.get("expires_at").asText()
);
Функция СсылкаНаАудиозапись(UUIDПриёма) Экспорт

    Заголовки = Новый Соответствие;
    Заголовки.Вставить("Authorization", "Bearer " + Константы.SmarticaКлючКлиники.Получить());
    Заголовки.Вставить("Accept", "application/json");

    Соединение = Новый HTTPСоединение(
        "app.smartica.ai", 443, , , , 10, Новый ЗащищенноеСоединениеOpenSSL);

    Путь = "/api/v1/integrations/" + Константы.SmarticaPlatform.Получить()
        + "/encounters/" + UUIDПриёма + "/audio";

    Ответ = Соединение.Получить(Новый HTTPЗапрос(Путь, Заголовки));

    Если Ответ.КодСостояния = 404 Тогда
        Возврат Новый Структура("available", Ложь);
    КонецЕсли;

    Если Ответ.КодСостояния <> 200 Тогда
        ВызватьИсключение "smartica.ai audio: HTTP " + Формат(Ответ.КодСостояния, "ЧГ=0");
    КонецЕсли;

    Чтение = Новый ЧтениеJSON;
    Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
    Данные = ПрочитатьJSON(Чтение, Истина);
    Чтение.Закрыть();

    Если Данные["status"] = "copying" Тогда
        Возврат Новый Структура("available, retry_after_sec", Истина, Данные["retry_after_sec"]);
    КонецЕсли;

    Аудиозапись = Данные["recordings"][0];

    Возврат Новый Структура("available, url, download_url, expires_at",
        Истина, Аудиозапись["url"], Аудиозапись["download_url"], Аудиозапись["expires_at"]);

КонецФункции

#Чего не делать

  • Не ставьте адрес …/audio в <audio src> или в ссылку: браузер получит JSON и ошибку авторизации.
  • Не сохраняйте url и download_url в базу. Через 10 минут хранилище их не примет.
  • Не скачивайте файл по url через атрибут download: для адреса хранилища браузер его не выполнит. Для скачивания есть download_url.
  • Не передавайте Authorization на адреса из url и download_url. Хранилище отклонит запрос с двумя способами авторизации.
  • Не разбирайте recordings как объект: это всегда массив.
  • Не вызывайте GET …/audio из браузера. API-ключ клиники живёт только на бэкенде.
  • Не опрашивайте …/audio по расписанию для всех приёмов. Запрашивайте ссылку, когда пользователь нажал кнопку.

#Связанные статьи

← Все статьи: Интеграция с МИС Поиск по базе знаний