API для подписчиков

API отдаёт пивоварне её собственные данные: всю историю чекинов, весь ассортимент, разбор отзывов на брак и на тона вкуса. Публичные рейтинги, справочники и поиск идут приложением к этому. Всё, что API умеет, — читать: ни одного метода, который что-то меняет, здесь нет и не появится.

Базовый адрес — https://tappd.ru/api/v1/. Формат ответа — JSON в UTF-8. Ключ выдаётся аккаунту с действующей подпиской в кабинете: Профиль → API.

curl -s https://tappd.ru/api/v1/my \
     -H "X-Api-Key: tpd_k7m3xp2q_9fvbn4rt8shj2wqd6yzc3mkp5xgv7bnf"

Это первый запрос, который стоит сделать: он отвечает, какая пивоварня закреплена за аккаунтом, до какого числа оплачена подписка, сколько осталось лимитов и открыты ли уже маршруты с сырыми текстами отзывов. Почти все «у меня ничего не работает» объясняются одним из этих четырёх ответов.

Ключ выпускает владелец аккаунта в кабинете — Профиль → API. Нужна действующая подписка. Ключей на аккаунт не больше 3 — чтобы переехать на новый без простоя, хватает двух: выпускаете второй, меняете его в своей программе, отзываете первый. Полный ключ показывается ровно один раз, в момент создания — у нас он хранится только хешем, поэтому ни прислать его повторно, ни подсмотреть в поддержке невозможно. Потеряли — отзовите и выпустите новый.

Вид ключа: tpd_ + 8 символов префикса + _ + 32 символа секрета, например tpd_k7m3xp2q_9fvbn4rt8shj2wqd6yzc3mkp5xgv7bnf. Первые 12 символов (tpd_k7m3xp2q) — префикс: он виден в кабинете и им можно назвать свой ключ в письме в поддержку, не раскрывая секрета.

X-Api-Key: tpd_k7m3xp2q_9fvbn4rt8shj2wqd6yzc3mkp5xgv7bnf     ← основной способ

Authorization: Bearer tpd_k7m3xp2q_9fvbn4rt8shj2wqd6yzc3mkp5xgv7bnf   ← тоже работает

Основной способ — X-Api-Key: он доезжает всегда. Заголовок Authorization на части конфигураций PHP снимается веб-сервером ещё до нашего кода; мы его восстанавливаем тремя разными приёмами, но если ключ вдруг «не принимается», первое, что стоит попробовать, — перейти на X-Api-Key.

• Только https. Запрос по http:// — 403 https_required.
• Только GET и HEAD. Любой другой метод — 405. HEAD обслуживается как GET, но тела не отдаёт и строк не списывает.
• Можно ограничить ключ адресами. В кабинете есть поле «разрешённые IP» — перечисляются точно, через запятую, без масок и подсетей. Пустое поле означает «с любого адреса». Запрос с чужого — 403 ip_not_allowed, и в тексте ошибки назван адрес, который мы увидели: чаще всего это не атака, а сменившийся адрес у подрядчика.
• Подписка кончилась — ключ не отзывается. Есть отсрочка 3 суток, после неё маршруты отвечают 402. Продлили подписку — тот же ключ заработал снова, пересоздавать ничего не нужно.

У успешного ответа всегда два ключа верхнего уровня: data — то, что просили, и meta — служебное. Список meta закрыт, других полей там не появится.

{
  "data": [ … ],
  "meta": {
    "count": 50,
    "limit": 50,
    "has_more": true,
    "next": "eyJtIjoiZHQiLCJrIjoi…",
    "sync_cursor": "2026-08-31T16:20:14+03:00",
    "depth_capped": false,
    "source": "showcase",
    "stale_min": 12,
    "data_through": "2026-08-31T16:20:14+03:00",
    "data_age_min": 12,
    "analyzed_through": "2026-08-31T05:47:11+03:00",
    "generated_at": "2026-08-31T16:32:07+03:00",
    "contract": "2026-09-01"
  }
}

Все отметки времени — ISO-8601 с офсетом московского пояса (2026-08-31T16:20:14+03:00). Календарные даты остаются датами (2019-05-14) и во время не превращаются: у них нет точности до секунды, и обещать её незачем.

{
  "error": {
    "code": "bad_param",
    "message": "Дата задаётся как YYYY-MM-DD, например 2026-08-31.",
    "field": "from",
    "quota": null,
    "reset": null,
    "request_id": 918273
  }
}

Шесть ключей печатаются всегда, даже пустыми. field заполнен у всех 400: bad_param выдаётся на десяток разных причин, и без имени поля каждая опечатка превращалась бы в переписку. quota и reset — у 429. request_id совпадает с заголовком X-Request-Id: назовите его в письме в поддержку, и запрос найдётся в журнале за секунду.

