API TesLab: адрес сервера и первый запрос

В документации мы постарались ответить на частые вопросы по работе TesLab, с которыми сталкиваются пользователи.
Если Вы не нашли ответ на свой вопрос, напишите нам.

Личный кабинет

API TesLab: адрес сервера и первый запрос

API позволяет другой программе получать данные TesLab и передавать их в TesLab. Для первого подключения нужны точный адрес сервера вашей организации и учётная запись с подходящими правами.

Начните с получения токена и проверки сеанса через auth/check. После этого переходите к выбранной операции. Ниже приведены примеры curl и JavaScript, а затем отдельный пример чтения лабораторной заявки. Домены, номера записей и учётные данные в примерах вымышлены.

В этой статье

Что подготовить

  1. Получите у администратора полный HTTPS-адрес сервера API своей организации, включая порт и префикс пути, если они используются.
  2. Подготовьте отдельную учётную запись интеграции. Ей должны быть доступны нужные операции и записи.
  3. Получите token.auth по инструкции Авторизация по логину и паролю. Сохраните также ID пользователя из результата входа: он понадобится для проверки ответа.
  4. Для второго примера заранее согласуйте тестовую лабораторную заявку и её внутренний ID.

Адрес страницы приложения и домен, который вы вводите при входе, могут отличаться от адреса API. Домен входа может быть псевдонимом организации. Внешний скрипт не выполняет такое сопоставление автоматически.

Единая учебная форма входа TesLab: логин и пароль без переключателя способов
1. Логин и сервер через @ или привязанный email. 2. Пароль учётной записи TesLab. Способ входа определяется автоматически.

В приложении сначала выполняется вход по логину и серверу. Если введён email, а сервер недоступен или для домена не найден адрес TesLab, приложение пробует вход по привязанной почте. При необходимости подтвердите почту кодом и выберите организацию. Ошибка пароля не переключает вход на другую учётную запись. Для внешнего API по-прежнему нужен точный адрес сервера.

Как составить адрес API

Адрес запроса состоит из базы API и пути метода:

https://хост[:порт][/префикс]/api/метод
  • https://lab.example/api служит условной базой.
  • auth/check является методом проверки сеанса.
  • Полный адрес примера: https://lab.example/api/auth/check.
  • Если администратор выдал базу уже с /api, второй раз этот сегмент не добавляйте. Сохраните указанные порт и префикс пути.

Уточняйте точный путь операции по документации. Наличие GET само по себе не означает безопасное чтение: смысл запроса определяет обработчик метода. Для примеров ниже используется POST.

Из чего состоит запрос API. Начните с адреса своей организации. Проверяйте ответ выбранного метода.
Запрос состоит из адреса операции, заголовков и параметров. В ответе проверяют статус, формат и ожидаемые данные.

Какие заголовки передать

  • auth: значение token.auth, полученное при входе. Передавайте его как есть, без добавления Bearer.
  • Lang: ru: язык ответа. В примерах явно выбран русский.
  • Out: json: формат ответа. Для этих примеров нужен JSON. Заголовок Accept не заменяет Out.
  • Content-Type: application/json; charset=UTF-8: добавьте, если передаёте JSON-тело. У проверки сеанса тело не требуется.

Не помещайте пароль или токен в адрес запроса, общие журналы и скриншоты. auth, HTTP Basic и ключи входящих интеграций Access-Code используются в разных сценариях. Ключ отдельного webhook не заменяет пользовательский токен.

Параметры подробнее разобраны в статье Параметры запросов: JSON, формы, типы и заголовки. Для файлов действуют отдельные правила загрузки: границу multipart формирует клиент, её не нужно придумывать вручную.

Первый запрос: проверка сеанса

  1. Замените lab.example на точный адрес вашего сервера API.
  2. Замените YOUR_AUTH_TOKEN на полученное значение token.auth.
  3. Выполните запрос. Вариант ниже предназначен для оболочки Bash, например в Linux или macOS.
curl -i -sS -X POST 'https://lab.example/api/auth/check' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json'

Параметр -i показывает заголовки ответа вместе с телом, -sS убирает индикатор прогресса, сохраняя сообщения об ошибках. Переносы строк с обратной косой чертой относятся к Bash. В другой оболочке используйте её синтаксис переноса либо выполните команду одной строкой.

auth/check проверяет сеанс без обращения к предметной заявке. Он обновляет служебные сведения об использовании сеанса и при определённых условиях продлевает срок токена. Успешная проверка не предоставляет дополнительные права на другие методы.

Как проверить ответ

  1. Проверьте HTTP-код. Для успешного примера ожидается 200.
  2. Убедитесь, что Content-Type указывает JSON, а тело разбирается как JSON.
  3. Проверьте отсутствие error: true.
  4. Найдите корневое поле id и сравните его с ID ожидаемого пользователя. У auth/check нет обёртки res.

Сокращённый пример успешного ответа:

{
  "id": 900301,
  "login": "api-user",
  "name": "Учебный",
  "fname": "Пользователь"
}

