Merchant API AgentPay · инструкция для магазина

1. Отдайте HTTPS-фид в кабинете

/business → создайте магазин, коннектор Webhook / JSON.
Вставьте URL полного фида. Нажмите «Проверить фид», затем «Сохранить фид».
Укажите роль полей: описание, анализ, отзывы.

В каждом оффере укажите стабильный id (не меняйте его между выгрузками), название, цену числом, наличие (available или inStock), картинку HTTPS без cookie.

Укажите sku как артикул заказа, description или searchText от 8 символов, валюту RUB.

Отдайте полный снимок раз в сутки. Нет в фиде, нет в наличии. Дельту отдайте только по изменившимся позициям: id, inStock, price.

Не отдавайте http, localhost, паспорта покупателей и полный дамп отзывов с ФИО.

YML: обычный файл Яндекс.Маркета (yml_catalog / offer). XML без yml_catalog принимаем, если есть offer с id. JSON: объект products, как в карточке товара.

Пример YML

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2026-08-18">
  <shop>
    <offers>
      <offer id="milk-25-1l" available="true">
        <name>Молоко 2.5% 1л</name>
        <vendorCode>milk-25-1l</vendorCode>
        <price>89</price>
        <currencyId>RUB</currencyId>
        <picture>https://cdn.shop.example.ru/milk.jpg</picture>
        <description>молоко пастеризованное 2.5 процента</description>
        <vendor>Простоквашино</vendor>
        <param name="Жирность">2.5</param>
        <param name="rating">4.6</param>
        <param name="reviewsCount">12</param>
        <param name="reviewHighlights">Свежее|Нормальная цена</param>
      </offer>
    </offers>
  </shop>
</yml_catalog>

Пример JSON

{
  "products": [
    {
      "id": "milk-25-1l",
      "sku": "milk-25-1l",
      "title": "Молоко 2.5% 1л",
      "price": 89,
      "currency": "RUB",
      "imageUrls": ["https://cdn.shop.example.ru/milk.jpg"],
      "inStock": true,
      "description": "молоко пастеризованное 2.5 процента",
      "attributes": { "brand": "Простоквашино", "fatPercent": "2.5" },
      "rating": 4.6,
      "reviewsCount": 12,
      "reviewHighlights": ["Свежее", "Нормальная цена"]
    }
  ]
}

Реквизиты из кабинета

Webhook URL заказа — ваш HTTPS, например https://shop.example.ru/hooks/agentpay.
Запомните: mk_…, UUID магазина, HMAC-секрет вебхука.

2. Загрузить каталог вручную (если фида нет)

POST {API}/merchant/catalog/upsert

Заголовок:

Authorization: Bearer mk_ВАШ_КЛЮЧ
Content-Type: application/json

Тело (пример, 2 позиции, до 500 за запрос):

{
  "storeId": "0d9ce8c7-a3a1-4b01-ac7a-ec28bcdc8f28",
  "replaceMissing": false,
  "products": [
    {
      "id": "milk-25-1l",
      "sku": "milk-25-1l",
      "title": "Молоко 2.5% 1л",
      "price": 89,
      "currency": "RUB",
      "imageUrls": ["https://cdn.shop.example.ru/milk.jpg"],
      "inStock": true,
      "category": "dairy",
      "attributes": { "brand": "Простоквашино", "fatPercent": "2.5" }
    }
  ]
}

Локально: http://localhost:3100/merchant/catalog/upsert. Скрипт пилота в репозитории: node scripts/pilot-catalog.mjs с env MERCHANT_KEY и STORE_ID.

replaceMissing: true — товары, которых нет в этой пачке, помечаются «нет в наличии», не удаляются.

Проверка: GET {API}/merchant/catalog/products с тем же Bearer — или таблица в /business.

Swagger и OpenAPI

Откройте интерактивный Swagger: /docs/swagger. Машиночитаемый YAML: /docs/openapi-merchant.yaml.

2. Принять заказ

AgentPay шлёт POST на ваш webhook URL:

POST https://shop.example.ru/hooks/agentpay
Content-Type: application/json
X-AgentPay-Signature: <hmac-sha256 hex тела, секрет магазина>

{
  "schemaVersion": 1,
  "event": "order.created",
  "order": {
    "externalId": "uuid-покупки-agentpay",
    "storeId": "uuid-магазина",
    "currency": "coins",
    "totalAmount": 89,
    "items": [
      { "sku": "milk-25-1l", "name": "Молоко 2.5% 1л", "quantity": 1, "unitPrice": 89 }
    ],
    "delivery": {
      "method": "courier",
      "phone": "+79776134508",
      "comment": "подъезд 4, этаж 10, домофон B204B8557",
      "address": {
        "city": "Москва",
        "street": "Петрозаводская",
        "house": "28к4",
        "apartment": "204",
        "entrance": "4",
        "floor": "10",
        "intercom": "B204B8557"
      }
    }
  }
}

Создайте заказ в своей CMS с этими полями доставки. Накладную СДЭК создаёт ваш модуль. API перевозчика AgentPay не вызывает. Ответьте 2xx и JSON { "ok": true, "externalOrderId": "ваш-номер-заказа" }. Иначе AgentPay повторит запрос и может вернуть коины покупателю.

3. Подключите аккаунт покупателя у партнёра

Если покупатель уже есть в вашей CRM/loyalty, добавьте OAuth/SSO-flow. Покупатель входит у вас и разрешает AgentPay читать историю заказов и лояльность. AgentPay хранит partnerCustomerId и зашифрованные токены, а историю тянет on-demand.

GET /oauth/authorize — покажите логин и consent.
POST /oauth/token — верните access_token и partner_customer_id.
GET /customers/{partnerCustomerId}/orders — отдайте последние заказы без телефона, email и адреса.
POST /oauth/revoke — отключите доступ по запросу покупателя.
В order.created примите order.partnerCustomer.partnerCustomerId и прикрепите заказ к тому же профилю.

Полное описание: docs/b2b/partner-account-link.md и раздел Partner-hosted account link в Swagger.

4. Верните статус (по желанию)

После списания коинов покупатель уже видит статус «оформлен». Вызов статуса необязателен. Когда магазин принял заказ или передал его покупателю, отправьте обновление.

POST {API}/merchant/orders/{uuid-покупки}/status
Authorization: Bearer mk_…
{
  "status": "fulfilled",
  "externalOrderId": "INS-10045",
  "message": "Передано курьеру",
  "trackingNumber": "1234567890",
  "deliveryEta": "сегодня до 18:00"
}

submitted: оформлен. confirmed: подтверждён магазином. fulfilled: доставлен. cancelled / failed: возврат коинов. Поля message, trackingNumber, deliveryEta необязательны.

Обязательные поля карточки

id, title, price, currency, imageUrls (можно пустой массив), inStock. SKU настоятельно рекомендуется — по нему собирается заказ.

Сайт на 1С-Битрикс: поставьте модуль, см. инструкцию 1С-Битрикс.

OpenAPI: /docs/openapi-merchant.yaml. Swagger: /docs/swagger. Поддержка: help@agentpay.shop. Все платформы.

Своя CMS: Merchant API