Общая информация

API для продавцов Kaspi Магазина – программный интерфейс, который предназначен для получения информации о заказах, товарах и сопутствующих данных, поступивших через платформу Kaspi Магазина. Данный программный интерфейс соответствует спецификации JSON API. Спецификация описывает процесс взаимодействия клиент серверных систем, построенных на базе формата сообщений JSON и протокола передачи гипертекста (HTTP).

Авторизация

Подключиться к API могут только зарегистрированные пользователи Kaspi Магазина

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

Параметры рабочей среды

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

  • Accept – тип контента, соответствующий стандарту MIME. Данный заголовок должен соответствовать зарегистрированному значению application/json
  • Content-Type - тип тела запроса, соответствующий стандарту MIME. Данный заголовок должен соответствовать зарегистрированному значению text/plain
  • X-Auth-Token –токен авторизации. Уникальный идентификатор, позволяющий получить доступ к программному интерфейсу.

Адрес сервиса: https://kaspi.kz/shop/api/products

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

GET /shop/api/products/classification/categories/ HTTP/1.1

Host: kaspi.kz

Accept: application/json

X-Auth-Token: token

Варианты запросов

Получение категории

Описание

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

GET /shop/api/products/classification/categories HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
[
    {
        "code": "Master - GPS navigators",
        "title": "GPS навигаторы"
    },
    {
        "code": "Master - Head units",
        "title": "Автомагнитолы"
    },
    {
        "code": "Master - Car alarms",
        "title": "Автосигнализации"
    },
    {
        "code": "Master - Blenders",
        "title": "Блендеры"
    },
    {
        "code": "Master - Cooktops",
        "title": "Варочные поверхности"
    },
    {
        "code": "Master - Video cameras",
        "title": "Видеокамеры"
    },
    {
        "code": "Master - Videocards",
        "title": "Видеокарты"
    },
    {
        "code": "Master - DVRs",
        "title": "Видеорегистраторы"
    }
]

Атрибуты

code - код категории

title - наименование категории в Kaspi Магазине

Получение характеристик

Описание

По данному методу можно получить атрибуты характеристик по категориям. В ответе Вы получите список атрибутов, тип и обязательность заполнения.

GET /shop/api/products/classification/attributes?c=Master - Smartphones HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
[
    {
        "code": "Smartphones*Processor & Memory.smartphones*processor cores",
        "type": "enum",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*processor",
        "type": "string",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*processor clock speed",
        "type": "number",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*processor #combined",
        "type": "string",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*internal ram",
        "type": "number",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*internal memory size",
        "type": "number",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*memory slot",
        "type": "boolean",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*compatible memory cards",
        "type": "enum",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*maximum memory card size",
        "type": "enum",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Processor & Memory.smartphones*memory slot #combined",
        "type": "string",
        "multiValued": false,
        "mandatory": false
    },
    {
        "code": "Smartphones*Weight & dimensions.smartphones*width",
        "type": "number",
        "multiValued": false,
        "mandatory": false
    }
]

Параметры:

c - категория продукта. Обязательный параметр. Список наименовании категории можно получить по запросу на получение категории.


Атрибуты:
code - код характеристики

type - тип атрибута характеристик. Может содержать следующие данные:

  • boolean - подтверждение или отклонение данных атрибута
  • enum - значение из списка
  • string - текстовое значение
  • number - числовое значение

multiValued - возможность заполнять мультизначения, булевый тип.

mandatory - обязательность атрибута, булевое значение, указывает является ли обязательным атрибут.

Получение возможных значений для характеристик

Описание

Данный запрос возвращает возможные значения для характеристик по конкретной категории. В случае типа атрибута по Enum, в ответ получите список возможных значении.

GET /shop/api/products/classification/attribute/values?c=Master - Smartphones&a=Smartphones*Processor+%26+Memory.smartphones*processor+cores HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
[
    {
        "code": "1-ядерный",
        "name": "1-ядерный"
    },
    {
        "code": "2-х ядерный",
        "name": "2-х ядерный"
    },
    {
        "code": "3-х ядерный",
        "name": "3-х ядерный"
    },
    {
        "code": "4-х ядерный",
        "name": "4-х ядерный"
    },
    {
        "code": "8-ядерный",
        "name": "8-ядерный"
    }
]


Параметры:
c - Код категории. Обязательный параметр.

