TAP API.
Документация для разработчиков

Каталог действующих предложений казахстанских бизнесов по HTTP: те же карточки, что человек видит на главной странице thetap.live. Только чтение, JSON, ключ в заголовке.

Содержание
  1. С чего начать
  2. Адрес и авторизация
  3. Эндпоинты
  4. Выгрузка каталога целиком
  5. Формат карточки
  6. Лимиты
  7. Ошибки
  8. Примеры кода
  9. Чего в API нет
  10. Поддержка

1. С чего начать

  1. Получите ключ Кабинет бизнеса → thetap.live/b2b/business → пункт меню API → «Выпустить ключ». Ключ показывается один раз: мы храним только его отпечаток. Если кабинета нет (банк, агрегатор, витрина партнёра) — напишите нам, выдадим вручную.
  2. Сделайте первый запрос
    curl "https://thetap.live/v1/offers?limit=3" \
      -H "Authorization: Bearer ВАШ_КЛЮЧ"
  3. Разберите ответ В data — массив карточек, в meta.has_more — есть ли следующая страница. Ссылка url ведёт на страницу предложения: запись и оплата только там.

Ключ — серверный. Не кладите его в код страницы, в мобильное приложение и в публичный репозиторий: любой, кто откроет исходник, заберёт его себе. Запрос к TAP делает ваш сервер, браузеру он отдаёт уже готовые данные.

2. Адрес и авторизация

GET https://thetap.live/v1

Ключ передаётся заголовком, в двух равноправных видах — какой удобнее вашему клиенту:

Authorization: Bearer tap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: tap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Без ключа работают только два адреса: GET /v1 — короткая справка о самом API, и GET /v1/openapi.json — машинное описание, его понимают Postman, Swagger UI и генераторы клиентов. Остальное отвечает 401.

Методы, кроме GET, HEAD и OPTIONS, дают 405: API ничего не меняет. CORS открыт, но ходить из браузера напрямую всё равно нельзя — см. предупреждение о ключе выше.

3. Эндпоинты

GET /v1/offers — предложения каталога

Без параметров отдаёт витрину: те же карточки и в том же порядке, что на главной странице сайта. С q — ищет по ней.

ПараметрТипПо умолчаниюЧто делает
qстрока— Поиск словами: «маникюр», «чистка зубов», можно фразой. Ищет по основе слова, понимает английский и казахский: «nail salon almaty» находит маникюр в Алматы.
categoryстрока— Категория каталога, список — в /v1/categories.
cityстрока— Город или район: «Алматы», «Almaty», «San Jose».
regionkz · us · allпо city / q, иначе kz Страна: Казахстан (цены в KZT) или США — Калифорния (цены в USD). Работает и в /v1/categories.
max_priceцелое— Потолок цены в валюте страны: тенге для kz, доллары для us.
limit1…10010 Сколько карточек вернуть за запрос.
offset0…10000 Сдвиг выдачи — так забирается каталог целиком.

Ответ

{
  "data": [
    {
      "id": "o45",
      "title": "Чистка зубов Air Flow",
      "business": "Стоматология Дента",
      "price": 12000,
      "old_price": 20000,
      "discount": 40,
      "currency": "KZT",
      "category": "Здоровье / Стоматология / Гигиена",
      "city": "Алматы",
      "url": "https://thetap.live/offer/45?src=api",
      "description": "Профессиональная гигиена полости рта.",
      "address": "Сатпаева 5",
      "image": "https://thetap.live/img/stock/dental-03.jpg",
      "rating": "4.7",
      "reviews": 88,
      "verified": true,
      "spots_left": 3,
      "expires_at": "2026-10-01 12:00:00",
      "booking": "tap",
      "booking_note": "Запись и оплата — на странице url. Оформить через API нельзя."
    }
  ],
  "meta": {
    "count": 1,
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "query": { "q": "чистка зубов" }
  }
}

