# Техническая спецификация интеграции с ритейлерами: «ВТарелке» ⇄ Ритейл (X5, Купер, ВкусВилл, Лавка, Магнит) > **Статус документа:** Обязательное техническое приложение к B2B-соглашениям с продуктовыми сетями и агрегаторами доставок. > **Назначение:** Четкий перечень технологий, API-методов, шлюзов и форматов данных, которые сервис «ВТарелке» запрашивает у IT-команд ритейлеров. --- ## 1. Архитектурная модель взаимодействия Интеграция разделена на **4 независимых технологических уровня** (от моментального старта по Deep Link до прямого серверного API): ```text ┌─────────────────────────────────────────────────────────────────────────────┐ │ МОБИЛЬНОЕ ПРИЛОЖЕНИЕ «ВТАРЕЛКЕ» │ │ (AI-генератор рациона + Корзина на 5-7 дней + Детерминированный движок) │ └──────────────────────────────────────┬──────────────────────────────────────┘ │ ┌──────────────────────┴──────────────────────┐ ▼ ▼ [УРОВЕНЬ 1: Клиентский мост] [УРОВЕНЬ 2: Серверный REST API] • Universal Links / Deep Links • Geo Store Resolver (lat/lon) • Webview Bridge • Batch Price & Stock Revalidation • Пакетная передача SKU • Product Metadata & Weight Steps │ │ └──────────────────────┬──────────────────────┘ │ ▼ [УРОВЕНЬ 3: B2B Cart & Checkout API] • Серверная сборка корзины (Server-to-Server) • Применение партнерского промокода • Генерация защищенного токена чекаута │ ▼ [УРОВЕНЬ 4: Postback & Webhook Gateway] • События: Заказ создан / Оплачен / Доставлен • Автоматический перенос продуктов в Кладовку • Атрибуция CPA-вознаграждения (RevShare) ``` --- ## 2. Уровень 1: Шлюз сквозного переноса корзины (Deep Link / Universal Link) *Срок внедрения: 1–2 дня. Не требует изменений на бэкенде ритейлера, если у сети уже есть поддержка ссылок на корзину.* ### Что мы просим у ритейлера: Спецификацию формата **Universal Link (iOS) / App Link (Android)** или кастомной схемы URL для открытия нативного мобильного приложения доставки с предсобранным списком товаров. ### Формат данных: ```http GET https://delivery.retailer.ru/cart/add-batch?items=SKU1:QTY1,SKU2:QTY2&utm_source=vtarelke&sub_id={CLICK_ID}&promo={PARTNER_PROMO} ``` * **Параметры:** * `items` — массив пар `Идентификатор_товара:Количество` (или вес в граммах для весовых товаров); * `utm_source=vtarelke` — метка источника трафика; * `sub_id` — уникальный `click_id` нашего сервиса для сквозной склейки заказа; * `promo` — выделенный промокод на первый/повторный заказ для пользователей «ВТарелке». --- ## 3. Уровень 2: API актуализации каталога, цен и стоков (Inventory & Pricing API) *Назначение: Реализация принципа Local Truth vs Live Truth — перед отправкой пользователя на чекаут наш бэкенд за 100 мс проверяет актуальность цен и наличие товаров на конкретном складе/дарксторе.* ### Что мы просим у ритейлера: #### 3.1. Определение магазина по геолокации (`Geo Store Resolver`): * **Эндпоинт:** `POST /api/v1/geo/resolve-store` * **Вход:** `{ "latitude": 55.7558, "longitude": 37.6173 }` или адрес строкой. * **Выход:** `{ "store_id": "x5_darkstore_1488", "delivery_eta_min": 30, "min_order_rub": 1000 }`. #### 3.2. Пакетная валидация цен и остатков (`Batch Stock Revalidation`): * **Эндпоинт:** `POST /api/v1/stores/{store_id}/inventory/check` * **Входной JSON:** ```json { "store_id": "darkstore_1488", "items": [ { "sku": "4601234567890", "quantity": 1 }, { "sku": "2901234000000", "weight_g": 800 } ] } ``` * **Ответ ритейлера:** ```json { "status": "ok", "items": [ { "sku": "4601234567890", "available": true, "price_rub": 119.99, "discount_price_rub": 99.99, "stock_quantity": 42 }, { "sku": "2901234000000", "available": false, "reason": "OUT_OF_STOCK", "suggested_substitute_sku": "2901234000001" } ], "total_cart_price_rub": 99.99 } ``` #### 3.3. Метаданные весовых товаров: * Передача признака весового товара (`is_weighted: true`), шага фасовки (`step_g`: 100г, `min_weight_g`: 300г, `max_weight_g`: 2000г) для точного расчета Decimal-арифметики в рецептах. --- ## 4. Уровень 3: Прямой B2B Cart & Checkout API (Server-to-Server) *Назначение: Бесшовное создание корзины без перенаправлений через внешние браузеры.* ### Что мы просим у ритейлера: 1. **API-ключ партнера (B2B API Token)** с правами на создание и наполнение гостевых / пользовательских корзин; 2. **Метод создания корзины:** `POST /partner/v1/cart/create`; 3. **Метод пакетного наполнения:** `POST /partner/v1/cart/{cart_id}/items`; 4. **Метод применения промокода:** `POST /partner/v1/cart/{cart_id}/apply-promo`; 5. **Метод генерации Webview / Checkout URL:** `GET /partner/v1/cart/{cart_id}/checkout-url` — возвращает одноразовую безопасную ссылку, где пользователь сразу попадает на экран выбора времени доставки и оплаты. --- ## 5. Уровень 4: Шлюз уведомлений и постбэков (Webhooks / Postbacks) *Назначение: Автоматизация жизненного цикла продуктов и учет партнерской комиссии.* ### Что мы просим у ритейлера: Отправку Webhook-уведомлений на наш сервер `https://api.vtarelkeapp.ru/api/v1/webhooks/partner/{partner_code}` при изменении статуса заказа, оформленного через «ВТарелке». ### Спецификация Webhook Payload: ```json { "event": "ORDER_DELIVERED", "event_id": "evt_99887766", "timestamp": "2026-09-15T14:30:00Z", "partner_order_id": "X5-9481920", "sub_id": "vtarelke_user_abc123_click_789", "order_status": "DELIVERED", "cart_total_rub": 3840.50, "cpa_commission_rub": 115.20, "is_first_order": false, "items": [ { "sku": "4601234567890", "name": "Творог 5% Простоквашино", "quantity": 2, "price_rub": 109.90 }, { "sku": "2901234000000", "name": "Филе грудки индейки", "weight_g": 750, "price_rub": 340.00 } ] } ``` ### Что делает «ВТарелке» по этому событию: 1. **Событие `ORDER_DELIVERED`:** Приложение автоматически добавляет доставленные продукты в виртуальную **«Кладовку» (Pantry)** пользователя, выставляет реальные сроки годности и активирует алгоритм Zero-Waste спасения продуктов. 2. **Событие `ORDER_CANCELLED`:** Снимает отметку о покупке и возвращает пользователю напоминание о необходимости заказа ингредиентов на неделю. --- ## 6. Требования к тестовой среде (Sandbox / Staging) Для проведения закрытого тестирования до выката в прод нам требуются: 1. Доступ к **Sandbox API (Песочнице)** или тестовый контур с mock-складом; 2. Список из 20–30 тестовых SKU базовой продуктовой корзины (молоко, яйца, мясо, крупы, овощи); 3. Тестовый промокод со скидкой 99% для контрольных прогонов курьерской логистики разработчиками.