Connector API v1

Это обзор для разработчиков магазина. Полную спецификацию с примерами всех запросов и ответов пришлём после заявки на подключение.

Общее

• Базовый адрес задаёте вы в кабинете, например https://api.shop.ru/integrations/ai; все пути — относительно него.
• JSON в UTF-8. Даты — ISO 8601 в UTC.
• Деньги — целые числа в минимальных единицах (копейках) плюс currency, например "price": 1249000, "currency": "RUB" — это 12 490 ₽.
• Таймауты со стороны Torgo: чтение — 5 с, создание заказа — 15 с. При 5xx и таймауте запрос повторяется до 2 раз, поэтому все изменяющие запросы должны быть идемпотентными.
• Чего магазин не умеет — отметьте в features ответа /v1/capabilities или верните 501 NOT_SUPPORTED.

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

Каждый запрос Torgo к магазину содержит ключ, время и подпись тела:

Authorization: Bearer <api_key>        ключ, который магазин выдал Torgo
X-AI-Timestamp: 1792575433             unix-время, допуск ±300 с
X-AI-Signature: sha256=<hex>           HMAC-SHA256(signing_secret, timestamp + "." + body)
X-AI-Request-Id: <uuid>                для логов и поддержки

Магазин проверяет ключ, время и подпись. Для GET-запросов тело — пустая строка. Пример проверки на Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, timestamp, signature, signingSecret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "sha256=" +
    createHmac("sha256", signingSecret).update(`${timestamp}.${rawBody}`).digest("hex");
  return signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Ошибки

Ошибка — HTTP-статус и тело единого вида:

{ "error": { "code": "OUT_OF_STOCK", "message": "Размер 44 закончился", "details": {} } }

Методы

Метка features.* означает, что метод нужен, только если магазин объявил эту возможность в /v1/capabilities.

• GET/v1/capabilities

  Что умеет магазин и его правила: сроки отправки, возврат, часы поддержки, способы оплаты, ссылки на документы. Вызывается при подключении и раз в час; правила попадают в инструкции ассистента.

• GET/v1/categories

  Дерево категорий каталога.

• GET/v1/products/search

  Поиск опубликованных товаров: q, categoryId, attr[size]=44, attr[color]=…, priceMin/priceMax, inStock, limit ≤ 20, cursor.

• GET/v1/products/{id}

  Карточка: описание, атрибуты (состав, посадка, уход), варианты с доступным остатком, размерная сетка.

• POST/v1/delivery/optionsfeatures.deliveryOptions

  Способы и стоимость доставки для города и состава корзины: pickup_point, courier или store_pickup.

• POST/v1/delivery/pickup-pointsfeatures.pickupPoints

  Пункты выдачи рядом с адресом покупателя.

• POST/v1/ordersfeatures.orders

  Создать заказ — только после явного подтверждения итоговой сводки покупателем. Возвращает номер, суммы, срок резерва и ссылку на оплату.

• POST/v1/orders/{id}/payment-linkfeatures.paymentLink

  Новая ссылка на оплату, если старая истекла, и доступные способы (card, sbp).

• GET/v1/orders/{id}

  Статус заказа и оплаты, трек-номер.

• POST/v1/orders/{id}/cancelfeatures.orderCancel

  Отмена заказа.

• GET/v1/customers/lookupfeatures.customerLookup

  Покупатель по телефону: имя и последние заказы — только то, что нужно для консультации, без адресов и платёжных данных.

Правила заказа

• POST /v1/orders вызывается только после того, как покупатель явно подтвердил итоговую сводку.
• Запрос содержит idempotencyKey: повтор с тем же ключом возвращает тот же заказ, а не создаёт новый.
• Для каждой позиции передаётся expectedPrice. Если цена изменилась — магазин отвечает 409 PRICE_CHANGED, ассистент называет новую цену и просит подтвердить заново. Изменить цену или дать скидку ассистент не может.
• Магазин находит или создаёт покупателя по телефону, резервирует товар и помечает заказ источником «ИИ-менеджер» с указанием канала.
• Для Авито заказ не создаётся: покупка проходит через «Авито Доставку» по правилам площадки.

// ответ 201
{
  "id": "o_555", "number": "SHOP-000123", "status": "awaiting_payment",
  "totals": { "items": 1249000, "delivery": 42000, "discount": 0, "total": 1291000, "currency": "RUB" },
  "reservedUntil": "2026-10-23T19:26:39Z",
  "paymentLink": { "url": "https://shop.ru/pay/…", "expiresAt": "2026-10-23T19:26:39Z" }
}

Статусы заказа: awaiting_payment, paid, processing, shipped, delivered, cancelled, returned.

Вебхуки магазин → Torgo

Адрес для вебхуков выдаётся в кабинете. Подпись — заголовки X-Store-Timestamp и X-Store-Signature: sha256=HMAC(webhook_secret, timestamp + "." + body). Torgo отвечает 2xx; иначе магазин повторяет отправку через 1 мин, 5 мин, 30 мин и 2 ч.

{ "id": "evt_…", "type": "order.paid", "createdAt": "…", "data": { "orderId": "o_555", "number": "SHOP-000123" } }

Проверка подключения

В кабинете есть кнопка «Проверить». Она по шагам проходит:

1. /v1/capabilities — контракт и возможности магазина;
2. поиск одного товара и открытие его карточки;
3. расчёт доставки в тестовый город;
4. по желанию — тестовый заказ, который магазин сразу отменяет.

Результат каждого шага виден в кабинете — можно исправлять по одному.