API предварительной записи

Методы API

В примерах используется https://timira.ru — наш основной домен. Каждый клиент должен заменить его на свой внешний IP или домен, где установлена его копия системы электронной очереди. Путь /api/queue/booking не меняется.

Все примеры ниже используют тестовый ключ песочницы qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e. Он создаёт только is_test=true брони и не влияет на живую очередь. Для боевой работы выпустите live-ключ в админке → API-ключи: секрет показывается один раз, передавайте его в X-API-Key и храните в секрете интеграции.

Не отправляйте запросы клиента на timira.ru, если у клиента собственная установка. Примеры адресов: https://queue.client.ru/api/queue/booking, https://203.0.113.10/api/queue/booking. Домен или IP выдаётся при развёртывании копии системы; при необходимости настраивается свой TLS-сертификат.
Полные готовые функции для каждого метода лежат в bash, Node.js, PHP, Python, C#, PowerShell, 1С/BSL.
Проверка в браузере. Откройте API-проводник, чтобы отправить запросы в песочницу без кода: услуги, слоты, создание, чтение, перенос и отмена тестовой брони. Ответ показывается вместе со статусом и X-Request-Id.

POST /

Создать предварительную запись. Требуется право booking.create.

Тело запроса

ПолеТипОбязательноОписание
service_idintegerдаid услуги из GET /services
scheduled_atstringда*ISO 8601 со смещением, например 2026-12-01T14:30:00+03:00
date, timestringда*Альтернатива: YYYY-MM-DD + HH:MM в часовом поясе системы
customer.namestringнетФИО/имя клиента (до 150)
customer.phonestringесли требуется контактТелефон (до 40)
customer.emailstringесли требуется контактE-mail (до 150)
notestringнетКомментарий (до 2000)

* Нужно передать либо scheduled_at, либо пару date+time.

Ответ 201

{
  "booking_ref": "hXk2m9Qb1sA7cD4e",
  "number": "A-014",
  "status": "booked",
  "scheduled_at": "2026-12-01T11:30:00.000Z",
  "scheduled_at_local": "2026-12-01 14:30",
  "timezone": "Europe/Moscow",
  "service": { "id": 3, "name": "Приём документов", "prefix": "П" },
  "queue": { "id": 1, "name": "Окно 1" },
  "customer": { "name": "Иван", "phone": "+79990000000", "email": "i@example.ru" },
  "note": "Комментарий",
  "is_test": false,
  "booking_source": "api",
  "callable": false,
  "created_at": "2026-11-17T12:00:00.000Z"
}

Примеры

bash / curl
curl -s -X POST "https://timira.ru/api/queue/booking" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-4b1d-4c8e-9a55-1c2f3d4e5f60" \
  -d '{
    "service_id": 3,
    "scheduled_at": "2026-12-01T14:30:00+03:00",
    "customer": { "name": "Иван", "phone": "+79990000000", "email": "i@example.ru" }
  }'
Node.js (fetch)
const crypto = require('crypto');
// внутри async-функции
const res = await fetch('https://timira.ru/api/queue/booking', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.QUEUE_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    service_id: 3,
    scheduled_at: '2026-12-01T14:30:00+03:00',
    customer: { name: 'Иван', phone: '+79990000000', email: 'i@example.ru' },
  }),
});
const booking = await res.json();
if (!res.ok) throw new Error(booking.code + ': ' + booking.error);
Node.js (axios)
const { data: booking } = await axios.post(
  'https://timira.ru/api/queue/booking',
  {
    service_id: 3,
    scheduled_at: '2026-12-01T14:30:00+03:00',
    customer: { name: 'Иван', phone: '+79990000000' },
  },
  {
    headers: {
      'X-API-Key': process.env.QUEUE_API_KEY,
      'Idempotency-Key': require('crypto').randomUUID(),
    },
    validateStatus: () => true,
  },
);
if (!booking.booking_ref) throw new Error(booking.code + ': ' + booking.error);
PHP (cURL)
$ch = curl_init('https://timira.ru/api/queue/booking');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('QUEUE_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'service_id' => 3,
        'scheduled_at' => '2026-12-01T14:30:00+03:00',
        'customer' => ['name' => 'Иван', 'phone' => '+79990000000'],
    ], JSON_UNESCAPED_UNICODE),
]);
$booking = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 201) throw new RuntimeException($booking['code'] . ': ' . $booking['error']);
PHP (Guzzle)
$client = new GuzzleHttp\Client(['base_uri' => 'https://timira.ru']);
$res = $client->post('/api/queue/booking', [
    'headers' => [
        'X-API-Key' => getenv('QUEUE_API_KEY'),
        'Idempotency-Key' => bin2hex(random_bytes(16)),
    ],
    'json' => [
        'service_id' => 3,
        'scheduled_at' => '2026-12-01T14:30:00+03:00',
        'customer' => ['name' => 'Иван', 'phone' => '+79990000000'],
    ],
    'http_errors' => false,
]);
$booking = json_decode($res->getBody()->getContents(), true);
Python (requests)
import os, uuid, requests
r = requests.post(
    'https://timira.ru/api/queue/booking',
    headers={
        'X-API-Key': os.environ['QUEUE_API_KEY'],
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'service_id': 3,
        'scheduled_at': '2026-12-01T14:30:00+03:00',
        'customer': {'name': 'Иван', 'phone': '+79990000000'},
    },
    timeout=30,
)
booking = r.json()
if r.status_code != 201:
    raise RuntimeError(f"{booking.get('code')}: {booking.get('error')}")
