Доступ к API и AI-агентам

SimplyQuote предоставляет REST API, чтобы ваши AI-агенты, скрипты и интеграции могли работать с вашими предложениями и счетами от вашего имени. Доступ контролируется персональными токенами с ограниченной областью действия, которые можно отозвать.

1. Включите доступ к API

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

2. Выполните запрос

Передавайте токен как Bearer-токен в заголовке Authorization:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. Создание и обновление документов

Для создания и обновления предложений и счетов используется тот же токен с областью записи. Итоговые суммы всегда рассчитываются на сервере по переданным позициям:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

Ответ при успехе (списки аналогичны: quotes/invoices плюс total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Списки и пагинация

Конечные точки списков принимают updated_since (ISO 8601), page (по умолчанию 1), limit (по умолчанию 20, максимум 100) и status (без учёта регистра; неизвестные значения игнорируются). Ответы содержат total, page, limit и has_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

Правила полей для создания и обновления

items обязателен в POST: непустой массив, каждая позиция с непустым description, quantity > 0 (по умолчанию 1), unit_price >= 0 (по умолчанию 0). tax_rate — процент (0–100); при создании tax_rate > 0 подразумевает tax_enabled. currency хранится в верхнем регистре. issue_date принимает любую валидную дату (хранится ГГГГ-ММ-ДД). Предложения используют expiry_date, счета — due_date (принимаются оба алиаса, null очищает). Статус: предложения draft|sent, счета draft|sent|viewed|paid|cancelled — установка paid фиксирует paid_at. Итоги всегда пересчитываются на сервере.

4. Использование с AI-агентом

Дайте вашему агенту базовый URL, ваш токен и список конечных точек ниже. Пример инструкций для любого агента с вызовом инструментов (Claude, GPT, LangChain и т. д.):

У тебя есть доступ к моему аккаунту SimplyQuote.
Базовый URL: https://simplyquote.net
В каждом запросе отправляй заголовок: Authorization: Bearer sq_ваш_токен
Доступные конечные точки: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
Списки поддерживают ?page, ?limit (макс. 100), ?status, ?updated_since и возвращают { success:true, data:{ quotes|invoices, total, page, limit, has_more } }.
Одиночные GET возвращают bare-объект. {id} — это UUID, а не номер документа.
Для создания документов используй POST — всегда отправляй items с description, quantity и unit_price.

5. Подключение через MCP (рекомендуется для агентов)

В SimplyQuote встроен MCP-сервер (Model Context Protocol) по адресу /api/mcp (stateless streamable HTTP, JSON-RPC 2.0). Агенты с поддержкой удалённых MCP-серверов (Claude, ChatGPT, Cursor, VS Code и др.) могут подключаться напрямую с вашим токеном — без настройки промптов. Доступные инструменты:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

Пример вызова инструмента (JSON-RPC 2.0 — пакетные запросы отклоняются, уведомления возвращают 202, GET возвращает 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

Каждый вызов инструмента проверяется по областям вашего токена — токен только для чтения может получать списки и данные, а для создания предложений или счетов нужна соответствующая область записи.

Конечные точки

Области доступа

• quotes:read — Чтение ваших предложений
• invoices:read — Чтение ваших счетов
• clients:read — Зарезервировано — отдельной конечной точки клиентов пока нет (данные клиента есть в предложениях/счетах)
• quotes:write — Создание и обновление предложений
• invoices:write — Создание и обновление счетов
• clients:write — Зарезервировано — отдельной конечной точки клиентов пока нет (данные клиента создаются/обновляются неявно при сохранении предложений/счетов)

Формат ответов и ошибки

В конечных точках REST используются два формата — проверяйте, какой из них применим:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

Одиночные GET возвращают bare-объект выше (без обёртки) с плоскими ошибками { error, message } — например 404 при неизвестном id. Списки и POST/PATCH всегда используют обёртку.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true при успехе, false при ошибке
• data — данные при успешном запросе
• error — код ошибки, сообщение и дополнительные сведения при ошибке

Наиболее частые коды ошибок:

• UNAUTHORIZED — Токен отсутствует, недействителен или истёк (HTTP 401)
• FORBIDDEN — У токена нет требуемой области (HTTP 403)
• VALIDATION_ERROR — Тело запроса не прошло проверку (HTTP 400)
• NOT_FOUND — Запрошенный документ не существует (HTTP 404)
• DATABASE_ERROR — Ошибка хранилища при обработке запроса (HTTP 500)
• RATE_LIMIT — Слишком много запросов — повторите позже (HTTP 429)

Вебхуки, OAuth и полный справочник

Вебхуки: управляйте подписками через GET/POST/PATCH/DELETE /api/v1/webhooks (любой валидный токен, отдельная область не нужна). url должен быть публичной HTTPS-точкой. Секрет возвращается только при создании — проверяйте доставку по заголовку X-SimplyQuote-Signature (HMAC-SHA256).

Партнёрские приложения используют OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) вместо персональных токенов. Подробности — в docs/API.md и в машиночитаемой спецификации по адресу /api/v1/openapi.json.

Заметки по безопасности

• Токены хранятся в виде хэшей — SimplyQuote никогда не сохраняет исходный токен.
• Выдавайте только нужные агенту области; обычно достаточно доступа только для чтения.
• Отзывайте токен в любой момент в настройках — доступ закрывается мгновенно.
• Машиночитаемая спецификация для агентов доступна по адресу /api/v1/openapi.json