Дополнительные поля ответа не мешают проверке. Не считайте любой HTTP 200 подтверждением нужного результата: проверьте формат, структуру и ожидаемый ID.

Тот же запрос через JavaScript

Пример использует fetch, проверяет формат и структуру ответа, сравнивает пользователя и ограничивает ожидание 15 секундами. Вместо 900301 укажите ожидаемый ID вашей учётной записи.

const apiBase = 'https://lab.example/api';
const authToken = 'YOUR_AUTH_TOKEN';
const expectedUserId = 900301;
const isObject = value => value !== null
  && typeof value === 'object' && !Array.isArray(value);

async function callJson(method, body) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 15000);
  try {
    const response = await fetch(`${apiBase}/${method}`, {
      method: 'POST',
      headers: {
        auth: authToken, Lang: 'ru', Out: 'json',
        'Content-Type': 'application/json; charset=UTF-8'
      },
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: controller.signal
    });
    const type = (response.headers.get('Content-Type') || '')
      .split(';')[0].trim().toLowerCase();
    if (type !== 'application/json' && !type.endsWith('+json')) {
      throw new Error(`HTTP ${response.status}: ожидался ответ JSON`);
    }
    const text = await response.text();
    let result;
    try { result = JSON.parse(text); }
    catch { throw new Error(`HTTP ${response.status}: нечитаемый JSON`); }
    if (!response.ok || result?.error === true) {
      const reason = result?.mess || result?.title || 'Запрос отклонён';
      throw new Error(`HTTP ${response.status}: ${reason}`);
    }
    if (!isObject(result)) {
      throw new Error(`HTTP ${response.status}: неверная структура ответа`);
    }
    return result;
  } finally {
    clearTimeout(timer);
  }
}

const session = await callJson('auth/check');
if (!Number.isInteger(session.id) || session.id !== expectedUserId) {
  throw new Error('Ответ относится к другой учётной записи');
}
console.log(`Сеанс пользователя ${session.id} подтверждён`);

Обрыв соединения и отмена по таймауту не являются подтверждением выполнения операции. Не добавляйте к этому примеру бесконечные автоматические повторы.

Пример чтения лабораторной заявки

Перед выполнением: открытие карточки laboratory/requests/info может пересчитать состояние заявки. При определённых настройках автомат также запускает формирование акта. Поэтому этот метод не подходит для первоначальной проверки связи. Используйте заранее согласованную тестовую запись.

Для учётной записи должно быть доступно право «Информация» на карточку лабораторной заявки. Ограничение «только свои» тоже учитывается. Внутренний ID записи и номер печатного документа могут различаться.

Учебная лабораторная карточка TesLab: ID запроса и состояние заявки
1. Внутренний ID учебного запроса 900101 в заголовке карточки. 2. Состояние заявки относится к её бизнес-процессу. Проверку сеанса выполняйте отдельным методом auth/check.
curl -i -sS 'https://lab.example/api/laboratory/requests/info' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Lang: ru' \
  -H 'Out: json' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  --data '{"id":900101}'

--data задаёт POST-запрос с телом. Сокращённый пример ответа:

{
  "res": {
    "id": 900101,
    "tp": 1,
    "dsing": "2026-11-01",
    "cid": 900201,
    "status": 51,
    "cname": "ООО «Учебный заказчик»",
    "aid_num": "ДОГ-26/01",
    "cnum": "ДОГ-26/01",
    "count": 3
  }
}

У этого метода карточка находится в res. Проверьте, что res является объектом и res.id совпадает с запрошенным ID. Например, продолжение JavaScript-примера выше:

const requestedId = 900101;
const card = await callJson('laboratory/requests/info', {id: requestedId});
if (!isObject(card.res) || card.res.id !== requestedId) {
  throw new Error('Получена другая карточка или отсутствует ожидаемый ID');
}
console.log(`Получена карточка ${card.res.id}`);

status обозначает состояние заявки, count показывает количество объектов. Номер договора является строкой, а aid, если он возвращён, служит ID договора. Состав дополнительных полей зависит от данных; некоторые значения могут быть null.

Если запрос не сработал

  • HTTP-кода нет. Проверьте адрес, DNS, порт, доступность сервера и сертификат HTTPS. При запросе из браузера отдельно учитывайте его сообщение о CORS. Не отключайте проверку сертификата для рабочего обмена.
  • 400. Проверьте JSON, типы и значения параметров, Lang и Out. Внутренний ID передавайте положительным целым числом.
  • 401 или 419. Проверьте пользователя и состояние сеанса: срок, блокировку или отзыв. Не продолжайте запросы бесконечно со старым токеном.
  • 403. Проверьте передачу токена, права на метод и ограничения доступа. Возможны также ограничения запросов с IP или режим обслуживания.
  • 404. Проверьте путь метода, ID и область доступных записей. При ограничении «только свои» чужая карточка может выглядеть как ненайденная.
  • 429. Снизьте частоту обращений. Если сервер сообщил время ожидания, соблюдайте его.
  • 5xx. Сохраните время, метод и безопасные сведения об ошибке для администратора. При потере ответа на запись сначала выясните результат операции.
  • 200, но HTML, пустое тело или нечитаемый JSON. Проверьте базу API, маршрут, Out и ответ прокси. Это не подтверждение ожидаемого результата.
  • JSON получен, но структура или ID другие. Остановите обработку и проверьте метод, сервер и параметры. Такой ответ нельзя принимать как нужную карточку.