a - код характеристики. Обязательный параметр.

Внимание: Код характеристики в запросах должен соответствовать кодированию URL. Подробнее: https://www.w3schools.com/tags/ref_urlencode.ASP

Атрибуты:

code - код возможного значения

name - наименование возможного значения

Получение схемы JSON

Описание

По данному методу можно получить JSON схему

GET /shop/api/products/import/schema HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product attributes import scheme",
    "description": "Used to validate JSON documents with product attribute values and images.",
    "type": "array",
    "minItems": 1,
    "maxItems": 10000,
    "items": {
        "title": "Array of products",
        "description": "Contains individual products with their attributes and images.",
        "type": "object",
        "properties": {
            "sku": {
                "title": "SKU",
                "description": "Unique identifier used to find products in catalog.",
                "type": "string",
                "maxLength": 64,
                "minLength": 1,
                "example": "00167PVS"
            },
            "title": {
                "title": "Product title",
                "description": "Contains product title that would be shown on storefront, without category prefix (eg. Smartphone, Fridge etc.).",
                "type": "string",
                "maxLength": 1024,
                "minLength": 1,
                "example": "Sony Alpha A6100 Kit 16-50 мм OSS черный"
            },
            "brand": {
                "title": "Product brand",
                "description": "Contains product brand name that would be used in 'Brand' facet on product listing pages of storefront.",
                "type": "string",
                "maxLength": 256,
                "minLength": 1,
                "example": "Sony"
            },
            "category": {
                "title": "Category code",
                "description": "This code would be used to assign the product to a category. It also defines the scope of available attributes. Only leaf categories are accepted",
                "type": "string",
                "maxLength": 512,
                "minLength": 1,
                "example": "Master - Photo cameras",
                "pattern": "^Master - [a-zA-Z_\\s]+$"
            },
            "description": {
                "title": "Short product definition",
                "description": "Contains small product definition used on item page. Usually defaults to some major specs.",
                "type": "string",
                "maxLength": 1024,
                "minLength": 1,
                "example": "- тип: беззеркальная со сменной оптикой\n- число эффективных пикселов: 24 Мпикс\n- объектив в комплекте: да\n- диагональ жк-экрана: 3 дюйм\n- ручная настройка выдержки и диафрагмы: да"
            },
            "attributes": {
                "title": "List of attributes",
                "description": "Array of attributes available for the assigned category.",
                "type": "array",
                "minItems": 1,
                "maxItems": 256,
                "items": {
                    "title": "Individual attribute",
                    "description": "Contains data for individual attribute.",
                    "type": "object",
                    "properties": {
                        "code": {
                            "title": "Attribute code",
                            "description": "Identifies attribute within category. Unique inside category.",
                            "type": "string",
                            "maxLength": 256,
                            "minLength": 1,
                            "example": "Photo cameras*Camera matrix.photo cameras*type",
                            "pattern": "^([a-zA-Z_\\s&.-]+\\*)+[a-zA-Z_\\s&.-]+$"
                        },
                        "value": {
                            "title": "Attribute value",
                            "description": "Array could be used for multivalued attributes only.",
                            "example": [
                                "[\"зеркальный фотоаппарат (TTL)\", \"фотоаппарат с оптическим видоискателем\"]",
                                "\"6000x4000\"",
                                "24"
                            ],
                            "oneOf": [
                                {
                                    "type": "array",
                                    "minItems": 1,
                                    "maxItems": 32,
                                    "uniqueItems": true,
                                    "items": {
                                        "type": "string",
                                        "maxLength": 256,
                                        "minLength": 1
                                    }
                                },
                                {
                                    "type": "string",
                                    "maxLength": 256,
                                    "minLength": 1
                                },
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "boolean"
                                }
                            ]
                        }
                    },
                    "required": [
                        "code",
                        "value"
                    ],
                    "additionalProperties": false
                }
            },
            "images": {
                "title": "Product images",
                "description": "Must contain at least one valid image url. Valid means downloadable and having valid picture as content. Redirects are supported.",
                "type": "array",
                "minItems": 1,
                "maxItems": 5,
                "uniqueItems": true,
                "items": {
                    "type": "object",
                    "properties": {
                        "url": {
                            "title": "Image url",
                            "description": "Individual image url.",
                            "type": "string",
                            "maxLength": 1024,
                            "minLength": 1,
                            "format": "uri",
                            "pattern": "^https?://",
                            "example": "https://cdn-kaspi.kz/shop/medias/sys_master/images/images/h5d/h37/16008607399966/sony-alpha-a6600-kit-16-50mm-cernyj-100692376-1.jpg"
                        }
                    },
                    "required": [
                        "url"
                    ],
                    "additionalProperties": false
                }
            }
        },
        "required": [
            "sku",
            "title",
            "brand",
            "category",
            "attributes",
            "images"
        ],
        "additionalProperties": false
    }
}