Свои данные объёмом не ограничены вовсе. У маршрутов /v1/my/* нет ни кошелька строк, ни потолка глубины, ни обязательного окна по датам: выкачать всю историю пивоварни целиком — это то, за что заплачено, и ограничение здесь било бы ровно по тому, кто платит. Тратится только сам запрос (минутный и суточный счётчики).

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

• ?ids= — по числу запрошенных номеров, а не найденных, и дубликаты считаются. Иначе список добивают несуществующими номерами и недоплачивают.
• /v1/search — фиксированные 50 строк: поиск по подстроке идёт полным проходом, и работа одна и та же на одну найденную строку и на двадцать.
• /v1/breweries/{id}/stats — фиксированные 100 строк: это единственный живой агрегат по чекинам во всём публичном API. Отсюда же — обязательный ETag на нём.

Ответ 304 и запрос методом HEAD стоят ноль строк.

X-Request-Id: 918273                  ← есть ВСЕГДА, даже на 401; назовите его в поддержке
X-RateLimit-Minute-Remaining: 57      ← дальше только там, где ключ опознан
X-RateLimit-Day-Remaining: 2841
X-RateLimit-Rows-Remaining: 4180      ← на /v1/my/* здесь слово "unlimited"
X-Data-Age-Min: 12                    ← только на /v1/my/*; "unknown", если чекинов нет

Лимитные заголовки появляются только после того, как ключ опознан. На 401, 402, 403, 404 unknown_route, 405 и 409 их нет вовсе — до владельца ключа мы в этот момент ещё не дошли, а значит и остатков ничьих не знаем. Из всего перечисленного на таком ответе стоит один X-Request-Id. Разбирать отказ по отсутствию X-RateLimit-* не надо — код и error.code точнее.

На 429 добавляются Retry-After (в секундах) и X-RateLimit-Reset (unix-время). Если кончилось несколько лимитов сразу, назван тот, чьё окно закроется позже — то есть Retry-After это честное «после этого срока запрос точно пройдёт», а не «попробуйте ещё разок через пять секунд».

Там, где у ответа есть ETag, он приходит в заголовке ETag. Верните его в If-None-Match — и если у нас ничего не изменилось, придёт 304 с пустым телом, бесплатно: ни строка кошелька, ни повторная передача данных за это не берутся. На регулярном опросе это главный способ не тратить лимиты впустую.

curl -s -D- -o/dev/null https://tappd.ru/api/v1/rankings/beers \
     -H "X-Api-Key: $KEY" -H 'If-None-Match: "8f14e45fceea167a5a36dedd4bea2543"'

HTTP/1.1 304 Not Modified
X-Request-Id: 918274

ETag зависит и от формы запроса тоже (сортировка, страница, период). Меняете параметры — старый ETag просто не совпадёт, и придут данные; отдельно об этом заботиться не нужно.

ETag есть не везде, и это правило, а не недоделка. Он стоит там, где версию ответа можно назвать целиком и честно. Его нет у /v1/my (в теле остатки лимитов, они меняются каждый запрос), у /v1/my/beers и /v1/my/summary, у /v1/search и /v1/meta, а также у двух маршрутов с сырым текстом — /v1/my/defects и …/mentions: текст отзыва у нас может быть переписан задним числом, не сдвинув ни одной отметки разбора, и ETag от разбора отдавал бы 304 на изменившийся текст. Врущий 304 хуже отсутствующего кэша. У /v1/meta вместо ETag есть поле version в теле.

Словарь один на весь API: одинаковые имена значат одинаковое везде, где встречаются. Неизвестные параметры молча игнорируются — присылать лишнее не ошибка.

• Число вне диапазона обрезается. limit=1000 — это потолок маршрута (100 у публичных, 500 у своих, 20 у поиска), смещение за глубину списка — пустая страница с depth_capped: true, окно статистики больше года — двенадцать месяцев. Это нормальный край, а не ошибка.
• Значение не того типа отвергается. limit=много, from=вчера, beer_id=abc — 400 bad_param с именем поля. Дата, не прошедшая проверку календаря, тоже: молчаливо выкинутый фильтр дал бы вам не ошибку, а лишние данные в отчёте, и заметить это было бы нечем.
• Перевёрнутый период — тоже 400. from больше to — это опечатка, а какую из двух дат считать верной, знаете только вы.

Восемь маршрутов. Пивоварня берётся из привязки аккаунта, а не из параметров запроса: «чужую» пивоварню здесь запросить нечем. Кошелёк строк они не тратят, потолка объёма у них нет.

{
  "data": {
    "login": "4brewers",
    "role": "user",
    "subscription": { "until": "2026-12-01T00:00:00+03:00", "active": true },
    "brewery": {
      "id": 188442,
      "name": "4BREWERS",
      "country": "Russia",
      "logo_url": "https://tappd.ru/beer_logo/brewery/188442.webp"
    },
    "limits": {
      "req_min":      { "left": 59,   "limit": 60 },
      "req_day":      { "left": 2984, "limit": 3000 },
      "rows_day_pub": { "left": 5000, "limit": 5000 }
    },
    "bind": { "trusted": true, "open_at": null }
  },
  "meta": {
    "data_through": "2026-08-31T16:20:14+03:00",
    "data_age_min": 12,
    "generated_at": "2026-08-31T16:32:07+03:00",
    "contract": "2026-09-01"
  }
}

GET /api/v1/my/beers?from=2026-08-01&to=2026-08-31&sort=checkins&limit=2

{
  "data": [
    {
      "beer_id": 6842600,
      "name": "План Побега",
      "style": "Sour - Fruited",
      "abv": 5.5,
      "description": "Кислый эль с маракуйей и манго.",
      "first_checkin": "2026-08-14",
      "logo_url": "https://tappd.ru/beer_logo/6842600.webp",
      "checkins": 412,
      "rated": 398,
      "rating": 4.07
    },
    {
      "beer_id": 6837700,
      "name": "Зубы Города Льва",
      "style": "Wild Ale - Other",
      "abv": 5.5,
      "description": "",
      "first_checkin": "2026-08-02",
      "logo_url": "https://tappd.ru/beer_logo/6837700.webp",
      "checkins": 96,
      "rated": 91,
      "rating": 3.88
    }
  ],
  "meta": { "count": 2, "limit": 2, "has_more": true,
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

{
  "data": {
    "period":          { "from": "2026-08-01", "to": "2026-08-31", "days": 31 },
    "previous_period": { "from": "2026-07-01", "to": "2026-07-31", "days": 31 },
    "current":  { "checkins": 9841, "rated": 9502, "rating": 4.02, "reviews": 3918,
                  "defects_checked": 1204, "defects_found": 71 },
    "previous": { "checkins": 8760, "rated": 8455, "rating": 3.98, "reviews": 3401,
                  "defects_checked": 1102, "defects_found": 64 }
  },
  "meta": { "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "analyzed_through": "2026-08-31T05:47:11+03:00",
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/my/defects/summary?from=2026-06-01&to=2026-08-31

{
  "data": {
    "period": { "from": "2026-06-01", "to": "2026-08-31", "days": 92 },
    "beer_id": null,
    "min_confidence": 50,
    "current": {
      "checked": 3374, "found": 210, "critical": 18, "unreviewed": 147,
      "codes": [
        { "code": "phenolic", "name": "Фенольный тон (пластик, аптека)",
          "group": "brew", "group_name": "Варка и брожение", "critical": false, "count": 16 },
        { "code": "hop_fade", "name": "Хмель выдохся",
          "group": "age", "group_name": "Возраст и хранение", "critical": false, "count": 14 }
      ],
      "clusters": [
        { "beer": { "id": 6487618, "name": "ERIS: Armagnac BA (2025)" },
          "code": "haze_film", "code_name": "Муть, хлопья, плёнка",
          "count": 4, "severity": 2, "first": "2026-07-19", "last": "2026-08-24" }
      ]
    }
  },
  "meta": { "analyzed_through": "2026-08-31T05:47:11+03:00",
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

{
  "data": {
    "period": { "from": null, "to": null, "days": null },
    "beer_id": null,
    "reviews": { "checked": 3374, "with_descriptors": 2598, "mentions": 7841 },
    "descriptors": [
      { "code": "sour", "name": "Кислинка", "group": "taste", "group_name": "Вкус",
        "kind": "tone", "is_defect": false, "echo_pct": 4,
        "mentions": 365, "share": 14.0,
        "positive": 226, "neutral": 113, "negative": 26,
        "bright": 42, "faint": 24, "avg_rating": 4.05, "beers": 84 },
      { "code": "body_full", "name": "Плотное тело", "group": "body", "group_name": "Тело и текстура",
        "kind": "profile", "is_defect": false, "echo_pct": 0,
        "mentions": 176, "share": 6.8,
        "positive": 124, "neutral": 46, "negative": 6,
        "bright": 17, "faint": 9, "avg_rating": 4.16, "beers": 66 }
    ]
  },
  "meta": { "count": 2, "limit": 300, "has_more": false, "depth_capped": false,
            "analyzed_through": "2026-08-31T05:47:11+03:00",
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/my/defects?codes=haze_film&sev_gte=2&limit=1

{
  "data": [
    {
      "chekin_id": 1503927744,
      "datetime": "2026-08-24T19:41:03+03:00",
      "checkin_date": "2026-08-24",
      "beer": { "id": 6487618, "name": "ERIS: Armagnac BA (2025)",
                "style": "Stout - Russian Imperial",
                "logo_url": "https://tappd.ru/beer_logo/6487618.webp" },
      "venue": { "id": 7728362, "name": "Share House" },
      "username": "beer_hunter_78",
      "rating": 3.25,
      "text": "Вкус хороший, но в этой банке какие-то хлопья и плёнка сверху. Вылил половину.",
      "has_comment": true,
      "has_photo": true,
      "photo_url": "https://tappd.ru/funny_photo/1503927744.webp",
      "source_url": "https://untappd.com/user/beer_hunter_78/checkin/1503927744",
      "code": "haze_film",
      "code_name": "Муть, хлопья, плёнка",
      "codes": ["haze_film"],
      "severity": 2,
      "severity_label": "Заметный дефект",
      "confidence": 78,
      "quote": "какие-то хлопья и плёнка сверху",
      "note": "Жалоба на конкретный экземпляр, не на стиль",
      "status": "new",
      "status_by": "",
      "status_at": null
    }
  ],
  "meta": { "count": 1, "limit": 1, "has_more": true, "next": null,
            "sync_cursor": "2026-08-31T05:47:11+03:00",
            "analyzed_through": "2026-08-31T05:47:11+03:00",
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/my/descriptors/sour/mentions?from=2026-08-01&limit=1

{
  "data": {
    "code": "sour",
    "name": "Кислинка",
    "known": true,
    "period": { "from": "2026-08-01", "to": null, "days": null },
    "beer_id": null,
    "mentions": [
      {
        "chekin_id": 1502881003,
        "datetime": "2026-08-15T21:07:44+03:00",
        "beer": { "id": 6842600, "name": "План Побега", "style": "Sour - Fruited" },
        "username": "beer_hunter_78",
        "rating": 4.25,
        "text": "Приятная кислинка, маракуйя на первом плане, пьётся легко.",
        "has_comment": true,
        "has_photo": false,
        "source_url": "https://untappd.com/user/beer_hunter_78/checkin/1502881003",
        "sentiment": 1,
        "intensity": 1,
        "raw_word": ""
      }
    ]
  },
  "meta": { "count": 1, "limit": 1, "has_more": false, "depth_capped": true,
            "analyzed_through": "2026-08-31T05:47:11+03:00",
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/my/checkins?limit=1

{
  "data": [
    {
      "chekin_id": 1502881003,
      "datetime": "2026-08-15T21:07:44+03:00",
      "beer": { "id": 6842600, "name": "План Побега", "style": "Sour - Fruited",
                "logo_url": "https://tappd.ru/beer_logo/6842600.webp" },
      "brewery_id": 188442,
      "is_collab": false,
      "venue": { "id": 7728362, "name": "Share House" },
      "username": "beer_hunter_78",
      "rating": 4.25,
      "text": "Приятная кислинка, маракуйя на первом плане, пьётся легко.",
      "has_comment": true,
      "has_photo": false,
      "photo_url": null,
      "source_url": "https://untappd.com/user/beer_hunter_78/checkin/1502881003",
      "served": "Can",
      "source": "main"
    }
  ],
  "meta": { "count": 1, "limit": 1, "has_more": true,
            "next": "eyJtIjoiZHQiLCJrIjoiMjAyNi0wOC0xNSAyMTowNzo0NCIsImkiOjE1MDI4ODEwMDMsImYiOiI3YjJmOWMxZDRhMGUifQ",
            "sync_cursor": "2026-08-31T16:22:00+03:00",
            "data_through": "2026-08-31T16:20:14+03:00", "data_age_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

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

GET /api/v1/rankings/breweries?sort=rating&limit=1

{
  "data": [
    {
      "brewery_id": 460729,
      "name": "Ashram Cider",
      "logo_url": "https://tappd.ru/beer_logo/brewery/460729.webp",
      "source_url": "https://untappd.com/brewery/460729",
      "metrics": {
        "rating": 4.4569, "checkins": 254, "users": 130, "venues": 24,
        "past_rating": 4.6348, "past_checkins": 92, "past_users": 51, "past_venues": 16
      }
    }
  ],
  "meta": { "source": "showcase", "stale_min": 12, "count": 1, "limit": 1,
            "has_more": true, "depth_capped": false,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/breweries?ids=460729,999999999,188442

{
  "data": [
    { "brewery_id": 460729, "name": "Ashram Cider",
      "logo_url": "https://tappd.ru/beer_logo/brewery/460729.webp",
      "source_url": "https://untappd.com/brewery/460729",
      "metrics": { "rating": 4.4569, "checkins": 254, "users": 130, "venues": 24,
                   "past_rating": 4.6348, "past_checkins": 92,
                   "past_users": 51, "past_venues": 16 } },
    { "brewery_id": 188442, "name": "4BREWERS",
      "logo_url": "https://tappd.ru/beer_logo/brewery/188442.webp",
      "source_url": "https://untappd.com/brewery/188442",
      "metrics": { "rating": 4.0189, "checkins": 9841, "users": 3204, "venues": 612,
                   "past_rating": 3.9812, "past_checkins": 8760,
                   "past_users": 2988, "past_venues": 574 } }
  ],
  "meta": { "source": "showcase", "stale_min": 12,
            "count": 2, "limit": 3, "has_more": false, "depth_capped": false,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/beers/6487618

{
  "data": {
    "beer_id": 6487618,
    "name": "ERIS: Armagnac BA (2025)",
    "style": "Stout - Russian Imperial",
    "abv": 16.5,
    "description": "Имперский стаут, выдержанный в бочках из-под арманьяка.",
    "first_checkin_date": "2026-02-11",
    "image_url": "https://tappd.ru/beer_logo/6487618.webp",
    "brewery": { "brewery_id": 329172, "name": "Midnight", "external": false,
                 "logo_url": "https://tappd.ru/beer_logo/brewery/329172.webp" },
    "collab_partners": [],
    "source_url": "https://untappd.com/beer/6487618",
    "metrics": { "rating": 4.516667, "checkins": 87, "users": 86, "venues": 29 }
  },
  "meta": { "source": "showcase", "stale_min": 12,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/breweries/460729/beers?limit=1

{
  "data": [
    {
      "beer_id": 6804379,
      "name": "Melomel Wild Pear Batch #2",
      "style": "Mead - Melomel",
      "abv": 14.0,
      "description": "Медовуха на диких грушах, вторая партия.",
      "first_checkin_date": "2026-07-28",
      "image_url": "https://tappd.ru/beer_logo/6804379.webp",
      "brewery": { "brewery_id": 460729, "name": "Ashram Cider", "external": false,
                   "logo_url": "https://tappd.ru/beer_logo/brewery/460729.webp" },
      "collab_partners": [],
      "source_url": "https://untappd.com/beer/6804379",
      "metrics": { "rating": 4.516038, "checkins": 53, "users": 53, "venues": 3 }
    }
  ],
  "meta": { "source": "showcase", "stale_min": 12, "count": 1, "limit": 1,
            "has_more": true, "depth_capped": false,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/breweries/188442/stats?from=2026-06-01&to=2026-08-31

{
  "data": [
    { "month": "2026-06", "checkins": 8214, "ratings": 7902, "rating": 3.99 },
    { "month": "2026-07", "checkins": 8760, "ratings": 8455, "rating": 3.98 },
    { "month": "2026-08", "checkins": 9841, "ratings": 9502, "rating": 4.02 }
  ],
  "meta": { "count": 3, "limit": 12, "has_more": false, "depth_capped": false,
            "data_through": "2026-08-31T16:20:14+03:00",
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

GET /api/v1/search?type=beer&q=melomel&limit=1

{
  "data": [
    {
      "beer_id": 6804379,
      "name": "Melomel Wild Pear Batch #2",
      "style": "Mead - Melomel",
      "abv": 14.0,
      "image_url": "https://tappd.ru/beer_logo/6804379.webp",
      "brewery": { "brewery_id": 460729, "name": "Ashram Cider", "external": false }
    }
  ],
  "meta": { "count": 1, "limit": 1, "has_more": false,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

{
  "data": {
    "defect_groups": [ { "code": "bio", "name": "Микробиология" }, … ],
    "defect_codes": [
      { "code": "gushing", "name": "Гашинг (фонтанирование)", "group": "bio",
        "group_name": "Микробиология", "critical": true,
        "cause": "Заражённый солод (Fusarium), микробиология розлива…" }
    ],
    "descriptor_groups": [ { "code": "taste", "name": "Вкус" }, … ],
    "descriptor_codes": [
      { "code": "sour", "name": "Кислинка", "group": "taste", "group_name": "Вкус",
        "kind": "tone", "defect": false, "echo_pct": 4 }
    ],
    "version": "3f1c9a0b7d2e5648a1c4f0b93e77dd21"
  },
  "meta": { "count": 1, "has_more": false,
            "generated_at": "2026-08-31T16:32:07+03:00", "contract": "2026-09-01" }
}

Забрать историю к себе и потом поддерживать её в актуальном состоянии — это два разных режима, и путать их нельзя.

Первая полная выгрузка. Запрашиваете /v1/my/checkins?limit=500, берёте meta.next, передаёте его в cursor, повторяете, пока meta.has_more не станет false. Строк это не стоит, тратятся только запросы: самая крупная пивоварня в базе выкачивается примерно за 1 200 запросов, то есть влезает в суточный лимит с большим запасом.

• Курсор непрозрачен. Это не дата и не номер: внутри наша служебная структура, и она уже дважды поменялась бы. Не разбирайте его, не конструируйте сами, не «поправляйте» — возвращайте ровно ту строку, которую получили.
• Курсор привязан к фильтрам — ко всем сразу. В отпечаток входят from, to, beer_id, rating_gte, rating_lte, include_collabs и since, а вместе с ними маршрут и пивоварня. Прислали старый курсор вместе с изменившимся любым из них — придёт 400 bad_param с field: "cursor". Это защита: иначе у вас была бы дыра в выгрузке, о которой вы бы никогда не узнали. Меняете фильтры — начинайте выгрузку заново, без cursor.
• limit посреди выгрузки менять можно — на него курсор не завязан.

Сохраните meta.sync_cursor из любого ответа бэкфилла (он отдаётся в обоих режимах и снимается до выборки) и дальше ходите с since=<это значение>. Режим отдаёт всё, что появилось и изменилось после этого момента, от старых к новым; внутри него листание тоже курсорное. В конце запомните новый sync_cursor.

Пока на сервере не прогнана миграция отметок загрузки, режим since отвечает 503 с текстом про то, что отметки ещё не ведутся. Это ожидаемое состояние сразу после запуска API, а не поломка у вас: выгружайтесь пока курсором, это тот же самый набор данных. У /v1/my/defects такой зависимости нет — там since идёт по времени разбора и работает всегда.

Отметки не заполняются задним числом: since видит только то, что появилось и поправилось после запуска API. Поэтому первая выгрузка обязана быть курсорной — since=2000-01-01 историю не отдаст.

• Эмодзи в текстах отзывов потеряны. Это честная оговорка, а не оговорка на всякий случай: таблица чекинов у нас в кодировке, куда эмодзи не помещаются, и наш сборщик обрезает текст на первом же символе. Мы отдаём то, что лежит в базе, — то есть текст без эмодзи, а иногда и укороченный на них. Обещать «слово в слово, как написал покупатель» мы не можем.
• CORS выключен, и это не забывчивость. Заголовков Access-Control-Allow-Origin нет и не будет: обратиться к API из браузерного JavaScript означает положить ключ в код страницы, то есть отдать выгрузку своей пивоварни любому, кто откроет исходник. Ходите за данными со своего сервера. Если задача — показать блок «наши сорта» или экран на стене, для этого есть готовые виджеты feed/: они не требуют ключа вовсе, и ссылку на такой экран выдаёт поддержка.
• Ключ именной. Один ключ — один аккаунт с одной закреплённой пивоварней. Смена пивоварни у аккаунта меняет и то, что отдают /v1/my/*.
• Номера сущностей у нас и у источника одни и те же. beer_id, brewery_id, venue_id, chekin_id — те же числа, что в адресах источника. Отдельного «нашего» идентификатора нет, сопоставлять ничего не нужно.
• Ноль в оценке — это «оценки нет». Мы отдаём такие как null. Не считайте по ним среднее: у нас оно тоже считается только по чекинам с оценкой, и именно поэтому числа в API сходятся с числами на сайте.
• has_photo: true не гарантирует photo_url. У части старых чекинов известен факт фото, но не его адрес. Это разные вопросы, и поля отвечают на разные.
• Название сорта приходит как null, если страницу сорта не удалось разобрать — это не «сорт называется никак». То же и со стилем. Пустых строк в этих полях не бывает нигде: ни на публичных маршрутах, ни на /my/*, проверять достаточно на null. Обычно чинится само в течение суток.
• Метрики и рейтинги пересобираются раз в час. Опрашивать их чаще смысла нет — используйте ETag и сэкономьте лимит.

Оба делают одно и то же и полностью рабочие: первый запуск выкачивает всю историю курсором, каждый следующий догружает изменения по since. Строки кладутся upsert'ом по chekin_id, отметка синхронизации хранится рядом. Запускать вторым скриптом по расписанию — раз в 15–30 минут более чем достаточно.

<?php
/**
 * Выгрузка чекинов своей пивоварни в локальную таблицу.
 * Первый запуск — полный бэкфилл курсором, дальше догрузка по since.
 */

