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

Читать первым. Здесь только «как достучаться»; что именно спрашивать — в API-SPRAVOCHNIK.md.

Что нужно иметь

1. Поднятый WireGuard. Тот же, через который открывается просмотрщик базы. Без него не откроется ничего.
2. Свой ключ. Персональный, не общий на троих. Выдаётся отдельно и в чат не пересылается.

Проверка, что сеть в порядке: откройте просмотрщик по адресу http://10.77.0.1:8011. Открылся — сеть работает, и дальше дело только в ключе.

Адрес службы

http://10.77.0.1:8014

Тот же узел, что у просмотрщика, другой порт. Просмотрщик — 8011, данные — 8014. Порт открыт только с ваших адресов в WireGuard; из интернета его нет.

Первый запрос

Ключ передаётся заголовком Authorization. Но сначала — жива ли служба вообще. Этот адрес ключа не требует:

curl -s http://10.77.0.1:8014/health

Ответ {"status":"ok"} означает, что сеть в порядке. Теперь проверка ключа — все адреса с данными лежат под /api/v1:

curl -s -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "http://10.77.0.1:8014/api/v1/facts/stocks-daily?limit=2"

Ответ вида {"data": [...], "page": {...}, "meta": {...}} — и сеть, и ключ в порядке.

⚠️ Забыть /api/v1 — самая частая ошибка первого дня. Без него придёт 404, и выглядит это как «такого отчёта нет», хотя отчёт есть.

Ключ в коде — не строкой

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

export GWPTD_API_KEY='...'
curl -s -H "Authorization: Bearer $GWPTD_API_KEY" \
  http://10.77.0.1:8014/api/v1/status/freshness

В Python:

import os, requests

KEY = os.environ["GWPTD_API_KEY"]
BASE = "http://10.77.0.1:8014"   # адреса с данными — под /api/v1

otvet = requests.get(
    f"{BASE}/api/v1/facts/stocks-daily",
    headers={"Authorization": f"Bearer {KEY}"},
    params={"limit": 2},
    timeout=30,
)
otvet.raise_for_status()
print(otvet.json()["data"])

⚠️ В браузерной странице ключ не размещается. Всё, что попало в JavaScript, видно любому, кто откроет страницу. Как делать страницу, которой нужны данные, — в UI-STRANICA.md, раздел «Откуда страница берёт данные».

Что даёт ваш ключ

Только чтение. Формально — полномочия data:read и status:read, и служба проверяет их на каждом запросе.

Действие	Ответ
прочитать отчёт	данные
прочитать состояние сбора	данные
изменить что-либо	403
запустить сбор	403

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

Когда не отвечает

Что видите	Что это значит	Что делать
соединение не устанавливается	WireGuard не поднят или порт не проброшен	проверьте просмотрщик на 8011: не открылся — дело в WireGuard
401 missing bearer token	заголовок не дошёл	проверьте, что переменная не пустая: echo $GWPTD_API_KEY
401 invalid token	ключ не тот или отозван	напишите нам, ключ перевыпустим
403 missing scope	ключ не даёт этого действия	так и задумано; не обходить, а сказать нам, что вам нужно
404	такого адреса нет	ищите правильный: API-SPRAVOCHNIK.md
429 RATE_LIMITED	больше 60 запросов в минуту	берите страницами по 200–500 строк, а не по одной
503	источник данных временно недоступен	это честный ответ службы, а не ваша ошибка. Повторите позже
200, но data пуст	запрос отработал, строк нет	смотрите meta.data_status: no_data — законная пустота

Последнее важно и часто путает: пустой ответ — не поломка. Служба намеренно не подделывает успех и не выдумывает строки. Если купоны не запускались, отчёт по купонам честно пуст.

⚠️ Не всякий адрес из списка работает. Часть отвечает честным «501 — не сделано», а у отдельных отчётов есть свои поломки: на 11.08.2026, например, /api/v1/reports/amazon/coupons падает с ошибкой запроса к источнику. Это наша недоделка, а не ваша ошибка — сообщите, и мы починим. Какие адреса действительно работают, показывает разбор из API-SPRAVOCHNIK.md.

Ограничение частоты

Служба общая: её же читает основной сайт аналитики. Цикл, шлющий запросы без пауз, положит сайт всем.

• не более 60 запросов в минуту на ключ;
• забираете много — берите страницами, а не по одной строке (см. справочник);
• ночные выгрузки лучше согласовать, чтобы не совпали со сбором.

При превышении служба отвечает 429 с кодом RATE_LIMITED. Это видно в журнале с вашим ключом — ключи персональные именно поэтому.

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

Дальше

• какие адреса существуют и что они отдают — API-SPRAVOCHNIK.md;
• нужного адреса нет — API-NOVYY-OTCHET.md;
• задание своему ИИ-агенту — AGENTU.md.