API для клиентов

Подключите свою учётную систему: каталог 1С, заказы и счета вашей организации — по REST API с токенами из личного кабинета.

Выпустить токен Спецификация OpenAPI 1.0.0

Авторизация

Базовый адрес: https://sdc-polet.ru/api/v1. Токен выпускается в личном кабинете (раздел «API-токены») и передаётся в заголовке:

curl https://sdc-polet.ru/api/v1/orders \
  -H "Authorization: Bearer polet_…" \
  -H "Accept: application/json"

У токена есть права — выдавайте только нужные:

catalog:read — Каталог и цены
orders:read — Мои заказы
orders:write — Создание заказов
invoices:read — Счета и PDF

Доступны заказы, оформленные вами, и все заказы организаций, связь с которыми подтвердил менеджер. Лимит — 60 запросов в минуту на токен.

Методы

Служебное

GET/api/v1/health
Проверка доступности API
Без токена. 200 — работает, 503 — нет связи с базой данных.
GET/api/v1/auth/me
Владелец токена, права токена и организации
Удобно для проверки токена при настройке интеграции.
DELETE/api/v1/auth/token
Отозвать текущий токен
Токен, с которым пришёл запрос, перестаёт действовать. Выпуск новых токенов — только в личном кабинете.

Каталог

GET/api/v1/catalog/categoriesправо catalog:read
Разделы каталога
GET/api/v1/catalog/productsправо catalog:read
Товары в продаже с текущими ценами
GET/api/v1/catalog/products/{id}право catalog:read
Товар

Заказы

GET/api/v1/ordersправо orders:read
Мои заказы и заказы подтверждённых организаций
Сначала новые.
POST/api/v1/ordersправо orders:write
Создать заказ (счёт выставит 1С)
Тот же сценарий, что на сайте: заказ сохраняется, счёт выставляется в 1С в очереди (обычно до минуты). Нужен заголовок Idempotency-Key: повтор с тем же ключом вернёт тот же заказ (200, Idempotent-Replayed: true). Организация — только с подтверждённой связью. Включается по запросу (иначе 403 orders-disabled).
GET/api/v1/orders/{id}право orders:read
Заказ

Счета

GET/api/v1/invoicesправо invoices:read
Счета по моим заказам
GET/api/v1/invoices/{id}право invoices:read
Счёт
GET/api/v1/invoices/{id}/pdfправо invoices:read
PDF счёта

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

Списки отдаются страницами: ?limit=20 (до 100). В ответе — meta.next_cursor; следующая страница — ?cursor=…. Когда курсор равен null, данные закончились.

{ "data": [ … ], "meta": { "per_page": 20, "next_cursor": "eyJpZCI6…", "prev_cursor": null } }

Создание заказа и идемпотентность

POST /orders требует заголовок Idempotency-Key — новый UUID на каждый заказ. Если связь оборвалась, повторите запрос с тем же ключом: вернётся уже созданный заказ (заголовок Idempotent-Replayed: true), второго счёта не будет.

curl -X POST https://sdc-polet.ru/api/v1/orders \
  -H "Authorization: Bearer polet_…" \
  -H "Idempotency-Key: 6f1c2b8e-3d4a-4b5c-9e7f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{"inn":"7701234567","product_ids":[12,15]}'

Счёт выставляется в 1С в течение минуты: статус меняется с processing на invoiced. Следите за ним через GET /orders/{id} или вебхук invoice.issued. Создание заказов через API включается по запросу — напишите нам.

Ошибки

Ошибки приходят в формате application/problem+json (RFC 9457). Поле code — машинный код, detail — пояснение по-русски, при ошибках полей — errors.

{ "type": "https://sdc-polet.ru/api/docs/#errors-missing-scope", "title": "Недостаточно прав",
  "status": 403, "code": "missing-scope", "detail": "У токена нет права: orders:write." }

401 unauthenticated — нет токена, он отозван или истёк;
403 missing-scope, organization-not-confirmed, orders-disabled;
404 not-found, pdf-not-ready; 409 idempotency-key-reused; 422 validation-failed, products-unavailable;
429 rate-limited — подождите столько секунд, сколько указано в Retry-After.

Вебхуки

По запросу мы отправляем на ваш https-адрес события order.created и invoice.issued. Тело — JSON с полями id, event, created_at и data.order (как в GET /orders/{id}). Ответьте кодом 2xx в течение 10 секунд, иначе отправим повторно: через 1, 5, 15 минут, 1 и 3 часа.

Проверяйте подпись: заголовок X-Polet-Signature: t=<время>,v1=<подпись>, где подпись — HMAC-SHA256 строки «t.тело» на вашем секрете. Отклоняйте запросы старше 5 минут и повторы по X-Polet-Delivery.

// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_X_POLET_SIGNATURE'], 't=%d,v1=%s');
$ok = abs(time() - $t) < 300
   && hash_equals(hash_hmac('sha256', $t.'.'.file_get_contents('php://input'), $secret), $v1);