$KEY   = getenv('TAPPD_KEY');                 // ключ в коде не держим
$BASE  = 'https://tappd.ru/api/v1';
$STATE = __DIR__ . '/tappd_sync.json';        // тут храним sync_cursor

$pdo = new PDO('mysql:host=localhost;dbname=my;charset=utf8mb4', 'user', 'pass',
    array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION));

/** Один запрос к API с повтором на 5xx и 429. */
function api($path, array $query, $key) {
    $url = $path . (strpos($path, '?') === false ? '?' : '&') . http_build_query($query);

    for ($try = 1; $try <= 5; $try++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, array(
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => array('X-Api-Key: ' . $key),
            CURLOPT_TIMEOUT        => 60,
            CURLOPT_HEADER         => true,
        ));
        $raw  = curl_exec($ch);
        $code = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $hlen = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $head = substr((string) $raw, 0, $hlen);
        $body = substr((string) $raw, $hlen);
        curl_close($ch);

        // 5xx бывают в первую минуту после выкладки — это норма, надо ретраить.
        // 429 говорит, сколько ждать, в заголовке Retry-After.
        if ($code >= 500 || $code === 429 || $raw === false) {
            $wait = 2 * $try;
            if (preg_match('/^Retry-After:\s*(\d+)/mi', $head, $m)) $wait = (int) $m[1];
            sleep(min($wait, 120));
            continue;
        }

        $json = json_decode($body, true);
        if ($code !== 200) {
            $e = isset($json['error']) ? $json['error'] : array();
            throw new RuntimeException('API ' . $code . ' ' . (isset($e['code']) ? $e['code'] : '')
                . ': ' . (isset($e['message']) ? $e['message'] : $body)
                . ' (request_id ' . (isset($e['request_id']) ? $e['request_id'] : '?') . ')');
        }
        return $json;
    }
    throw new RuntimeException('API недоступен после пяти попыток: ' . $url);
}

