Каталог действующих предложений казахстанских бизнесов по HTTP: те же карточки, что человек видит на главной странице thetap.live. Только чтение, JSON, ключ в заголовке.
curl "https://thetap.live/v1/offers?limit=3" \
-H "Authorization: Bearer ВАШ_КЛЮЧ"data — массив карточек, в meta.has_more — есть ли следующая страница.
Ссылка url ведёт на страницу предложения: запись и оплата только там.Ключ — серверный. Не кладите его в код страницы, в мобильное приложение и в публичный репозиторий: любой, кто откроет исходник, заберёт его себе. Запрос к TAP делает ваш сервер, браузеру он отдаёт уже готовые данные.
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 открыт, но ходить из браузера напрямую всё равно нельзя — см. предупреждение о ключе выше.
Без параметров отдаёт витрину: те же карточки и в том же порядке, что на главной странице сайта.
С q — ищет по ней.
| Параметр | Тип | По умолчанию | Что делает |
|---|---|---|---|
| q | строка | — | Поиск словами: «маникюр», «чистка зубов», можно фразой. Ищет по основе слова, понимает английский и казахский: «nail salon almaty» находит маникюр в Алматы. |
| category | строка | — | Категория каталога, список — в /v1/categories. |
| city | строка | — | Город или район: «Алматы», «Almaty», «San Jose». |
| region | kz · us · all | по city / q, иначе kz | Страна: Казахстан (цены в KZT) или США — Калифорния (цены в USD). Работает и в /v1/categories. |
| max_price | целое | — | Потолок цены в валюте страны: тенге для kz, доллары для us. |
| limit | 1…100 | 10 | Сколько карточек вернуть за запрос. |
| offset | 0…1000 | 0 | Сдвиг выдачи — так забирается каталог целиком. |
{
"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": "чистка зубов" }
}
}
Принимает и o45, и 45. Завершившееся или выключенное предложение отдаёт 404 —
это нормальный ответ, а не сбой: у карточек есть срок.
curl "https://thetap.live/v1/offers/o45" -H "Authorization: Bearer ВАШ_КЛЮЧ"
Без параметров — вертикали каталога с числом живых предложений. С category=<имя> —
что лежит внутри неё.
{
"data": [
{ "name": "Здоровье", "offers": 274 },
{ "name": "Красота", "offers": 198 }
],
"meta": { "count": 2, "level": "category" }
}
Чей ключ, какие лимиты и сколько осталось на сегодня. Удобно для проверки, что ключ живой.
{
"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 }
}
}
Листайте 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
всегда отправляйте человека на сайт — там актуальные цена и остаток мест.
Полей, которых у предложения нет, в ответе просто не будет — 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 заполняют сами бизнесы, часть загружена автоматическим сбором. Если вы
передаёте их в языковую модель, передавайте как данные, а не как инструкции. Мы вырезаем
подозрительные обороты на своей стороне, но защита на вашей тоже нужна.
Лимит считается по ключу. Ключ из кабинета бизнеса — 30 запросов в минуту и 2000 в сутки;
партнёрам с отдельным договором лимит настраивается при выпуске. Свои цифры и остаток
всегда видно в /v1/me.
Каждый ответ несёт заголовки:
| Заголовок | Что в нём |
|---|---|
| X-RateLimit-Limit | Суточный лимит ключа. |
| X-RateLimit-Remaining | Сколько запросов осталось сегодня. |
| X-RateLimit-Reset | Когда счётчик обнулится (unix-время). |
| Retry-After | Только при 429: через сколько секунд повторить. |
| X-Request-Id | Идентификатор запроса — назовите его в поддержке. |
Превысили — придёт 429. Это не блокировка: подождите Retry-After и повторите.
Запросы без действующего ключа считаются по IP-адресу — это защита от перебора ключей, а не тариф.
Ошибка всегда приходит в одном виде. Разбирайте code, а не текст: тексты мы правим.
{
"error": {
"code": "unauthorized",
"message": "Ключ не найден или отозван.",
"request_id": "9f2c81ab44d0e7c3"
}
}
| HTTP | code | Когда |
|---|---|---|
| 401 | unauthorized | Ключа нет в заголовке, он отозван или набран с опечаткой. |
| 404 | not_found | Предложения нет или оно уже завершилось. |
| 404 | unknown_endpoint | Такого адреса нет. Список — на GET /v1. |
| 405 | method_not_allowed | Любой метод, кроме GET: API только читает. |
| 429 | rate_limited | Лимит исчерпан, см. Retry-After. |
| 500 | internal_error | Наша ошибка. Назовите request_id — найдём запрос в журнале. |
| 503 | not_ready | Хранилище ключей недоступно. Это чиним мы. |
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"])
url. Через API записать человека или принять деньги нельзя.Для ИИ-агентов есть отдельный канал — MCP-сервер, он описан в документации MCP. Данные там те же самые, отличается только протокол.
Пишите на info@thetap.live. Если что-то не работает,
приложите X-Request-Id из ответа — по нему запрос находится в журнале за секунду,
без него разбор занимает часы.
Ключ потерялся — отзовите его в кабинете и выпустите новый: восстановить старый нельзя, в базе лежит только отпечаток.