Item.Upsert

Добавляет или полностью обновляет товары общего каталога кассы; возвращает локальные ID для работы с корзиной. Товар доступен всем интеграциям этой кассы.

Для авторизации передайте Bearer-токен интеграции в HTTP-заголовке. Подробнее — авторизация API.

Входные параметры

Передайте item_id, external_id либо оба поля. Без item_id новый external_id создаёт товар, а существующий обновляет тот же товар независимо от токена интеграции. По item_id обновляется существующий товар, включая созданный вручную; неизвестный ID возвращает 701001. Если указаны оба идентификатора, они должны соответствовать одному товару; новый внешний ключ можно назначить товару, у которого его ещё нет. Уже назначенный ключ не заменяется другим: для обновления передайте только item_id.

Старый external_id, который связан с несколькими товарами, без item_id возвращает 701003. Передайте оба поля, чтобы явно выбрать товар для общего ключа. Остальные товары сохраняются и доступны по своим item_id. Одинаковый ИКПУ не объединяет товары. Один товар нельзя обновить дважды в одном пакете, даже через разные идентификаторы. Все обязательные реквизиты товара передаются заново: это не частичное обновление. Удалённый товар при обновлении восстанавливается.

ИКПУ, упаковка, допустимая ставка НДС и период её действия проверяются так же, как при проверке чека. Переданное наименование сохраняется без замены названием из справочника ИКПУ; удаляются только пробелы по краям. Штрихкод может быть уточнён данными справочника; ставка 600 применяется принудительно, если её требует справочник. Признаки маркировки и ограничения оплаты определяются по ИКПУ. Маркировка конкретной единицы товара при создании справочника не требуется. При ошибке ни один товар из запроса не сохраняется.

ИКПУ и штрихкод в примере фиктивные: используйте действительные данные товара.

Пример запроса

Authorization: Bearer <integration-token>
Content-Type: application/json;charset=utf-8

{
    "jsonrpc": "2.0",
    "method": "Item.Upsert",
    "params": {
        "items": [
            {
                "external_id": "SKU-001",
                "name": "Тестовый товар",
                "barcode": "4780000000000",
                "icps": "00000000000000000",
                "price": 10000,
                "vat_value": 0,
                "owner_type": 0
            }
        ]
    },
    "id": 1
}

Обновление существующего товара по локальному ID (все обязательные реквизиты передаются заново):

{
    "jsonrpc": "2.0",
    "method": "Item.Upsert",
    "params": {
        "items": [
            {
                "item_id": 101,
                "name": "Тестовый товар 250 г",
                "barcode": "4780000000000",
                "icps": "00000000000000000",
                "price": 12000,
                "vat_value": 0,
                "owner_type": 0
            }
        ]
    },
    "id": 2
}

Выходные параметры

result.items содержит по одному результату на товар в исходном порядке: external_id, item_id, created (создан новый товар), фактические name, barcode, price, vat_value, icps, package_code (null при отсутствии упаковок).

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "items": [
            {
                "external_id": "SKU-001",
                "item_id": 101,
                "created": true,
                "name": "Тестовый товар",
                "barcode": "4780000000000",
                "price": 10000,
                "vat_value": 0,
                "icps": "00000000000000000",
                "package_code": null
            }
        ]
    },
    "ok": true,
    "id": 1
}

Ошибки: общие ошибки авторизации и формата; 701001 — товар с указанным item_id не найден; 701003 — поля товара, конфликт идентификаторов, неизвестная ставка/единица или неподходящая упаковка; 705511 — нет данных ИКПУ. При недоступности сервиса проверки возвращается соответствующая ошибка из перечня; товары не сохраняются.