/** UPSERT: since отдаёт и НОВЫЕ строки, и ПРАВКИ уже отданных. */
function save(PDO $pdo, array $rows) {
    $st = $pdo->prepare(
        'INSERT INTO checkins (chekin_id, dt, beer_id, beer_name, username, rating,
                               text, has_photo, venue_name, served, is_collab)
         VALUES (:id, :dt, :bid, :bname, :user, :rating, :text, :photo, :venue, :served, :collab)
         ON DUPLICATE KEY UPDATE
             dt = VALUES(dt), beer_id = VALUES(beer_id), beer_name = VALUES(beer_name),
             rating = VALUES(rating), text = VALUES(text), has_photo = VALUES(has_photo),
             venue_name = VALUES(venue_name), served = VALUES(served), is_collab = VALUES(is_collab)');

    foreach ($rows as $r) {
        $st->execute(array(
            ':id'     => $r['chekin_id'],
            ':dt'     => $r['datetime'],
            ':bid'    => $r['beer']['id'],
            ':bname'  => $r['beer']['name'],
            ':user'   => $r['username'],
            ':rating' => $r['rating'],          // null = оценки не ставили
            ':text'   => $r['text'],
            ':photo'  => $r['has_photo'] ? 1 : 0,
            ':venue'  => $r['venue']['name'],
            ':served' => $r['served'],
            ':collab' => $r['is_collab'] ? 1 : 0,
        ));
    }
}

