API v2 — документация

1. Начало работы

Три шага до первого запроса: получите ключ API в личном кабинете, отправьте запрос на единый адрес /api/v2 с обязательными параметрами key и action, разберите JSON-ответ. Валюта счёта — рубли (RUB).

Базовый URL

Все методы вызываются относительно базового URL. Этот же адрес сервер отдаёт в поле api_url ответа GET /api/config.

Первый запрос — проверка баланса:

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=balance

2. Аутентификация

Аутентификация выполняется по персональному ключу API формата bc_live_…. Ключ выдаётся в личном кабинете после регистрации и передаётся в каждом запросе параметром key.

Ключ можно перевыпустить в кабинете (старый при этом перестаёт действовать). Храните ключ в тайне: он даёт полный доступ к заказам и балансу аккаунта.

Где взять ключ:

1. Зарегистрируйтесь и войдите в личный кабинет.
2. Откройте раздел с API-ключом — там отображается ключ вида bc_live_xxxxxxxxxxxxxxxxxx.
3. При необходимости нажмите «Перевыпустить», чтобы заменить ключ.

3. Формат запросов и ответов

Все методы вызываются по одному адресу /api/v2. Запрос можно отправить как GET (параметры в query-строке), так и POST (тело в application/x-www-form-urlencoded или application/json). Обязательные для всех запросов параметры: key (ключ API) и action (имя метода).

Ответ всегда в формате JSON. Успешный ответ содержит поля метода; ошибка возвращается объектом с полем error и текстом причины. Денежные значения — в рублях (валюта счёта RUB), в ответах присутствует поле currency; числовые поля (rate, min, max, charge, start_count, remains) приходят строками. Скидка уровня аккаунта (зависит от суммы заказов за последние 60 дней) применяется автоматически к фактическому списанию при add — одинаково в кабинете и через API; rate в services — базовая цена без скидки.

Интерфейс панели может дополнительно показывать суммы в долларах по текущему курсу — это справочный эквивалент для удобства; расчёты и списания всегда идут в рублях. Курс и округление ориентировочны, API не гарантирует бухгалтерскую точность отображаемого $-эквивалента.

4. Методы

Единый эндпоинт поддерживает действия ниже. Столбец «Статус» показывает реальную готовность метода; экспериментальные и планируемые возможности вынесены в раздел «Ограничения».

5. Справочник методов

Полное описание каждого метода: параметры, пример запроса (curl) и фактический формат ответа. Идентификаторы в примерах иллюстративны.

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=services

[
  {
    "service": 1001,
    "name": "Instagram Followers [Refill 30D] [Max: 100K]",
    "type": "Default",
    "category": "Instagram — Followers",
    "rate": "130.5",
    "min": "115",
    "max": "100000",
    "refill": true,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": true
  },
  {
    "service": 1002,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram — Likes",
    "rate": "48.0",
    "min": "313",
    "max": "50000",
    "refill": false,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": true
  },
  {
    "service": 1003,
    "name": "YouTube Views (broken data)",
    "type": "Default",
    "category": "YouTube — Views",
    "rate": "90.0",
    "min": "1000",
    "max": "20",
    "refill": false,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": false
  }
]

# Default
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add \
  -d service=1001 \
  -d link=https://instagram.com/example \
  -d quantity=1000

# Drip-feed (повторы) — runs + interval
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1002 \
  -d link=https://youtube.com/watch?v=xxxx \
  -d quantity=1000 -d runs=10 -d interval=30

# Custom Comments (планируется) — comments, по одному в строке
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1001 \
  -d link=https://instagram.com/p/xxxx \
  --data-urlencode $'comments=Отличный пост!\nОгонь\nЖду ещё'

# Mentions (планируется) — usernames
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1001 \
  -d link=https://instagram.com/p/xxxx \
  -d usernames=user_a,user_b,user_c

# успех — ID созданного заказа
{ "order": 23501 }

# ошибка (недостаточно средств на балансе)
{ "error": "Not enough funds on the balance" }

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=status \
  -d order=23501

{
  "charge": "15.32",
  "start_count": "1273",
  "status": "Pending",
  "remains": "1000",
  "currency": "RUB"
}

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=status \
  -d orders=23501,23502

{
  "23501": { "charge": "15.32", "start_count": "1273", "status": "Completed", "remains": "0", "currency": "RUB" },
  "23502": { "error": "Incorrect order ID" }
}

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=balance

{
  "balance": "34.68",
  "currency": "RUB"
}

# один заказ
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill \
  -d order=23501

# несколько заказов
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill \
  -d orders=23501,23502

# один заказ (order=ID) — идентификатор долива (= ID заказа)
{ "refill": 23501 }

# несколько (orders=ID,ID) — массив по каждому заказу
[
  { "order": "23501", "refill": 23501 },
  { "order": "23502", "error": "Refill is not available for this order" }
]

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill_status \
  -d refill=23501

{ "status": "Completed" }

# долив ещё выполняется
{ "status": "In progress" }

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=cancel \
  -d orders=23501,23502

[
  { "order": "23501", "cancel": 1 },
  { "order": "23502", "cancel": { "error": "Order can not be canceled" } }
]

6. Ограничения и экспериментальное

Ниже — то, что реализовано частично или пока только планируется. Не используйте эти возможности как готовые.

• Планируется Custom Comments. Тип заказа «свои комментарии» (параметр comments в add) пока не реализован — add принимает только Default и Drip-feed.
• Планируется Mentions. Тип заказа «упоминания» (параметр usernames) пока не реализован.
• базово refill_status. Отдаётся упрощённо: только Completed или In progress. Отдельного детального статуса долива пока нет.
• Планируется Идентификатор долива. Сейчас поле refill совпадает с ID заказа; отдельные ID запросов на долив планируются.
• Планируется Идемпотентность add. Защиты от двойного заказа нет: повторный add с теми же параметрами создаст новый заказ и повторно спишет средства. Ключ идемпотентности планируется.
• Поведение при таймауте. Если запрос add завершился сетевым таймаутом, заказ мог быть уже создан на сервере. Не повторяйте запрос вслепую: сначала проверьте balance и свежий status, и только затем при необходимости повторяйте.

7. Ошибки

Ошибки возвращаются объектом с полем error и текстом причины. Ниже — фактические тексты ошибок, которые отдаёт API v2.

8. История изменений

Кратко о версиях публичного API.

• v2 — текущая. Публичный key-API: services, add (Default, Drip-feed), status (один и несколько), balance, refill, cancel. Валюта счёта — RUB, числовые значения строками. refill_status — базово.
• v2.1 — планируется. Типы заказа Custom Comments и Mentions, ключ идемпотентности для add, отдельные ID запросов на долив и детальный refill_status.