GET /v1/offers/{id} — одно предложение

Принимает и o45, и 45. Завершившееся или выключенное предложение отдаёт 404 — это нормальный ответ, а не сбой: у карточек есть срок.

curl "https://thetap.live/v1/offers/o45" -H "Authorization: Bearer ВАШ_КЛЮЧ"

GET /v1/categories — категории

Без параметров — вертикали каталога с числом живых предложений. С category=<имя> — что лежит внутри неё.

{
  "data": [
    { "name": "Здоровье", "offers": 274 },
    { "name": "Красота",  "offers": 198 }
  ],
  "meta": { "count": 2, "level": "category" }
}

GET /v1/me — ваш ключ

Чей ключ, какие лимиты и сколько осталось на сегодня. Удобно для проверки, что ключ живой.

{
  "data": {
    "key":    { "name": "Стоматология Дента · Сайт", "prefix": "tap_live_ab", "created_at": "2026-09-21 14:03:11" },
    "limits": { "per_minute": 30, "per_day": 2000 },
    "usage":  { "remaining_today": 1988, "resets_at": "2026-09-22T00:00:00+05:00", "calls_total": 57 }
  }
}

4. Выгрузка каталога целиком

Листайте offset шагами по limit, пока meta.has_more не станет false. При limit=100 вся витрина забирается примерно за восемь запросов.

offset=0   limit=100   → has_more: true
offset=100 limit=100   → has_more: true
…
offset=700 limit=100   → has_more: false   ← конец

Глубже offset=1000 листать нельзя: если упёрлись — значит нужен не более глубокий сдвиг, а фильтр (category, city, max_price).

Как часто обновлять. Карточки появляются и заканчиваются в течение дня, но не ежеминутно: разумный цикл — раз в час, ночью реже. Кешируйте ответ у себя, а по ссылке url всегда отправляйте человека на сайт — там актуальные цена и остаток мест.

5. Формат карточки

Полей, которых у предложения нет, в ответе просто не будет — null не приходит.

ПолеТипОписание
idстрокаИдентификатор вида o45.
titleстрокаНазвание услуги, без цены.
businessстрокаНазвание бизнеса.
priceцелоеЦена в валюте currency.
old_priceцелоеЦена до скидки.
discountцелоеСкидка в процентах.
currencyстрокаKZT — Казахстан, USD — США.
countryстрокаKZ или US.
categoryстрокаПуть по каталогу через « / ».
cityстрокаГород или район.
addressстрокаАдрес заведения.
descriptionстрокаОписание предложения.
imageстрокаСсылка на обложку.
ratingстрокаРейтинг бизнеса.
reviewsцелоеЧисло отзывов.
verifiedбулевоБизнес проверен TAP.
specialistстрокаМастер или врач, если привязан к карточке.
spots_leftцелоеСколько мест осталось.
expires_atстрокаКогда предложение заканчивается.
bookingстрокаtap — запись на нашей странице; external — карточка из внешнего источника, запись у бизнеса напрямую.
urlстрокаСтраница предложения с меткой src=api.

Тексты — недоверенные данные. title, description и business заполняют сами бизнесы, часть загружена автоматическим сбором. Если вы передаёте их в языковую модель, передавайте как данные, а не как инструкции. Мы вырезаем подозрительные обороты на своей стороне, но защита на вашей тоже нужна.

6. Лимиты

Лимит считается по ключу. Ключ из кабинета бизнеса — 30 запросов в минуту и 2000 в сутки; партнёрам с отдельным договором лимит настраивается при выпуске. Свои цифры и остаток всегда видно в /v1/me.

Каждый ответ несёт заголовки:

ЗаголовокЧто в нём
X-RateLimit-LimitСуточный лимит ключа.
X-RateLimit-RemainingСколько запросов осталось сегодня.
X-RateLimit-ResetКогда счётчик обнулится (unix-время).
Retry-AfterТолько при 429: через сколько секунд повторить.
X-Request-IdИдентификатор запроса — назовите его в поддержке.