$state = is_file($STATE) ? json_decode(file_get_contents($STATE), true) : array();
$since = isset($state['sync_cursor']) ? $state['sync_cursor'] : '';

$query = array('limit' => 500);
if ($since !== '') $query['since'] = $since;    // пусто — значит первый запуск, идём курсором

$total = 0;
$mark  = $since;

while (true) {
    $res  = api($BASE . '/my/checkins', $query, $KEY);
    $rows = $res['data'];
    $meta = $res['meta'];

    save($pdo, $rows);
    $total += count($rows);

    // Снимок берём из ПЕРВОГО ответа: он сделан ДО выборки, и всё, что появилось
    // за время выгрузки, догрузится в следующий раз.
    if ($mark === $since && !empty($meta['sync_cursor'])) $mark = $meta['sync_cursor'];

    // Свежесть данных: пустой ответ и вставший парсер выглядят одинаково.
    if (isset($meta['data_age_min']) && $meta['data_age_min'] > 180) {
        error_log('[tappd] данные не обновлялись ' . $meta['data_age_min'] . ' мин');
    }

    if (empty($meta['has_more'])) break;
    $query['cursor'] = $meta['next'];           // курсор возвращаем КАК ЕСТЬ
}

if ($mark !== '') file_put_contents($STATE, json_encode(array('sync_cursor' => $mark)));
echo "загружено строк: $total\n";