Загрузка характеристик

Описание

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

Заголовки

Accept: application/json

X-Auth-Token: token

Content-Type: text/plain

Параметры

sku - Артикул товара, который используется в Вашей системе. Обязательный параметр
title - Наименование товара в вашей системе. Обязательный параметр
brand - Бренд
category - Категория товара(code категории). Обязательный параметр
description - описание к загрузке
images - фотографии товара, должны быть загружены ссылки. Каждая ссылка на картинку указывается ключом url. Обязательный параметр

Атрибуты
code - Код характеристики товара. Обязательный атрибут

value - заполненное значение в зависимости от типа. Обязательный атрибут

POST /shop/api/products/import HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
Content-Type: text/plain

//body

[

  {

    "sku": "000001",
    "title": "Apple iPhone 12 Pro Max 128GB черный",
    "brand": "Apple",
    "category": "Master - Smartphones",
    "description": "Some description",
    "attributes": [
      {
        "code": "Smartphones*Processor & Memory.smartphones*processor",
        "value": "Apple A14 Bionic"
      },
      {

        "code": "Smartphones*Weight & dimensions.smartphones*height",
        "value": 160.8
      },
      {
        "code": "Smartphones*Weight & dimensions.smartphones*weight",
        "value": "226"
      }
         ],
    "images": [
      {
        "url": "https://imageadress.kz/iphone1.png"
      },
      {
        "url": "https://imageadress.kz/iphone2.png"
      },
      {
        "url": "https://imageadress.kz/iphone3.png"
      }
    ]
  },
  {
    "sku": "00168PVS",
    "title": "Sony Alpha ILCE-6400 Body черный",
    "brand": "Sony",
    "category": "Master - Photo cameras",
    "attributes": [
      {
        "code": "Photo cameras*Camera matrix.photo cameras*type",
        "value": "зеркальный фотоаппарат (TTL)"
      },
      {
        "code": "Photo cameras*Camera matrix.photo cameras*number of effective pixels",
        "value": 32
      },
      {

        "code": "Photo cameras*Camera matrix.photo cameras*matrix physical size",
        "value": "36 мм (36 x 24 мм)"
      },
      {
        "code": "Photo cameras*Camera matrix.photo cameras*maximum photo resolution",
        "value": "6100x4000"
      },
      {
        "code": "Photo cameras*Camera matrix.photo cameras*bit depth",
        "value": "18 бит/пиксел"
      }
    ],
    "images": [
      {
        "url": "https://newimage.kz/sony1.png"
      },
      {
        "url": "https://newimage.kz/sony2.png"
      },
      {
        "url": "https://newimage.kz/sony3.png"
      }
    ]
  }
]

{
    "code": "0000001",
    "status": "UPLOADED"
}

Получение статуса обработки

Описание

По данному методу, Вы можете получить статус обработки по ранее загруженным описаниям

GET /shop/api/products/import?i=000001 HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
{
    "code": "000001",
    "status": "FINISHED"
}


Параметры

i - код загрузки описания. Обязательный параметр.

Атрибуты:

code - код загрузки описания

status - статус загрузки описания

description - описание

Получение результата обработки

Описание

Данный запрос возвращает детальный результат обработки.

GET /shop/api/products/import/result?i=000001 HTTP/1.1
Host: kaspi.kz
Accept: application/json
X-Auth-Token: token
{
    "errors": 0,
    "warnings": 0,
    "skipped": 0,
    "total": 1,
    "result": {
        "000001": {
            "state": "FINISHED"
        }
    }
}

Параметры:

i - код загрузки описания для получения результата загрузки. Обязательный параметр.

Атрибуты:
errors - количество предложении с ошибками

warnings - количество предложении с предупреждениями

skipped - количество пропущенных предложении

total - общее количество загруженных предложении

state - состояние по загруженному описанию

  • No labels