Если в кабинет ежедневно прилетает больше 10–15 заказов или вы — агентство, которое запускает заказы для нескольких клиентов одновременно, ручной ввод превращается в отдельную должность. API убирает эту работу полностью: интеграция занимает один спринт у одного разработчика, дальше система живёт сама и требует внимания только при изменении бизнес-логики на вашей стороне.
Эта статья — не сухая API-референс, а карта подключения от выпуска токена до получения статуса по вебхуку. С пометками о граблях, на которые наступили первые 30 интеграторов, и примерами кода на трёх языках, которые работают как есть.
Когда переходить на API
- Больше 10–15 заказов в день — ручной ввод съедает час-полтора
- Несколько клиентов в работе и нужна сегментация по биллингу
- Хочется триггерить заказ из внешней CRM по событию (новый пост → автоматический разгон)
- Нужны исторические данные по заказам в собственной БД для отчётов
- Хотите интегрировать накрутку в воронку продукта (например, разгонять контент внутри своей платформы)
Шаги подключения
- 1В настройках кабинета выпускаете API-токен. Токены отзываются и пересоздаются по одному клику
- 2Опционально — добавляете URL вебхука. Можно один на все события или разные на старт/успех/ошибку
- 3Делаете GET /services, чтобы получить актуальный каталог с providerServiceId, минимумами, максимумами и ценами
- 4POST /orders с serviceId, link и quantity — получаете обратно orderId и стартовый статус
- 5Слушаете обновления статуса через вебхук или периодический pull /orders/:id
Авторизация
Все запросы авторизуются bearer-токеном в заголовке Authorization. Токен живёт до отзыва — мы не делаем «истечение через 24 часа», потому что это создаёт больше проблем, чем решает (нужно где-то хранить refresh-токен, перевыдавать, синхронизировать между сервисами). При компрометации токен отзывается одной кнопкой в кабинете и всё, что было сделано до этого момента, остаётся в истории — при выпуске нового токена ничего не теряется.
Первый запрос — три варианта
Запрос на создание заказа — самый простой эндпоинт API. Минимум: serviceId (берём из /services), link (публичный URL объекта) и quantity. Опциональные поля: idempotencyKey (страховка от двойного списания при ретрае), webhookUrl (override на конкретный заказ), comment (метка для собственных отчётов).
cURL — для дебага и быстрых проверок
curl -X POST https://api.follu.biz/v1/orders -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' -d '{"serviceId": 814, "link": "https://t.me/example", "quantity": 1000, "idempotencyKey": "order-2026-04-01-001"}'
Python — для скриптов и кронов
import requests; r = requests.post('https://api.follu.biz/v1/orders', headers={'Authorization': f'Bearer {TOKEN}'}, json={'serviceId': 814, 'link': 'https://t.me/example', 'quantity': 1000}); print(r.json())
TypeScript — для бэкендов на Node
const r = await fetch('https://api.follu.biz/v1/orders', { method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ serviceId: 814, link: 'https://t.me/example', quantity: 1000 }) }); const data = await r.json();
Вебхуки vs polling
Если ваша интеграция боевая (а не разовый скрипт), вебхуки — правильный выбор. Polling /orders/:id раз в 30 секунд работает, но создаёт паразитный трафик и быстро упирается в лимиты. Вебхук приходит ровно тогда, когда статус меняется: started, in_progress, partial, completed, cancelled, error. Все события отправляются POST'ом, в теле — orderId, новый статус, дельта по выполнению, временная метка.
Обработка ошибок
Ответы — JSON с строгой схемой. Ошибки приходят со стандартными HTTP-кодами и человекочитаемым полем message — никаких «Error 0» без описания. 400 — валидация (неправильные параметры), 401 — нет/невалидный токен, 402 — недостаточно средств на балансе, 404 — сервис не найден, 409 — конфликт идемпотентности (повторный запрос с тем же idempotencyKey), 429 — rate limit, 5xx — наши проблемы. На 5xx можно ретраить через экспоненциальную задержку — система идемпотентна по idempotencyKey.
Лимиты и rate limiting
Стандартный лимит — 10 запросов в секунду на токен. Burst — 30 запросов в окне 3 секунды. Для большинства интеграций этого хватает с большим запасом. Если предполагается высокая нагрузка (агентство с сотнями заказов в час, интеграция в продуктовую воронку) — пишите в поддержку, поднимем индивидуально под задачу. Лимит проверяется на стороне gateway, при превышении приходит 429 с заголовком Retry-After.
Что мы добавим в API в ближайшие месяцы
- Batch endpoints — отправка до 50 заказов одним POST'ом
- GraphQL для гибких запросов по истории заказов
- Streaming-ответы для long-poll сценариев (полезно для дашбордов реального времени)
- OpenAPI-спецификация и автогенерируемые клиенты для Go, Java, PHP
Полная документация — на developers.follu.biz. Если что-то описано непонятно или не работает как ожидается — пишите, исправим в день обращения. API мы держим как продукт, а не как костыль.