#!/usr/bin/env python3
"""Выгрузка чекинов своей пивоварни: бэкфилл курсором, дальше догрузка по since."""

import json
import os
import pathlib
import re
import time

import requests

KEY   = os.environ["TAPPD_KEY"]           # ключ в коде не держим
BASE  = "https://tappd.ru/api/v1"
STATE = pathlib.Path(__file__).with_name("tappd_sync.json")

session = requests.Session()
session.headers["X-Api-Key"] = KEY        # основной способ передать ключ


def api(path, **params):
    """Один запрос с повтором на 5xx и 429."""
    for attempt in range(1, 6):
        r = session.get(BASE + path, params=params, timeout=60)

        # 5xx бывают в первую минуту после выкладки — это норма, надо ретраить.
        if r.status_code >= 500 or r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 2 * attempt))
            time.sleep(min(wait, 120))
            continue

        if r.status_code != 200:
            e = r.json().get("error", {})
            raise RuntimeError(
                f"API {r.status_code} {e.get('code')}: {e.get('message')} "
                f"(request_id {e.get('request_id')})"
            )
        return r.json()

    raise RuntimeError(f"API недоступен после пяти попыток: {path}")


def save(rows):
    """UPSERT: since отдаёт и НОВЫЕ строки, и ПРАВКИ уже отданных."""
    with connection.cursor() as cur:        # ваш драйвер БД
        cur.executemany(
            """INSERT INTO checkins (chekin_id, dt, beer_id, beer_name, username,
                                     rating, text, has_photo, venue_name, served, is_collab)
               VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
               ON DUPLICATE KEY UPDATE
                   dt = VALUES(dt), beer_id = VALUES(beer_id), beer_name = VALUES(beer_name),
                   rating = VALUES(rating), text = VALUES(text), has_photo = VALUES(has_photo),
                   venue_name = VALUES(venue_name), served = VALUES(served),
                   is_collab = VALUES(is_collab)""",
            [
                (
                    r["chekin_id"], r["datetime"], r["beer"]["id"], r["beer"]["name"],
                    r["username"], r["rating"],          # None = оценки не ставили
                    r["text"], int(r["has_photo"]), r["venue"]["name"],
                    r["served"], int(r["is_collab"]),
                )
                for r in rows
            ],
        )
    connection.commit()


