API PromoPilot

Єдиний REST API екосистеми PromoPilot: запускайте посилальне просування, відстежуйте позиції, проводьте SEO-аудити та сканування безпеки з вашого коду — CRM, SaaS, панелей агентства.

• Базова адреса: https://promopilot.link/api/v1
• Формат — JSON поверх HTTPS; всі відповіді містять поле ok.
• Проєкти, створені через API, показуються в кабінеті окремим розділом «Проєкти API» і позначаються бейджем — вони не змішуються з особистими.
• Машиночитувана специфікація: openapi.json

curl https://promopilot.link/api/v1/ping
# {"ok":true,"pong":true,"time":"2026-07-20T12:00:00Z"}

Авторизація та ключі

Ключі API видаються в клієнтському кабінеті: Кабінет → API для розробників. При створенні ключа ви обираєте, до яких сервісів він має доступ (скоупи): promotion, rank, audit, shield. Ключ показується повністю один раз — ми зберігаємо тільки його SHA-256 відбиток.

Authorization: Bearer ppk_ваш_ключ
# или
X-Api-Key: ppk_ваш_ключ

Білінг та баланс

• Усі платні операції списуються з особистого балансу акаунта — того ж, що й у кабінеті. Окремого «API-балансу» немає.
• Просування: ціна за тарифом / гнучким каскадом / глобальною ціною, мінус ваша персональна знижка; підписники Pro автоматично отримують додаткову знижку 10%.
• Перед запуском можна дізнатися точну ціну: POST /promotion/quote (без списання).
• Rank Tracker — списання за фактом перевірок; SEO Audit full — передоплата за оцінкою розміру; Shield deep/comprehensive — фіксована ціна сканування.
• Якщо коштів недостатньо — HTTP 402 insufficient_funds з полями required, balance, shortfall та посиланням на поповнення topup_url. Поповнення балансу виконується в кабінеті.

Формат помилок

{
  "ok": false,
  "error": {
    "code": "insufficient_funds",
    "message": "Недостатньо коштів на балансі. Поповніть баланс у кабінеті та повторіть запит.",
    "details": {"required": 44.1, "balance": 10.0, "shortfall": 34.1, "topup_url": "…"}
  }
}

Ліміти

• 120 запитів на хвилину на ключ (базовий ліміт).
• Запуск просування — до 20 на хвилину; створення проектів — до 30 на годину; запуск аудитів/сканів — до 10 на хвилину.
• При перевищенні — HTTP 429 з заголовком Retry-After. Рекомендована частота опитування статусів — раз у 30–60 секунд.

Локалізація

Людочитні повідомлення (message) повертаються мовою з параметра ?lang= (ru, en, uk, pl) або заголовка Accept-Language; за замовчуванням — мова вашого акаунта. Машинні коди помилок і статуси не перекладаються — прив'язуйте логіку до них.

Довідник ендпоінтів

Обліковий запис

{"ok":true,"user":{"id":2,"balance":124.50,"currency":"USD","promotion_discount_percent":10,"is_pro":true,...},"key":{"label":"CRM","scopes":["promotion"]}}

{"ok":true,"balance":124.50,"currency":"USD","topup_url":"…/client/balance.php"}

{"ok":true,"key":{"label":"CRM","scopes":["promotion","rank"],"requests_total":1520,...}}

Проекти та посилання скоуп: promotion

{"ok":true,"projects":[{"id":311,"name":"Client A","created_via":"api","links_count":3,"active_runs":1,...}]}

{"ok":true,"project":{"id":312,"created_via":"api",...},"links":{"added":2,"domain_errors":0}}

{"ok":true,"project":{"id":312,"links":[...],"runs":[...]}}

{"ok":true,"project":{...}}

{"ok":true,"deleted":true}

{"ok":true,"link":{"id":915,"url":"https://site.com/page",...},"links_count":4}

{"ok":true,"deleted":true}

Просування (каскади) скоуп: promotion

{"ok":true,"tariffs":[{"id":3,"slug":"pro","name":"Pro","price_per_link":49.0,"cascade":{...}}],"your_discount_percent":10}

{"ok":true,"pricing_mode":"tariff","base_price":49.0,"discount_percent":10,"total":44.1,"balance":124.5,"sufficient_funds":true}

{"ok":true,"run_id":501,"status":"queued","charged":44.1,"discount_percent":10,"balance_after":80.4,"currency":"USD"}

{"ok":true,"runs":[{"id":501,"status":"level1_active","progress":{"done":3,"total":12,"pct":25},...}],"pagination":{...}}

{"ok":true,"run":{"id":501,"status":"level2_active","levels":[{"level":1,"total":5,"verified":5},...]}}

{"ok":true,"run_id":501,"nodes":[{"level":1,"network":"telegraph","url":"https://telegra.ph/…","verified":true,...}]}

Звіти та white-label (Pro) скоуп: promotion

{"ok":true,"run":{...},"summary":{"verified":12,...},"report":{"level1":[...],"level2":[...],"crowd":[...]},"whitelabel":{...}} — или {"ok":true,"pdf":{"url":"…/uploads/reports/api-cascade-501-….pdf"},"branded":true}

{"ok":true,"is_pro":true,"branding_active":true,"branding":{"company_name":"Acme","logo_url":"…","accent_color":"#6366f1",...}}

{"ok":true,"branding":{...}}

Rank Tracker скоуп: rank