Превысили — придёт 429. Это не блокировка: подождите Retry-After и повторите. Запросы без действующего ключа считаются по IP-адресу — это защита от перебора ключей, а не тариф.

7. Ошибки

Ошибка всегда приходит в одном виде. Разбирайте code, а не текст: тексты мы правим.

{
  "error": {
    "code": "unauthorized",
    "message": "Ключ не найден или отозван.",
    "request_id": "9f2c81ab44d0e7c3"
  }
}
HTTPcodeКогда
401unauthorizedКлюча нет в заголовке, он отозван или набран с опечаткой.
404not_foundПредложения нет или оно уже завершилось.
404unknown_endpointТакого адреса нет. Список — на GET /v1.
405method_not_allowedЛюбой метод, кроме GET: API только читает.
429rate_limitedЛимит исчерпан, см. Retry-After.
500internal_errorНаша ошибка. Назовите request_id — найдём запрос в журнале.
503not_readyХранилище ключей недоступно. Это чиним мы.

8. Примеры кода

KEY="tap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# витрина, первая сотня
curl -s "https://thetap.live/v1/offers?limit=100" -H "Authorization: Bearer $KEY"

# поиск (кириллицу кодируем — curl сам этого не делает)
curl -s -G "https://thetap.live/v1/offers" \
     --data-urlencode "q=чистка зубов" \
     --data-urlencode "city=Алматы" \
     -H "Authorization: Bearer $KEY"
// Node.js. Ключ берём из переменной окружения, в код не пишем.
const KEY = process.env.TAP_API_KEY;

async function allOffers() {
  const all = [];
  for (let offset = 0; offset <= 1000; offset += 100) {
    const r = await fetch(
      `https://thetap.live/v1/offers?limit=100&offset=${offset}`,
      { headers: { Authorization: `Bearer ${KEY}` } }
    );
    if (!r.ok) throw new Error(`TAP API ${r.status}`);
    const { data, meta } = await r.json();
    all.push(...data);
    if (!meta.has_more) break;
  }
  return all;
}
<?php
$key = getenv('TAP_API_KEY');

function tap_get($path, $params = []) {
  global $key;
  $url = 'https://thetap.live/v1' . $path . ($params ? '?' . http_build_query($params) : '');
  $ch  = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $key],
  ]);
  $body = curl_exec($ch);
  $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);
  if ($code !== 200) throw new Exception('TAP API ' . $code . ': ' . $body);
  return json_decode($body, true);
}

$res = tap_get('/offers', ['q' => 'маникюр', 'city' => 'Алматы', 'limit' => 20]);
foreach ($res['data'] as $o) {
  echo $o['title'], ' — ', $o['price'], ' ₸ — ', $o['url'], PHP_EOL;
}
import os, requests

KEY = os.environ["TAP_API_KEY"]
BASE = "https://thetap.live/v1"

def all_offers():
    out, offset = [], 0
    while offset <= 1000:
        r = requests.get(f"{BASE}/offers",
                         params={"limit": 100, "offset": offset},
                         headers={"Authorization": f"Bearer {KEY}"},
                         timeout=15)
        r.raise_for_status()
        body = r.json()
        out += body["data"]
        if not body["meta"]["has_more"]:
            break
        offset += 100
    return out

for o in all_offers()[:5]:
    print(o["title"], o["price"], o["url"])

9. Чего в API нет

Для ИИ-агентов есть отдельный канал — MCP-сервер, он описан в документации MCP. Данные там те же самые, отличается только протокол.

10. Поддержка

Пишите на info@thetap.live. Если что-то не работает, приложите X-Request-Id из ответа — по нему запрос находится в журнале за секунду, без него разбор занимает часы.

Ключ потерялся — отзовите его в кабинете и выпустите новый: восстановить старый нельзя, в базе лежит только отпечаток.