Объекты JSON, списки и файлы проверяются по разным контрактам. Порядок обработки ошибок описан в статье Ответы API и обработка ошибок, безопасные повторы в статье Повторные запросы и диагностика сбоев.

Дальнейшие шаги

Темы раздела «Интеграция API»
  • Авторизация по логину и паролю. Получение token.auth через auth/gettoken, кодирование пароля в Base64 и передача токена в заголовке auth.
  • Срок действия токена, проверка и завершение сессии. Начальные сроки, продление при работе, проверка auth/check, истечение, блокировка и отзыв текущей сессии.
  • HTTP Basic для серверных интеграций. Передача логина и пароля по HTTPS, особенности коротких сессий и применение Basic в готовом обмене с 1С.
  • Учётная запись интеграции и права доступа. Права пользователя и отдела, ограничения данных и лицензии; разница между входом сотрудника, контрагента и ОДС.
  • Параметры запросов: JSON, формы, типы и заголовки. Тело и параметры URL, вложенные значения, строки и числа, Lang/Out и правила передачи файлов без повреждения данных.
  • Ответы API и обработка ошибок. Различия объекта, списка и файла; HTTP-код, error/title/mess, ошибки полей, отказ авторизации и нечитаемый ответ.
  • Списки: страницы, сортировка и фильтры. Запрос небольших порций, startRow/endRow, разрешённые поля сортировки и фильтрации, rows и счётчики результата.
  • Загрузка файлов и вложений. Multipart-файл, прямая привязка к записи и сценарии с предварительной загрузкой; допустимые типы, размеры и ошибки.
  • Скачивание файлов и результатов фоновых операций. Прямое скачивание и фоновый результат: запуск, ожидание готовности или ошибки, получение файла и его имени по схеме выбранного метода.
  • Повторные запросы и диагностика сбоев. Действия при таймауте, потере ответа и ограничении частоты: проверка результата до повтора и полезные сведения для разбора ошибки.
  • Ключи входящих интеграций. Чем Access-Code/AccessCode отличается от пользовательского токена, к какому обработчику относится ключ и что меняется при его ротации.
  • Диспетчерские заявки из внешней системы. Создание заявки по ID лифта с описанием и контактом, бизнес-проверки, полученный ID и отличие от непринятого обращения.
  • Приём звонков от АТС: WebRTC и SIP-подключение. Требования к станции и браузерному SIP, параметры сотрудника и отличие голосового канала от серверных уведомлений о звонке.
  • События звонка на добавочный: HTTP hook. Параметры start/end, ext/from/callid/server, ключ доступа, короткий ответ и согласованный идентификатор звонка.
  • События Asterisk: входящий звонок, текст и ответ. Входящие уведомления транка, текст распознавания и NOTIFY_ANSWER; обязательные поля и отличие от нового адресного hook.
  • События Novofon: начало, ответ и завершение. Связь событий по pbx_call_id, уведомления добавочного и поведение неизвестных или только журналируемых событий.
  • AMI-канал Asterisk: события и адресация звонков. Серверное подключение к станции, события разных версий Asterisk, Linkedid/Uniqueid и сопоставление добавочных сотрудников.
  • Голосовой робот: обмен сообщениями с АТС. Запросы CallNotification/start/request, перенос состояния диалога и ответы question/info/action для передачи разговора дальше.
  • Обращения из Chatter: события сообщений и диалога. Обработка message_created, идентификаторы inbox/conversation/message и отделение сообщения жителя от служебного сообщения или ответа бота.
  • Webhook-каналы мессенджеров Chatter. Входящие callbacks провайдеров, inbox/identifier, выбор адаптера и передача исходящих сообщений с учётом служебных заметок.
  • Протокол обмена с 1С:Бухгалтерия. Точка 1c/buh, HTTP Basic, версия EnterpriseData, команды определения возможностей и обменный узел NodeCode.
  • Файлы и фоновые операции обмена с 1С. Загрузка и получение частей ZIP, SessionID/FileID/OperationID, проверка готовности, завершение и ограничения транспорта.

Что передать для диагностики

Укажите адрес сервера без секретных параметров, метод API, время запроса, HTTP-код, Content-Type, ожидаемый ID и безопасный фрагмент ошибки. Не отправляйте токен, пароль, заголовок Authorization или полный рабочий запрос с учётными данными.

Для отдельных способов обмена используйте соответствующую инструкцию: HTTP Basic, ключи входящих интеграций или скачивание файлов и фоновых результатов. Не переносите формат одного метода на другой только по похожему названию.