state = json.loads(STATE.read_text()) if STATE.exists() else {}
since = state.get("sync_cursor", "")

params = {"limit": 500}
if since:
    params["since"] = since               # пусто — первый запуск, идём курсором

total, mark = 0, since

while True:
    res = api("/my/checkins", **params)
    rows, meta = res["data"], res["meta"]

    save(rows)
    total += len(rows)

    # Снимок берём из ПЕРВОГО ответа: он сделан ДО выборки, и всё, что появилось
    # за время выгрузки, догрузится в следующий раз.
    if mark == since and meta.get("sync_cursor"):
        mark = meta["sync_cursor"]

    # Свежесть данных: пустой ответ и вставший парсер выглядят одинаково.
    age = meta.get("data_age_min")
    if age is not None and age > 180:
        print(f"[tappd] данные не обновлялись {age} мин")

    if not meta.get("has_more"):
        break
    params["cursor"] = meta["next"]       # курсор возвращаем КАК ЕСТЬ

if mark:
    STATE.write_text(json.dumps({"sync_cursor": mark}))
print(f"загружено строк: {total}")

В каждом ответе есть meta.contract — дата контракта. Сейчас это 2026-09-01.

• Новое поле — не ломающее изменение. Поля могут появляться в любом ответе в любой момент, и дату контракта это не двигает.
• Новое значение перечисления — тоже не ломающее. В source, served, status, кодах дефектов и тонов со временем появятся значения, которых сегодня нет.
• Клиент обязан игнорировать неизвестное. Разбирайте то, что знаете, и молча пропускайте остальное. Код, падающий на незнакомом поле или значении, сломается на нашем обычном вторнике.
• Дату контракта двигает только по-настоящему ломающее изменение — удаление поля, смена его типа или смысла. О таком мы предупреждаем письмом за месяц.
• /v2/ не будет. Вторая версия при одном разработчике означала бы вечную двойную поддержку, и обе половины поехали бы.

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

Заметили, что ключ утёк, — отзовите его в кабинете и выпустите новый; всё, что выпущено раньше, продолжает работать, пока не отозвано. Вопросы, ошибки и просьбы — в поддержку, и назовите request_id из ответа или префикс своего ключа: по ним запрос находится в журнале за секунду.