1. Составление прайс-листа в XML-формате

XML Schema Definition (XSD) — это файл, который задаёт структуру и правила оформления XML-прайс-листа. Он определяет, какие элементы должны быть в документе, какие из них обязательны, какие — опциональны, а также типы данных (например, число, строка, логическое значение).

С помощью XSD система Halyk Market проверяет правильность заполнения XML перед загрузкой. Это позволяет убедиться, что файл содержит все необходимые поля (например, артикул, цену, остаток, склад, доставку) и что данные соответствуют установленному формату.

Если структура XML не соответствует XSD-схеме, загрузка файла не произойдёт — система укажет ошибки для исправления.

Таким образом, XSD обеспечивает валидацию и корректность данных при интеграции прайс-листа через API.

XML Schema Definition (XSD) для валидации файла прайс-листа

<?xml version="1.0" encoding="UTF-8"?>
<!-- edited with XMLSpy v2014 rel. 2 sp1 (x64) (http://www.altova.com) by Daniel Brodkorb (mgm technology partners gmbh) -->
<!-- W3C Schema generated by XMLSpy v2014 rel. 2 sp1 (x64) (http://www.altova.com) -->
<xs:schema xmlns="halyk_market" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="halyk_market">
    <xs:element name="merchant_offers">
        <xs:complexType>
          <xs:choice minOccurs="0" maxOccurs="unbounded">
                <xs:element ref="company"/>
                <xs:element ref="merchantid"/>
                <xs:element ref="brand" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="offers"/>
             </xs:choice>
            <xs:attribute name="date" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="company" type="xs:string"/>
    <xs:element name="merchantid" type="xs:string"/> <!-- should be Seller BIN -->
    <xs:element name="brand" type="xs:string"/>

    <!--     <xs:simpleType name="nzString">
            <xs:restriction base="xs:string">
                <xs:minLength value="1"/>
            </xs:restriction>
        </xs:simpleType>
     -->
    <xs:element name="offers">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="offer" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="offer">
        <xs:annotation>
            <xs:documentation>Details of Merchant's offer</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice minOccurs="0" maxOccurs="unbounded">
                <xs:element ref="model" minOccurs="1" maxOccurs="1"/>
                <xs:element ref="brand" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="barcodes" minOccurs="0"/>
                <xs:element ref="stocks" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="deliveryOptions" minOccurs="0" maxOccurs="1"/>
                <xs:choice>
                    <xs:element ref="price" minOccurs="1" maxOccurs="1"/>
                    <xs:element ref="cityprices" minOccurs="1" maxOccurs="1"/>
                </xs:choice>
                <xs:element ref="loanPeriod" minOccurs="1" maxOccurs="1"/>
            </xs:choice>
            <xs:attribute name="sku" type="Sku" use="required"/>                        <!-- Merchant warehouse's product-ID, Article-No -->
            <xs:attribute name="stockLevel" type="xs:positiveInteger" use="optional"/>           <!-- number of goods in total, should not be used if stockLevel specified inside any of availability-element -->
        </xs:complexType>
    </xs:element>

    <xs:element name="model" type="xs:string"/>

    <xs:element name="stocks">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="stock" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="barcodes">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="barcode" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="barcode" type="xs:string"/>

    <xs:element name="loanPeriod" type="xs:string"/>

    <xs:element name="stock">
        <xs:complexType>
            <xs:attribute name="storeId" type="xs:string" use="required"/>                    <!-- Store string-ID -->
            <xs:attribute name="isPP" type="YesNo" use="optional"/>                           <!-- "yes" / "no", if not specified  -->
            <xs:attribute name="available" type="YesNo" use="required"/>                      <!-- "yes" / "no"  -->
            <xs:attribute name="preOrder" type="xs:unsignedLong" use="optional"/>             <!-- days for pre-order -->
            <xs:attribute name="stockLevel" type="xs:unsignedLong" use="optional"/>           <!-- number of goods in this store, if used - should be specified for each of element in sequence -->
        </xs:complexType>
    </xs:element>

    <xs:element name="deliveryOptions">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="deliveryOption" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute name="deliverable" type="YesNo" use="optional"/>                <!-- Deliverable by courier? "yes" / "no"  -->
        </xs:complexType>
    </xs:element>

    <xs:element name="deliveryOption">
        <xs:complexType>
            <xs:attribute name="city" type="xs:string" use="required"/>
            <xs:attribute name="cityId" type="xs:string" use="optional"/>                     <!-- City KATO ID -->
            <xs:attribute name="priceToDoor" type="xs:unsignedLong" use="optional"/>
            <xs:attribute name="priceToPP" type="xs:unsignedLong" use="optional"/>
            <xs:attribute name="timeToDoor" type="xs:unsignedLong" use="optional"/>           <!-- max time in days -->
            <xs:attribute name="timeToPP" type="xs:unsignedLong" use="optional"/>             <!-- max time in days -->
        </xs:complexType>
    </xs:element>

    <xs:element name="price">
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base="ST_price">
                    <xs:attribute name="oldprice" type="xs:unsignedLong" use="optional" />
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>

    <xs:element name="cityprices">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="cityprice" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="cityprice">
        <xs:complexType>
            <xs:simpleContent>
                <xs:extension base="ST_price">
                    <xs:attribute name="cityId" type="xs:string" use="required"/>
                    <xs:attribute name="oldprice" type="xs:unsignedLong" use="optional"/>
                </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
    </xs:element>

    <xs:simpleType name="ST_price">
        <xs:restriction base="xs:unsignedLong"/>
    </xs:simpleType>
    <xs:simpleType name="Sku">
        <xs:restriction base="xs:string">
            <xs:maxLength value="20" />
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="YesNo">
        <xs:restriction base="xs:string">
            <xs:enumeration value="yes"/>
            <xs:enumeration value="no"/>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

Пример файла прайс-листа в XML-формате

Описание элементов документа (M) — Mandatory — обязательное (O) — Optional — необязательное (R) — Reserved — зарезервировано (будет реализовано позднее, сейчас значение игнорируется)

Основные элементы

Элемент

Тип

Описание

<company>

(M)

Наименование компании

<merchantid>

(M)

ID продавца (обычно БИН)

<brand>

(O)

Название бренда продавца (используется, если один продавец имеет несколько брендов)

<offers>

(M)

Список товаров, продаваемых мерчантом. Каждый товар описывается отдельным элементом <offer>

Элемент <offer>

Содержит описание одного товарного предложения мерчанта: индефикацию товара, наличие, цены, условия доставки и рассрочки.

Атрибут / Элемент

Тип

Описание

sku

(M)

Артикул (идентификатор) товара в складской системе мерчанта. Строка до 64 символов

stockLevel

(O)

Остаток товара на складе. Не использовать одновременно с stocks->stock. При заполнении остатки должны обновляться после продажи

<model>

(M)

Название продукта

<brand>

(O)

Производитель товара

<barcodes>

(O)(R)

Список баркодов. Каждый <barcode> содержит один баркод (цифры и латинские буквы)

Элемент <stocks>

Содержит список складов и/или пунктов выдачи, где товар доступен.

Атрибут / Элемент

Тип

Описание

storeId

(M)

Уникальный идентификатор склада или pickup point, соответствующий данным в панели продавца

isPP

(O)(R)

Является ли точка пунктом выдачи. Значения: yes / no

available

(M)

Доступность товара в этой точке. Значения: yes / no

stockLevel

(O)

Количество товара, доступное в данной точке (не использовать одновременно с общим stockLevel)

Ценообразование

Определяет стоимость товара — либо единую цену, либо цены по городам.

Элемент

Тип

Описание

<price>

(O)

Цена (с НДС), одинаковая для всех городов или при продаже только в одном городе. Не использовать вместе с <cityprices>

<cityprices>

(O)

Список цен по городам. Делает товар доступным только для указанных городов. Не использовать вместе с <price>

Внутри <cityprices>

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

Атрибут / Значение

Тип

Описание

cityId

(M)

ID города по классификатору КАТО

Значение элемента

(M)

Цена товара в указанном городе

Элемент <deliveryOptions>

Определаяет условия доставки товара для конкретного города.

Атрибут / Элемент

Тип

Описание

city

(M)

Название города доставки

cityId

(O)

КАТО-код города доставки

priceToDoor

(O)

Стоимость доставки клиенту по адресу

priceToPP

(O)(R)

Стоимость доставки до точки выдачи

timeToDoor

(O)(R)

Время доставки клиенту (в днях)

timeToPP

(O)(R)

Время доставки до точки выдачи (в днях)

Элемент <loanPeriod>

Определяет возможность покупки со всеми элементами

Тип

Описание

(M)

Максимальный срок рассрочки (в месяцах). Целое неотрицательное число

Требования к форматам значений

Поле

Требование

Цена

Не должна содержать пробелов, разделителей или дробной части

Цена

Состоит только из цифр, без символов валюты или других знаков

Требования к формату значений в прайс-листе

1. Цена не должна содержать пробелов и разделителей

2. Цена не должна содержать дробной части

3. Цена не должна содержать других символов, кроме цифр (в т. ч. символ валюты)

Замена символов в XML

Следующие символы, встречающиеся в текстовых значениях документа, должны быть экранированы (заменены на следующие заменяющие последовательности символов):

Символ

Код в XML (Entity)

"

&quot;

&

&amp;

>

&gt;

<

&lt;

'

&apos;

Файл должен передаваться в формате UTF-8

Населенные пункты, поддерживаемые в системе, и их коды (KATO)

КАТО-код

Населённый пункт / Регион

35363110

Abay (obl. Karaganda)

434430000

Aiteke-Bi

116630100

Akmol (Akmol. obl.)

273620100

Aksay

551610000

Aksu

515230100

Aksukent

471010000

Aktau

151010000

Aktobe

196837100

Alatau (Zhetigen)

194067200

Alga

750000000

Almaty

634820100

Altay

433220100

Aralsk

391610000

Arkalyk

113430100

Arshaly

514839300

Arys

710000000

Astana

314033100

Aisha-bibi (Zhamb. obl.)

113820100

Atbasar

515433100

Abay (Turk. obl.)

231010000

Atyrau

194033100

Avat (Alm. obl.)

633420100

Ayagoz

194043100

Baidibek-Bi

196847100

Baiserke (Alm. obl.)

194067100

Baiterek (Alm. obl.)

351610000

Balkhash

431910000

Baykonyr

473630100

Beineu

196235100

Belbulak

196243100

Besagash

595030100

Beskol

273230100

Chapaev (ZKO)

196630100

Chundzha

271033100

Derkul

235235100

Dossor

552210000

Ekibastuz

154823100

Emba

196255400

Enbekshi

194020100

Esik

475220100

Fort Shevchenko

634030100

Glubokoe

196249100

Guldala

234030100

Inderbor

195247100

Irgeli

195233400

Isaevo

154820100

Kandyagash

395030100

Karabalyk

196430100

Karabulak

196253400

Karabulak (Alm. obl.)

351010000

Karaganda

316220100

Karatau

113863600

Karazhar

195220100

Kaskelen

636230100

Kasyma Kaysenova

614030100

Kazygurt

612010000

Kentau

551043100

Kenzhekol

156020100

Khromtau

195233500

Kokozek

195247400

Koksay

116672100

Talapker

111010000

Kokshetau

191610000

Konaev

314851205

Korday

116651100

Kosshy

391010000

Kostanay

116645100

Koyandi

633851100

Krasniy Yar

315030100

Kulan

233620100

Kulsary

434423100

Kazalinsk

632210000

Kurchatov

234630100

Kurmangazy

474230100

Kuryk

431010000

Kyzylorda

615820100

Lenger

392010000

Lisakovsk

235230100

Makat

635430100

Ulken-Naryn

235630100

Makhambet

114020100

Makinsk

434663100

Toretam

595220000

Mamlutka

475030100

Mangystau

154630100

Martuk

315430100

Merke

196833100

Mukhametzhan Tuimebaeva

596630100

Novoishimskoe

635030100

Kokpekty

354820100

Karkaralinsk

196830100

Otegen-batyr

196253100

Panfilovo

551041100

Pavladarskoe

551010000

Pavlodar

591010000

Petropavlovsk

352035000

Zhairem

114820100

Esil

276253100

Podstepnoe

352100000

Priozersk

195253000

Raiymbek

156420100

Ridder

392410000

Rudniy

352210000

Saran

115633100

Akkol

156033100

Abay (Aktobe obl.)

196020100

Sarkand

515420100

Saryagash

313630100

Sarykemer

194630100

Saryozek

352310000

Satpayev

551010000

Semey

632810000

Shakhan

352800000

Shakhtinsk

156420000

Shalkar (Aktyubinskaya obl.)

616420100

Shardara

194083100

Shelek

474630100

Shetpe

117055900

Shieli

515630100

Sholakkorgan

316621100

Shu

117020100

Shuchinsk

511010000

Shymkent

111810000

Stepnogorsk

191010000

Taldykorgan

196220100

Talgar

311010000

Taraz

431047100

Tasboget

192610000

Tekeli

352410000

Temirtau

395430100

Tobyl

316630100

Tole bi (Zhambyl. obl.)

353285100

Topar

516030100

Turar Ryskulov

512610000

Turkestan

196245100

Tuzdybastau

271010000

Uralsk

636430100

Urjar

353641300

Usharal

195020100

Ushtobe

631010000

Ust-Kamenogorsk

194230100

Uzinagash

114620100

Yereimentau

271035000

Zachagansk

191633100

Zarechnoe

433630100

Zhalagash

354430100

Zhanaarka

434030100

Zhanakorgan

471810000

Zhanaozen

316020100

Zhanatas

634620100

Zaysan

196833200

Zhapek Batyr

195620100

Zharkent

474239000

Zhetibay

515420100

Zhetysay

351810000

Zhezkazgan

195237100

Zhibek Zholy (Alm. obl.)

394420100

Zhitikara

434630100

Zhosaly