{"ok":true,"projects":[{"id":7,"domain":"site.com","region":"UA","keywords_count":50,"top10":12,...}]}

{"ok":true,"project":{"id":8,...}}

{"ok":true,"project":{...},"keywords":[{"id":91,"keyword":"купить окна","last_position":4,"last_checked_at":"…"}]}

{"ok":true,"added":25,"skipped":0}

{"ok":true,"queued":50,"note":"…"}

SEO Audit скоуп: audit

{"ok":true,"projects":[{"id":4,"domain":"site.com","start_url":"https://site.com/",...}]}

{"ok":true,"project":{"id":5,...}}

{"ok":true,"has_estimate":true,"estimated_pages":430,"full_audit_price":5.0,"currency":"USD"}

{"ok":true,"crawl_id":88,"mode":"full","max_pages":500,"charged":5.0}

{"ok":true,"crawl":{"id":88,"status":"done","health_score":79,"pages_crawled":430,"issues":{...}}}

{"ok":true,"crawls":[...]}

Security Shield скоуп: shield

{"ok":true,"projects":[{"id":3,"domain":"site.com","verified":true,...}]}

{"ok":true,"project":{"id":3,"verified":false,"verify_token":"pp-verify-…"},"verification_hint":"…"}

{"ok":true,"verified":true,"method":"dns"}

{"ok":true,"scan_id":41,"mode":"deep","charged":19.0}

{"ok":true,"scan":{"id":41,"status":"done","score":86,"grade":"B","verdict":{...},"findings_summary":{"critical":0,"high":1,...},"share_report_url":"…"}}

Приклади коду

cURL — створити проект і запустити просування

curl -X POST https://promopilot.link/api/v1/projects \
  -H "Authorization: Bearer ppk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Site",
    "url": "https://client-site.com",
    "language": "ru",
    "links": [{"url": "https://client-site.com/services", "anchor": "услуги компании"}]
  }'

curl -X POST https://promopilot.link/api/v1/promotion/runs \
  -H "Authorization: Bearer ppk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 312, "url": "https://client-site.com/services"}'

PHP

<?php
$key = getenv('PROMOPILOT_API_KEY'); // никогда не храните ключ в коде
function pp_api(string $method, string $path, array $data = null) {
    global $key;
    $ch = curl_init('https://promopilot.link/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $key,
            'Content-Type: application/json',
            'Accept-Language: ru',
        ],
        CURLOPT_POSTFIELDS => $data !== null ? json_encode($data) : null,
    ]);
    $res = json_decode(curl_exec($ch), true);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if (($res['ok'] ?? false) !== true) {
        throw new RuntimeException($res['error']['code'] ?? ('http_' . $code));
    }
    return $res;
}

$project = pp_api('POST', '/projects', ['name' => 'Client', 'url' => 'https://client-site.com']);
try {
    $run = pp_api('POST', '/promotion/runs', [
        'project_id' => $project['project']['id'],
        'url' => 'https://client-site.com/services',
    ]);
    echo "Запущено, run_id={$run['run_id']}, списано {$run['charged']}";
} catch (RuntimeException $e) {
    if ($e->getMessage() === 'insufficient_funds') {
        // пополните баланс и повторите
    }
}

Python

import os, requests

API = "https://promopilot.link/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROMOPILOT_API_KEY']}"}

def api(method, path, **json_body):
    r = requests.request(method, API + path, headers=HEADERS, json=json_body or None, timeout=30)
    data = r.json()
    if not data.get("ok"):
        code = data.get("error", {}).get("code", f"http_{r.status_code}")
        if code == "insufficient_funds":
            details = data["error"]["details"]
            raise RuntimeError(f"Пополните баланс: не хватает {details['shortfall']}")
        raise RuntimeError(code)
    return data

project = api("POST", "/projects", name="Client", url="https://client-site.com")
run = api("POST", "/promotion/runs", project_id=project["project"]["id"],
          url="https://client-site.com/services")
print("run_id:", run["run_id"], "charged:", run["charged"])

# Поллинг статуса
import time
while True:
    st = api("GET", f"/promotion/runs/{run['run_id']}")["run"]
    print(st["status"], st["progress"]["pct"], "%")
    if st["status"] in ("completed", "failed", "cancelled"):
        break
    time.sleep(60)

report = api("GET", f"/promotion/runs/{run['run_id']}/report")

Node.js

const API = "https://promopilot.link/api/v1";
const KEY = process.env.PROMOPILOT_API_KEY;

async function api(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json",
      "Accept-Language": "ru",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!data.ok) {
    const code = data.error?.code || `http_${res.status}`;
    if (code === "insufficient_funds") {
      console.error("Пополните баланс:", data.error.details.topup_url);
    }
    throw new Error(code);
  }
  return data;
}

const { project } = await api("POST", "/projects", { name: "Client", url: "https://client-site.com" });
const run = await api("POST", "/promotion/runs", { project_id: project.id, url: "https://client-site.com/services" });
console.log("run:", run.run_id, "charged:", run.charged);

OpenAPI

Повна машиночитувана специфікація для генерації клієнтів та імпорту в Postman/Insomnia: https://promopilot.link/api/v1/openapi.json

Запитання та пропозиції щодо API — через підтримку в кабінеті або Telegram. Зворотна сумісність: зміни, що ламають контракт, виходять тільки новою версією (/api/v2), поточні поля не видаляються без анонсу в changelog.