C# (HttpClient)
using var http = new HttpClient { BaseAddress = new Uri("https://timira.ru") };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("QUEUE_API_KEY"));
http.DefaultRequestHeaders.Add("Idempotency-Key", Guid.NewGuid().ToString());

var body = new {
    service_id = 3,
    scheduled_at = "2026-12-01T14:30:00+03:00",
    customer = new { name = "Иван", phone = "+79990000000" }
};
var res = await http.PostAsJsonAsync("/api/queue/booking", body);
var booking = await res.Content.ReadFromJsonAsync<JsonElement>();
if (!res.IsSuccessStatusCode)
    throw new Exception(booking.GetProperty("code") + ": " + booking.GetProperty("error"));
PowerShell (Invoke-RestMethod)
$headers = @{
  'X-API-Key'      = $env:QUEUE_API_KEY
  'Idempotency-Key' = [guid]::NewGuid().ToString()
}
$body = @{
  service_id   = 3
  scheduled_at = '2026-12-01T14:30:00+03:00'
  customer     = @{ name = 'Иван'; phone = '+79990000000' }
} | ConvertTo-Json -Depth 5
$booking = Invoke-RestMethod -Method Post -Uri 'https://timira.ru/api/queue/booking' `
  -Headers $headers -ContentType 'application/json; charset=utf-8' -Body $body
1С:Предприятие 8.3 (BSL)
// Полная функция — examples/booking.bsl, функция СоздатьЗаписьОчереди
Результат = СоздатьЗаписьОчереди(
    "timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e",
    3, "2026-12-01T14:30:00+03:00",
    "Иван", "+79990000000", "i@example.ru");
Сообщить("Код записи: " + Результат.booking_ref);

GET /slots?service_id=3&date=2026-12-01

Свободные слоты на дату. Требуется право slots.read.

Параметры: service_id (обязательно), date (YYYY-MM-DD; по умолчанию сегодня).

Ответ — объект с slots[] (см. Расписание и слоты).

bash / curl
curl -s "https://timira.ru/api/queue/booking/slots?service_id=3&date=2026-12-01" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
Node.js
const url = new URL('https://timira.ru/api/queue/booking/slots');
url.searchParams.set('service_id', '3');
url.searchParams.set('date', '2026-12-01');
const slots = await fetch(url, { headers: { 'X-API-Key': process.env.QUEUE_API_KEY } }).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/slots?service_id=3&date=2026-12-01');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY')]]);
$slots = json_decode(curl_exec($ch), true);
Python
slots = requests.get(
    'https://timira.ru/api/queue/booking/slots',
    params={'service_id': 3, 'date': '2026-12-01'},
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var slots = await http.GetFromJsonAsync<JsonElement>("/api/queue/booking/slots?service_id=3&date=2026-12-01");
PowerShell
$slots = Invoke-RestMethod -Uri 'https://timira.ru/api/queue/booking/slots?service_id=3&date=2026-12-01' -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY }
1С / BSL
Слоты = ПолучитьСлоты("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e", 3, '20261201');

GET /services

Очереди и услуги, доступные ключу. Требуется право services.read.

bash / curl
curl -s "https://timira.ru/api/queue/booking/services" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
Node.js
const services = await fetch('https://timira.ru/api/queue/booking/services', {
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY },
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/services');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY')]]);
$services = json_decode(curl_exec($ch), true);
Python
services = requests.get(
    'https://timira.ru/api/queue/booking/services',
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var services = await http.GetFromJsonAsync<JsonElement>("/api/queue/booking/services");
PowerShell
$services = Invoke-RestMethod -Uri 'https://timira.ru/api/queue/booking/services' -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY }
1С / BSL
Услуги = ПолучитьУслуги("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e");

GET /schedule

Правила записи: на сколько дней вперёд можно записаться, шаг слотов, за сколько минут до записи клиент поднимается в начало очереди (окно защиты) и с какого момента его можно вызвать (окно вызова), рабочие часы. Требуется право slots.read.

bash / curl
curl -s "https://timira.ru/api/queue/booking/schedule" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
Node.js
const rules = await fetch('https://timira.ru/api/queue/booking/schedule', {
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY },
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/schedule');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY')]]);
$rules = json_decode(curl_exec($ch), true);
Python
rules = requests.get(
    'https://timira.ru/api/queue/booking/schedule',
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var rules = await http.GetFromJsonAsync<JsonElement>("/api/queue/booking/schedule");
PowerShell
$rules = Invoke-RestMethod -Uri 'https://timira.ru/api/queue/booking/schedule' -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY }
1С / BSL
Правила = ПолучитьПравилаЗаписи("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e");

GET /:ref

Прочитать бронь по booking_ref. Требуется право booking.read.

Ключ видит только свои брони. Для чтения чужих нужно право booking.read_all.

bash / curl
curl -s "https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
Node.js
const booking = await fetch('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e', {
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY },
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY')]]);
$booking = json_decode(curl_exec($ch), true);
Python
booking = requests.get(
    'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e',
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var booking = await http.GetFromJsonAsync<JsonElement>("/api/queue/booking/hXk2m9Qb1sA7cD4e");
PowerShell
$booking = Invoke-RestMethod -Uri 'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e' -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY }
1С / BSL
Запись = ПолучитьЗапись("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e", "hXk2m9Qb1sA7cD4e");

GET /?date=2026-12-01

Список броней за день (по умолчанию — сегодня) или период (date_from, date_to). Требуется право booking.list.

Параметры: date, date_from, date_to, service_id, queue_id, status (booked по умолчанию, all — все), page, limit (до 100).

bash / curl
curl -s "https://timira.ru/api/queue/booking?date=2026-12-01&status=all&page=1&limit=50" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e"
Node.js
const list = await fetch('https://timira.ru/api/queue/booking?date=2026-12-01', {
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY },
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking?date=2026-12-01');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY')]]);
$list = json_decode(curl_exec($ch), true);
Python
bookings = requests.get(
    'https://timira.ru/api/queue/booking',
    params={'date': '2026-12-01'}, headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var list = await http.GetFromJsonAsync<JsonElement>("/api/queue/booking?date=2026-12-01");
PowerShell
$list = Invoke-RestMethod -Uri 'https://timira.ru/api/queue/booking?date=2026-12-01' -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY }
1С / BSL
Список = ПолучитьЗаписи("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e", '20261201');

POST /:ref/cancel

Отменить активную бронь. Требуется право booking.cancel.

Тело: { "reason": "клиент отказался" } (необязательно).

bash / curl
curl -s -X POST "https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e" \
  -H "Content-Type: application/json" \
  -d '{"reason":"клиент отказался"}'
Node.js
const booking = await fetch('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ reason: 'клиент отказался' }),
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['reason' => 'клиент отказался'], JSON_UNESCAPED_UNICODE),
]);
$booking = json_decode(curl_exec($ch), true);
Python
booking = requests.post(
    'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel',
    json={'reason': 'клиент отказался'},
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var res = await http.PostAsJsonAsync(
    "/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel",
    new { reason = "клиент отказался" });
var booking = await res.Content.ReadFromJsonAsync<JsonElement>();
PowerShell
$body = @{ reason = 'клиент отказался' } | ConvertTo-Json
$booking = Invoke-RestMethod -Method Post -Uri 'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/cancel' `
  -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY } -ContentType 'application/json; charset=utf-8' -Body $body
