# PapaProxy.net — API и MCP для разработчиков

Страница: https://papaproxy.net/ru/developers.php

Операции личного кабинета PapaProxy.net доступны через REST API и MCP-сервер. Оба интерфейса используют одни и те же API-ключи с правами доступа (scopes).

## Основное

- Базовый URL: `https://papaproxy.net/account_new/api/v1`
- Авторизация: заголовок `Authorization: Bearer <api_key>`
- Создать ключ: https://papaproxy.net/account_new/settings?locale=ru#api-keys
- Справочник OpenAPI 3.1: https://papaproxy.net/account_new/docs?locale=ru
- MCP-эндпоинт: `https://papaproxy.net/account_new/api/v1/mcp` (удалённый сервер, HTTP)
- Без ключа доступны: `GET /billing/countries` и `POST /billing/composite/quote`
- MCP-сервер с ключом даёт агенту 50 инструментов

## Без ключа

```bash
curl -s "https://papaproxy.net/account_new/api/v1/billing/countries?product_kind=proxy_datacenter"

curl -s -X POST https://papaproxy.net/account_new/api/v1/billing/composite/quote \
  -H "Content-Type: application/json" \
  -d '{"product_kind":"proxy_datacenter","period_months":1,"segments":[{"country":"US","count":100}]}'
```

В ответе расчёта цены указаны в центах (`total_price_cents`, `monthly_price_cents`).

## Подключение MCP

```json
{
  "mcpServers": {
    "papaproxy": {
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": { "Authorization": "Bearer fb_YOUR_API_KEY" }
    }
  }
}
```

Claude Code: `claude mcp add --transport http papaproxy https://papaproxy.net/account_new/api/v1/mcp --header "Authorization: Bearer fb_YOUR_API_KEY"`

## Покупка

1. `list_countries` / `GET /billing/countries?product_kind=proxy_datacenter|proxy_isp` — страны и остатки.
2. `quote_composite` / `POST /billing/composite/quote` — бесплатный расчёт без обязательств.
3. `order_composite` / `POST /billing/composite/order` — заказ с баланса.

Поля заказа: `product_kind` (`proxy_datacenter`, `proxy_isp`, `proxy_personal`), `segments` (`[{"country":"US","count":300}]`, ISO-2), `period_months` (1, 3, 6, 12), `whitelist_ips` (обязательно для прокси, иначе 422 до списания), `use_balance: true` (оплата с баланса), `idempotency_key`. Повтор того же заказа возвращает уже созданную услугу без повторного списания.

## Права ключей

- `catalog:read` — продукты, страны, цены
- `services:read` — услуги, списки IP, логины и пароли, привязки по IP
- `services:write` — смена логина и пароля, привязки по IP, замена IP, sticky-сессии, отмена
- `usage:read` — статистика
- `wallet:read` — баланс, движения по счёту, PDF-счета
- `wallet:deposit` — пополнение баланса
- `wallet:spend` — оплата с баланса: покупки, продления, дополнения, докупка IP, платная замена IP
- `tickets:read`, `tickets:write` — тикеты
- `customer:read`, `customer:write` — профиль
- `webhooks` — вебхуки

## Правила для агента

- Перед покупкой покажите пользователю расчёт и получите подтверждение.
- Для повторяемых платных операций передавайте `idempotency_key`.
- Не выводите API-ключ в ответах и не сохраняйте его в файлах проекта.
- Если не хватает права, сообщите, какое право нужно, а не обходите ограничение.