Поиск получателя и кэш

GET /v1/recipients/lookup?username=durov&product=PREMIUM&months=3

{ "username": "durov", "found": true, "name": "Pavel Durov", "photoUrl": "https://…", "eligible": true }

• username принимается в формах durov, @Durov, https://t.me/durov: мы приводим его к нижнему регистру и отрезаем @ и ссылку.
• product: STARS (по умолчанию) или PREMIUM; для Premium обязателен months (3, 6 или 12), так проверяется, можно ли подарить (на активный Premium подарить нельзя, будет eligible: false). Для Stars eligible совпадает с found.
• found: false это обычный ответ 200, а не ошибка. На некорректный username ответ 400 (-9202), на Premium без months тоже 400 (-9203).
• Если поставщик сейчас недоступен (нет рабочего аккаунта или все упёрлись в лимит), ответ будет 502 (-9006): повторите через несколько секунд.
• Показывайте покупателю имя и аватар до оплаты: это снимает большинство ошибок «не тот username».

КэшCopy Anchor Link

Результаты кэшируются: найденные на 15 минут, ненайденные на 2 минуты. Одновременные одинаковые запросы склеиваются в один запрос к поставщику. Поэтому повторный lookup дешёвый, а POST /v1/orders сразу после lookup не ходит к поставщику ещё раз.

Если пользователь только что создал или сменил username, подождите пару минут: отрицательный результат ещё может быть в кэше.

ЛимитCopy Anchor Link

120 поисков в минуту на Project (вместо общего лимита ключа: поиски в 600 запросов ключа не считаются). Не проверяйте username на каждое нажатие клавиши, делайте debounce от 300 до 500 мс.

curl -X GET "https://example.com/v1/recipients/lookup?username=string"

{  "success": true,  "data": {    "username": "durov",    "found": true,    "name": "Pavel Durov",    "photoUrl": "https://cdn4.telesco.pe/file/durov.jpg",    "eligible": true  },  "meta": {    "requestId": "9f1c2b7e-3a4d-4e5f-8a6b-7c8d9e0f1a2b",    "timestamp": "2026-10-06T09:15:22.481Z",    "processingTimeMs": 38  }}