1С / BSL
Результат = ОтменитьЗапись("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e", "hXk2m9Qb1sA7cD4e", "клиент отказался");

POST /:ref/reschedule

Перенести активную бронь. Требуется право booking.reschedule.

Тело: { "scheduled_at": "2026-12-02T10:00:00+03:00" } или { "date": "2026-12-02", "time": "10:00" }.

bash / curl
curl -s -X POST "https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule" \
  -H "X-API-Key: qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at":"2026-12-02T10:00:00+03:00"}'
Node.js
const booking = await fetch('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.QUEUE_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ scheduled_at: '2026-12-02T10:00:00+03:00' }),
}).then(r => r.json());
PHP
$ch = curl_init('https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('QUEUE_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['scheduled_at' => '2026-12-02T10:00:00+03:00']),
]);
$booking = json_decode(curl_exec($ch), true);
Python
booking = requests.post(
    'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule',
    json={'scheduled_at': '2026-12-02T10:00:00+03:00'},
    headers={'X-API-Key': os.environ['QUEUE_API_KEY']}, timeout=30,
).json()
C#
var res = await http.PostAsJsonAsync(
    "/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule",
    new { scheduled_at = "2026-12-02T10:00:00+03:00" });
var booking = await res.Content.ReadFromJsonAsync<JsonElement>();
PowerShell
$body = @{ scheduled_at = '2026-12-02T10:00:00+03:00' } | ConvertTo-Json
$booking = Invoke-RestMethod -Method Post -Uri 'https://timira.ru/api/queue/booking/hXk2m9Qb1sA7cD4e/reschedule' `
  -Headers @{ 'X-API-Key' = $env:QUEUE_API_KEY } -ContentType 'application/json; charset=utf-8' -Body $body
1С / BSL
Результат = ПеренестиЗапись("timira.ru", 443, "qk_test_sandbox_6b1f0c9d8e7a5b4c3d2e1f0a9b8c7d6e", "hXk2m9Qb1sA7cD4e", "2026-12-02T10:00:00+03:00");
Коды ошибок — в разделе Ошибки. Машиночитаемое описание — openapi.json.