#Аудиозапись приёма
Если у клиники подключено своё хранилище, аудиозапись приёма лежит в облаке клиники. Ваша МИС может прослушать или скачать её прямо из карточки приёма. smartica.ai выдаёт короткую ссылку в хранилище клиники по отдельному запросу.
Как клиника подключает хранилище — в статье Своё хранилище для записей.
#Когда аудиозапись доступна
- У клиники подключено своё хранилище. Без него запрос вернёт
404audio_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 минут и что у МИС есть сетевой доступ к хранилищу.
#Как встроить в интерфейс МИС
- В карточке приёма кнопка «Прослушать» или «Скачать» обращается к бэкенду вашей МИС.
- Бэкенд вызывает
GET …/audioс API-ключом клиники. - Бэкенд возвращает браузеру только
url,download_urlиexpires_at. Ключ в браузер не попадает. - Браузер ставит
urlв плеер, аdownload_urlоткрывает по кнопке «Скачать». - На
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по расписанию для всех приёмов. Запрашивайте ссылку, когда пользователь нажал кнопку.