Описание API мерчантов
ОБЩИЕ СВЕДЕНИЯ
1. API мерчантов "располагается" по адресу:
http://377962.675tm.group/API/script_name.php
где script_name.php - название конкретного файла-интерфеса. К примеру:
http://377962.675tm.group/API/orders.php
http://377962.675tm.group/API/orders_process.php
2. При обращении к любому интерфейсу нет разницы, каким способом передаются данные,
GET или POST, если это не оговорено отдельно. Однако, в любом случае не стоит
передавать слишком длинные строки методом GET, и с этой т.з. POST предпочтительней.
3. При обращении к любому интерфейсу есть 2 обязательных параметра, которые необходимо
передавать ВСЕГДА. Помните об этом, т.к. в описании конкретных интерфейсов они повторно
упоминаться не будут, а будут упоминаться только специфические для данного интерфейса
параметры. Это следующие параметры:
api_id - ID товарной базы
api_key - специальный ключ (пароль) для данной базы, установленный нашими
администраторами
Пример: http://377962.675tm.group/API/orders.php?api_id=56&api_key=354dsg43652
4. Передаваемые параметры необходимо URL-кодировать (как имя параметра, так и его значение).
Параметры могут быть массивами. В этом случае в имени параметра присутствуют квадратные
скобки []. К примеру, так: status[43]=3, или так: order[]=214. В URL-кодированном виде
это будет выглядеть так status%5B43%5D=3, order%5B%5D=214.
5. При обращении к любому интерфейсу могут возникнуть ошибки. Таблица возможных ошибок
приведена снизу этой страницы. В случае возникновения ошибки
ВСЕГДА в ответе сервера будет строка вида:
error|error_id|error_name|error_data
Т.е. строка из 4-х полей, разделеннах символом | (вертикальная черта), где:
error - ключевое слово - признак ошибки
error_id - ID возникшей ошибки - целое число
error_name - название возникшей ошибки - строка
error_data - дополнительная информация об ошибке, у каждой ошибки может быть своя,
специфическая именно для нее, в специфическом для нее формате. Но, как правило, для большинства
ошибок (простых ошибок) она будет пустой, т.к. для них пояснения не требуются
Т.е. получив ответ от любого интерфейса всегда первым делом следует проверить, не ошибка ли это.
Если ошибки нет, то формат ответа зависит от конкретного интерфеса, но, как правило, это XML.
Вообще, интерфейсы условно разделяются на информационные (только отдающие информацию из
нашей базы) и управляющие (меняющие информацию на сервере). И если для вторых часто возможны
индивидуальные ошибки, то для первых, как правило, их не будет, т.к. некорректные
данные из запроса будут либо преобразованы к корректным значениям, либо взяты "как есть",
если это возможно. К примеру, если в запросе будет указан некорректный статус заказа для поиска
заказов по базе, то вы не получите ни одного заказа в ответе.
6. Некоторые интерфейсы предназначены для работы с заказами. У заказов есть
существенный атрибут "статус" (status), который кодируется целым числом.
Ознакомиться с табличкой статусов можно внизу данной страницы.
7. При описании XML используются следующие обозначения:
- Если название параметра приводится в угловых скобках <field_name>, то значит
данный параметр в XML представлен в виде вложенного элемента.
- Если название параметра приводится без угловых скобок, т.е. в виде
field_name, то данный параметр в XML представлен в виде атрибута у элемента.
- Если параметр помечен звездочкой *, то он опционален, т.е. может
отсутствовать.
параметры, не помеченные звездочкой, присутствуют всегда, но, тем не менее,
некоторые из них могут быть пустыми.
8. Для передаваемых параметров квадратные скобки после названия параметра (status[]) означают,
что данный параметр - массив. Т.е. может быть передано много таких переменных. К примеру:
status[25]=3&status[35]=5&status[37]=3
Индекс массива (в скобках) не всегда обязателен, тогда передается так:
order[]=21&order[]=33&order[]=34
СПЕЦИФИКАЦИЯ API
1. Экспорт базы заказов (orders.php).
Чтобы получить выборку заказов вы должны вызвать файл:
orders.php
Параметры вызова (все необязательны):
start - целое число, позиция, начиная с которой возвращать результат
(нумерация начинается с 0). Т.е. если, к примеру, вашему запросу соответствует 20 заказов,
а вы передали start=10, то вам вернет 10 последних заказов
portion - целое число, количество заказов, которое возвращать.
Т.е. если, к примеру, вашему запросу соответствует 20 заказов, а вы передали portion=10,
то вам вернет 10 первых результатов. А если вы передали start=10 и portion=10,
то 10 последних.
Однако, пользуясь этими параметрами, помните, что система "живая", и пока вы тянете
информацию о какой-то порции, могут придти еще заказы. Так что не допускайте логических
ошибок.
Лучше при необходимости пользуйтесь парой параметров portion и min_id (который будет
описан ниже). Это удобно, так как результаты всегде сортируются в порядке возрастания ID заказа,
т.е. в данном случае min_id всегда может удобно заменить start.
end_time - целое число. unix timestamp. Время, до которого (включительно)
выбирать заказы. Если не указано, то все.
start_time - целое число. unix timestamp. Время, начиная с которого (включительно)
выбирать заказы. Если не указано, то все. Может быть ОТРИЦАТЕЛЬНЫМ. Тогда считается вниз от
end_time. К примеру, не указав end_time и указав start_time=-86400, вы получите заказы за последние
86400 секунд, т.е. за сутки.
id - ID конкретного заказа
min_id - минимальный ID заказа (включительно), который может попасть в выборку
max_id - максимальный ID заказа (включительно), который может попасть в выборку
email - емайл заказчика - точное соответсвие
name - имя заказчика. Поиск по началам shipping и billing first_name и last_name (т.е. в сумме по 4-м полям)
zip - зип-код. Поиск по началам shipping и billing zip-кодов (т.е. по 2-м полям)
status - ID статуса заказа (если не указан, то любой)
cc4 - 4 последних цифры кредитки - точное соответствие
testmode - 0-реальные заказы (по умолчанию), 1-тестовые заказы, 2-любые заказы
shipping_details - поиск по способу доставки (точное соответствие)
Возврат:
В ответе вам вернет в XML полную информацию о заказах, соответствующих запросу:
<orders> - внешний контейнер
count - число заказов в данном ответе
<order> - заказ (повторяется для каждого заказа)
ID - ID заказа
time - время заказа в виде UNIX_TIMESTAMP
time_str - время заказа в виде человекопонятной строки
price - полная цена заказа (включает продукты, налоги, доставку), заплаченная покупателем (т.е. с учетом скидки)
price_prd - цена только продуктов в заказе
price_tax - налоги
price_ship - стоимость доставки заказа
discount - полная скидка, полученная покупателем
discount_prd - часть скидки, пришедшаяся на продукты
discount_tax - часть скидки, пришедшаяся на налоги
discount_ship - часть скидки, пришедшаяся на стоимость доставки заказа
status - статус заказа - число
status_str - статус заказа - человекопонятное определение
boxes - количество коробок, в которых был отправлен заказ (это должен быть оооочень большой заказ, чтобы количество коробок превысило 1)
testmode - 1, если заказ тестовый
num_comments - число админских коментариев к данному заказу
<products> - список продуктов
quantity - количество продуктов в заказе
weight - общий вес продуктов в корзине
<product>* - продукт (для каждой позиции в заказе)
ID - ID продукта (продукты с атрибутами, если клались несколько раз, то будут повторяться)
Внимание! Если в заказе в конце присутсвует продукт с ID=100000000, то это не реальный продукт,
заказанный покупателем, а виртуальный, отображающий информацию о коррекции в заказе, сделанной продавцом
(например, в результате телефонного разговора с покупателем).
В таком случае в поле price записана сумма коррекции заказа (может быть положительной, нулевой и отрицательной),
а в поле name - описание коррекции (комментарий). Общие для заказа элементы price* (см. выше) учитывают этот товар,
т.е. отображают реальную сумму заказа с учетом коррекции. См. также элемент correction, отображающий
всю информацию о коррекции.
<name> - название
quantity - количество для данной позиции в заказе
weight - полный вес данной позиции в заказе (т.е. с учетом количества)
price_one_wo_attr* - стоимость одного продукта в этой позиции без учета стоимости атрибутов (если продукт имеет атрибуты)
price_one - стоимость одного продукта в этой позиции
price - стоимость позиции (т.е. с учетом количества)
tax* - сумма налога для данной позиции (если не 0)
price_full - полная стоимость позиции (с учетом налогов)
<attribute_configuration>* - список атрибутов продукта, выбранных заказчиком (только если продукт имеет атрибуты)
<attribute> - атрибут продукта, присутствует для каждого атрибута, выбранного заказчиком -
т.е. атрибуты типа Optional и Multiple без выбранных опций и незаполненные атрибуты типа Text здесь не приводятся
code - код атрибута
value - значение атрибута - код выбранной опции для атрибутов типа Required и Optional,
коды всех выбранных опций через запятую для арибутов типа Multiple
и значение, введенное заказчиком, для атрибутов типа Text
<attributes> - строка с перечислением выбранных опций для атрибутов в человеко-читаемом виде (только если продукт имеет атрибуты)
<model> - модель продукта
<correction>* - информация о коррекции заказа, присутствует только если коррекция имела место
time - время последнего именения коррекции в виде UNIX_TIMESTAMP
time_str - время последнего именения коррекции в виде человекопонятной строки
admin* - username админа, внесшего последние изменения в коррекцию
(может отстутствовать, например, если коррекция менялась через API)
amount - сумма коррекции заказа (может быть отрицательной)
<description> - описание коррекции
<email> - email заказчика
<comment> - комментарий заказчика к заказу
<shipping_details> - выбранный вид доставки (строка в человекочитаемом виде)
<payment_details> - детали произведенной оплаты (строка в человекочитаемом виде)
<shipping_info> - шиппинг-информация для заказа (которая писалась админами)
<site_url> - урл партнерского сайта, с которого был сделан заказ
<site_name> - название партнерского сайта, с которого был сделан заказ
<shipping_address> - адрес доставки
<first_name> - first name
<last_name> - last name
<company> - company name
<address1> - address line 1
<address2> - address line 2
<city> - city
<state> - state/province (полное название)
<zip> - zip/postal code
<country> - country (полное название)
<tel> - telephone
<fax> - fax
<billing_address> - биллинг-адрес покупателя (плательщика)
<first_name> - first name
<last_name> - last name
<company> - company name
<address1> - address line 1
<address2> - address line 2
<city> - city
<state> - state/province (полное название)
<zip> - zip/postal code
<country> - country (полное название)
<tel> - telephone
<fax> - fax
2. Смена статусов заказов и их информации о доставке (orders_process.php).
Чтобы сменить статус заказов и их информацию о доставке, вы должны вызвать файл:
orders_process.php
Параметры вызова:
status[] - массив статусов, которые следует уставновить заказам.
Индекс в массиве - ID заказа, значение - статус, которые необходимо установить данному заказу.
Например: status[44]=2&status[45]=3
shipping_info[] - массив информации о доставке, которую следует уставновить заказам.
Индекс в массиве - ID заказа, значение - информация (строка, может быть пустой), которую
необходимо установить данному заказу.
shipping_info_mail - установить в 1, если информацию о доставке (только не пустую)
следует разослать заказчикам
Хотя бы один из параметров status и shipping_info обязан присутствовать!
Возврат:
В ответе, если не возникло ошибки (для данного интерфейса возможны специфические ошибки),
вам вернет в XML информацию об операции:
<orders> - внешний контейнер
<orders_wrong> - перечисленные через запятую ошибочные ID заказов
из вашего запроса - т.е. из ключей массивов status и shipping_info
(к примеру, если такого заказа нет в базе)
<statuses_wrong> - перечисленные через запятую ID заказов
из вашего запроса, для которых вы указали некорректный статус
<statuses_not_changed> - перечисленные через запятую ID заказов
из вашего запроса, для которых вы указали статус, совпадающий с тем, что у них уже имелся
Все операции для заказов, в которых не было ошибки, успешно выполняются.
3. Список производителей (manufacturers.php).
Чтобы получить список производителей, вы должны вызвать файл:
manufacturers.php
Параметры вызова (все необязательные):
id - id производителя. Чтобы выбрать несколько, можно указать несколько id
через запятую или передать этот параметр в формате массива (id[])
name - название. Выберет все, названия которых включают
в себя переданную в данном параметре строку.
exc_field[] - поля, которые следует исключить из выборки. Возможно исключить
следующие поля:
name
description
image
Возврат:
В ответе, вам вернет в XML информацию об найденных объектах (производителях):
<objects> - внешний контейнер
<manufacturer> - Производитель (повторяется для каждого)
id - уникальный идентификатор. Целое число.
<name> - название
<description>* - описание
url* - веб-адрес сайта производителя
<image>* - картинка
src - урл картинки
width - ширина картинки в пикселах
height - высота картинки в пикселах
size - размер файла картинки (в байтах)
4. Список категорий продуктов (categories.php).
Чтобы получить список категорий, вы должны вызвать файл:
categories.php
Параметры вызова (все необязательные):
id - id категории. Чтобы выбрать несколько, можно указать несколько id
через запятую или передать этот параметр в формате массива (id[])
parID - id родительской категории. Несколько указывать нельзя.
active - 0(только неативные) или 1(только активные). Передавайте
только если хотите фильтровать по этому параметру.
name - название. Выберет все, названия которых включают
в себя переданную в данном параметре строку.
exc_field[] - поля, которые следует исключить из выборки. Возможно исключить
следующие поля:
name
title
comment
description
meta_title
meta_keywords
meta_description
image
Возврат:
В ответе, вам вернет в XML информацию об найденных объектах (категориях):
<objects> - внешний контейнер
<category> - Категория (повторяется для каждой)
id - уникальный идентификатор. Целое число.
parID - идентификатор родительской категории. Целое число.
Если 0 - то категория верхнего уровня
active - флаг активности. 0 или 1.
priority - приоритет. Целое число (0-255). Чем меньше - тем выше приоритет.
<name> - название
<title>* - длинное название (заголовок).
<comment>* - краткое описание
<description>* - полное описание
<meta_title>* - текст для тега TITLE в html-е
<meta_keywords>* - ключевые слова для вставки в мета-теги
<meta_description>* - описание для вставки в мета-теги
<image>* - картинка
src - урл картинки
width - ширина картинки в пикселах
height - высота картинки в пикселах
size - размер файла картинки (в байтах)
5. Список продуктов (products.php).
Чтобы получить список продуктов, вы должны вызвать файл:
products.php
Параметры вызова (все необязательные):
id - id продукта. Чтобы выбрать несколько, можно указать несколько id
через запятую или передать этот параметр в формате массива (id[])
catID - id категории продукта. Чтобы выбрать несколько, можно указать несколько id
через запятую или передать этот параметр в формате массива (catID[])
code - код продукта. Выводит на экран все продукты с данным кодом.
model - модель. Выберет продукты с данной моделью. Если нужен нестрогий поиск, то можно использовать символ '%' (например 'aa%').
active - 0(только неативные) или 1(только активные). Передавайте
только если хотите фильтровать по этому параметру.
in_stock - 0(только отсутствующие) или 1(только присутствующие). Передавайте
только если хотите фильтровать по этому параметру.
is_new - 0(только не новые) или 1(только новые). Передавайте
только если хотите фильтровать по этому параметру.
price_type - 0(только простые), или 1(только Special), или 2(только Featured). Передавайте
только если хотите фильтровать по этому параметру.
min_price - минимальная цена.
max_price - максимальная цена.
have_image - 0(только без картинки), или 1(только с картинкой). Передавайте
только если хотите фильтровать по этому параметру. Проверяет только по первой картинке!
have_attributes - 0(только без атрибутов), или 1(только с атрибутами). Передавайте
только если хотите фильтровать по этому параметру.
name - название. Выберет все, названия которых включают
в себя переданную в данном параметре строку.
keyword - ключевое слово. Выберет все, названия или описание которых включают
в себя переданную в данном параметре строку.
exc_field[] - поля, которые следует исключить из выборки. Возможно исключить
следующие поля:
name
comment
description
model
measure
dimensions
image1 - image6
document1 - document3
meta_title
meta_keywords
meta_description
attributes
attr_combinations
add_fields - все дополнительные поля сразу
Возврат:
В ответе, вам вернет в XML информацию об найденных объектах (продуктах):
<objects> - внешний контейнер
<product> - Продукт (повторяется для каждого)
id - уникальный идентификатор. Целое число.
active - флаг активности. 0 или 1.
priority - приоритет. Целое число (0-255). Чем меньше - тем выше приоритет.
categories - список категорий через запятую, в которых лежит данный товар.
<name> - название продукта
<comment>* - краткое описание продукта
<description>* - полное описание продукта
time_available - врямя в юникс-таймстампе (т.е. в секундах от начала 1970 года) когда товар станет доступен
date_available - дата в формате YYYY-MM-DD, когда товар станет доступен (time_available в другом формате)
in_stock - наличие. 0 или 1.
is_new - указатель, что продукт новый. 0 или 1.
price - цена продукта (основная).
opt1 - минимальное количество для мелкого опта (если 0, то опта нет).
price1 - цена продукта для мелкого опта.
opt2 - минимальное количество для крупного опта (если 0, то опта нет).
price2 - цена продукта для крупного опта.
price_type* - тип товара. 0 или отсутствует - обычный товар, 1 - Special (скидки), 2 - Featured (сезонный товар).
spec_time1* - нижняя граница времени в юникс-таймстампе, когда этот товар имеет указанный специальный тип.
Если 0 - то без ограничений с этой стороны
spec_date1* - нижняя граница времени в формате YYYY-MM-DD, когда этот товар имеет указанный специальный тип. Аналог spec_time1.
spec_time2* - верхняя граница времени в юникс-таймстампе, когда этот товар имеет указанный специальный тип.
Если 0 - то без ограничений с этой стороны
spec_date2* - верхняя граница времени в формате YYYY-MM-DD, когда этот товар имеет указанный специальный тип. Аналог spec_time2.
spec_price* - основная цена на этот период. Если 0, то равна основной
spec_price1* - мелкооптовая цена на этот период. Если 0, то этого опта нет.
spec_price2* - крупнооптовая цена на этот период. Если 0, то этого опта нет.
quantity - количество на складе. 1000000 означает отсутствие ограничения.
num_chosen - сколько уже куплено таких продуктов. Для использования в топе.
mnfID - ID производителя. 0 - производительне определен.
<upc_code>* - UPC код продукта
<ean_code>* - EAN код продукта
<code>* - внутренний код продукта
<model>* - модель продукта
url* - веб-адрес официальной страницы продукта
weight - вес продукта
<measure>* - единицы измерения (напр. мешки, килограммы, ...)
<dimensions>* - размеры
<meta_title>* - текст для тега TITLE в html-е
<meta_keywords>* - ключевые слова для вставки в мета-теги
<meta_description>* - описание для вставки в мета-теги
<image1>* - картинка.
Внимание:
картинок может быть до 6 штук. Вместо 1 тогда будут цифры от 1 до 6
(image1, image2,..., image6). Причем не обязательно подряд (т.е. могут наличествовать
1 и 6, а остальных не быть вовсе).
1 - маленькая картинка, 2 - средняя,
3 - большая, 4-6 - дополнительные
src - урл картинки
width - ширина картинки в пикселах
height - высота картинки в пикселах
size - размер файла картинки (в байтах)
<document1>* - дополнительные документы к продукту (например, инструкции, схемы, ...).
Внимание:
документов может быть до 3 штук. Вместо 1 тогда будут цифры от 1 до 3
(document1, document2, document3). Причем не обязательно подряд (т.е. может наличествовать
только 3, а 1-го и 2-го не быть вовсе).
name - название документа
src - урл документа
size - размер файла документа (в байтах)
<attributes>* - атрибуты товара, доступные для выбора покупателем
<attribute> - атрибут (их может быть несколько)
<code> - код данного атрибута - уникальная (в пределелах продукта) строка
type - тип атрибута - целое число от 0 до 3.
Существует 4 типа атрибутов:
0 - обязательный для выбора покупателем атрибут,
1 - опциональный атрибут - т.е. не обязательный,
2 - атрибут множественного выбора,
3 - текстовое поле для заполнения кастомером при покупке.
<name> - название атрибута
<description>* - описание атрибута
<min_length>* - для атрибута типа 3, минимальная требуемая длина текста. Если отстутствует
или равна 0 - этот атрибут (текстовое поле) кастомеру заполнять необязательно.
<max_length>* - для атрибута типа 3, максимальная разрешенная длина текста.
<options>* - опции данного атрибута (для типов 0-2)
<option> - опция (их может быть несколько)
<code> - код данной опции - уникальная (в пределелах атрибута) строка
<name> - название опции
price* - стоимость опции (может отсутствовать, тогда 0).
Может быть положительной и отрицательной - добавляется к стоимости товара
weight* - вес опции (может отсутствовать, тогда 0).
Может быть положительной и отрицательной - добавляется к весу товара
quantity* - доступное количество товаров с данной опцией (может отсутствовать, тогда не ограничено).
<attr_combinations>* - комбинации атрибутов товара, доступные для выбора покупателем
<attr_combination> - комбинация атрибутов (их может быть несколько)
<definition> - определение комбинации атрибутов - перечисленные через пробел пары вида
attribute_code#option_code, задающие код атрибута (только типа 0 или 1) и код его опции,
разделенные символом #. Например: « color#gold size#xl».
price* - стоимость комбинации (может отсутствовать, тогда 0).
Может быть положительной и отрицательной - добавляется к стоимости товара
weight* - вес комбинации (может отсутствовать, тогда 0).
Может быть положительной и отрицательной - добавляется к весу товара
quantity* - доступное количество товаров с данной комбинацией атрибутов (может отсутствовать, тогда не ограничено).
<additional_fields>* - дополнительные поля продукта, из числа определенных для данной товарной базы.
<additional_field> - дополнительное поле (их может быть несколько)
id - идентификатор (код) поля - строка, например, add_field_color, add_field_material
type - тип поля. Возможные значения:
string - определяет, что значение поле - текст до 255 символов,
text - поле - текст до 65К,
checkbox - для поля возможны значения 1/0, что соотвествуют да/нет,
select - поле содержит одно значение из нескольких возможных, определенных для этого поля,
multiple - поле содержит набор значений из нескольких возможных, определенных для этого поля
name - название поля
<value> - значение поля (может присутствовать несколько раз для поля типа multiple)
id - идентификатор значения - целое число. Присутствует только если type= select или multiple
value - значение
6. Удаление производителя (manufacturer_delete.php).
Чтобы удалить производителя, вы должны вызвать файл:
manufacturer_delete.php
Параметры вызова:
id - id производителя
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
7. Удаление категории (category_delete.php).
Чтобы удалить категорию, вы должны вызвать файл:
category_delete.php
Параметры вызова:
id - id категории
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
8. Удаление продукта (product_delete.php).
Чтобы удалить продукт, вы должны вызвать файл:
product_delete.php
Параметры вызова:
id - id продукта
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
9. Создание нового производителя/редактирование старого (manufacturer_edit.php).
Чтобы создать нового или отредактировать старого производителя, вы должны вызвать файл:
manufacturer_edit.php
Параметры вызова (не обязательны, если не указано персонально):
id - id производителя - передавать только в случае редактирования старого. Для создания нового не передавать или передать 0.
name - название (обязательно при создании нового), до 255 символов
url - урл сайта производителя, до 100 символов
description - описание, до 65К символов
image - файл картинки, переданный методом POST аналогично тому, как это делает браузер (<input type=file name=image>),
или строка, содержащая адрес (урл) картинки в интернете
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML id нового/старого производителя:
<id> - id производителя, целое число
10. Создание новой категории/редактирование старой (category_edit.php).
Чтобы создать новую или отредактировать старую категорию, вы должны вызвать файл:
category_edit.php
Параметры вызова (не обязательны, если не указано персонально):
id - id категории - передавать только в случае редактирования старой. Для создания новой не передавать или передать 0.
parID - id родительской категории. Целое число. Если 0 (или не указано при создании новой категории) - то категория верхнего уровня
name - название (обязательно при создании нового), до 100 символов
title - длинное название, до 100 символов
active - флаг активности - 0 или 1. Для новой по умолчанию 1.
priority - приоритет. Число 0-255.
comment - краткое описание, до 255 символов
description - описание, до 65К символов
meta_title - заголовок для вставки в мета-теги, до 255 символов
meta_keywords - ключевые слова для вставки в мета-теги, до 65К символов
meta_description - описание для вставки в мета-теги, до 65К символов
image - файл картинки, переданный методом POST аналогично тому, как это делает браузер (<input type=file name=image>),
или строка, содержащая адрес (урл) картинки в интернете
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML id новой/старой категории:
<id> - id категории, целое число
11. Создание нового продукта/редактирование старого (product_edit.php).
Чтобы создать новый или отредактировать старый продукт, вы должны вызвать файл:
product_edit.php
Параметры вызова (не обязательны, если не указано персонально):
id - id продукта - передавать только в случае редактирования старого. Для создания нового не передавать или передать 0.
categories - список категорий через запятую (обязательно при создании нового),
к которым следует привязать данный товар. Может быть передан в виде массива (categories[])
categories_delete - список категорий через запятую,
от которых следует отвязать данный товар. Может быть передан в виде массива (categories_delete[])
name - название (обязательно при создании нового), до 255 символов
active - флаг активности - 0 или 1. Для нового по умолчанию 1.
priority - приоритет. Число 0-255.
time_available - врямя в юникс-таймстампе (т.е. в секундах от начала 1970 года) когда товар станет доступен
date_available - дата в формате YYYY-MM-DD, когда товар станет доступен (вместо time_available - то же в другом формате)
in_stock - наличие. 0 или 1. По умолчанию 1.
is_new - указатель, что продукт новый. 0 или 1.
price - цена продукта основная (обязательно при создании нового).
opt1 - минимальное количество для мелкого опта (если 0, то опта нет).
price1 - цена продукта для мелкого опта.
opt2 - минимальное количество для крупного опта (если 0, то опта нет).
price2 - цена продукта для крупного опта.
price_type - тип товара. 0 - обычный товар, 1 - Special (скидки), 2 - Featured (сезонный товар).
spec_time1 - нижняя граница времени в юникс-таймстампе, когда этот товар имеет указанный специальный тип.
Если 0 - то без ограничений с этой стороны
spec_date1 - нижняя граница времени в формате YYYY-MM-DD, когда этот товар имеет указанный специальный тип (вместо spec_time1 - то же в другом формате)
spec_time2 - верхняя граница времени в юникс-таймстампе, когда этот товар имеет указанный специальный тип.
Если 0 - то без ограничений с этой стороны
spec_date2 - верхняя граница времени в формате YYYY-MM-DD, когда этот товар имеет указанный специальный тип (вместо spec_time2 - то же в другом формате)
spec_price - основная цена на этот период. Если 0, то равна основной
spec_price1 - мелкооптовая цена на этот период. Если 0, то этого опта нет.
spec_price2 - крупнооптовая цена на этот период. Если 0, то этого опта нет.
quantity - количество на складе. 1000000 означает отсутствие ограничения. По умолчанию 1000000.
num_chosen - сколько уже куплено таких продуктов.
mnfID - ID производителя. 0 - производительне определен.
upc_code - UPC код продукта
ean_code - EAN код продукта
code - внутренний код продукта. До 16 символов.
model - модель продукта. До 50 символов.
url - веб-адрес официальной страницы продукта. До 255 символов.
weight - вес продукта
measure - единицы измерения (напр. мешки, килограммы, ...). До 50 символов.
dimensions - размеры. До 100 символов.
comment - краткое описание, до 255 символов
description - описание, до 65К символов
meta_title - заголовок для вставки в мета-теги, до 255 символов
meta_keywords - ключевые слова для вставки в мета-теги, до 65К символов
meta_description - описание для вставки в мета-теги, до 65К символов
imageN - файл картинки, переданный методом POST аналогично тому, как это делает браузер (<input type=file name=image1>),
или строка, содержащая адрес (урл) картинки в интернете. Здесь N -
это номер картинки 1-6. 1,2,3 - малая, средняя и большая картинки, 4,5,6 - дополнительные.
Можно передавать сразу несколько: image1=...&image2=...
version - изменение размера и создание картинок. Если передать в этом поле значение "1", скрипт создаст картинки "image1" и "image2" в необходимом разрешении из картинки в поле "image3", если поле не пустое.
documentN - файл дополнительного документа, переданный методом POST аналогично тому, как это делает браузер (<input type=file name=document1>),
или строка, содержащая адрес (урл) файла в интернете. Здесь N -
это номер документа 1-3.
Можно передавать сразу несколько: document1=...&document2=...
document_nameN - название соответствующего дополнительного документа. До 50-ти символов.
Здесь N - это номер документа 1-3.
Можно передавать сразу несколько: document_name1=...&document_name2=...
addition_field[code] - дополнительное поле продукта, из числа определенных для данной товарной базы.
Здесь code - это код конкретного дополнительного поля.
Например, addition_field[add_field_type] или addition_field[add_field_material].
Прередаваемое значение зависит от типа поля. Это:
0 или 1 - для поля типа checkbox,
строка - для поля типа string или text,
ID соответствующей опции (целое число) - для поля типа select,
список ID опций через запятую - для поля типа multiple.
Кроме того, у каждого продукта может быть набор атрибутов, присущих только ему,
которые покупатель должен выбирать/указывать при заказе данного товара. У каждого атрибута есть
свой набор опций (т.е. значений), из которых выбирает покупатель, либо атрибут задает текстовое поле,
которое должно быть заполнено покупателем. Атрибуты представляют собой многоуровневую структуру,
с которой можно ознакомиться выше, в интерфейсе выборки продуктов. В данном интерфейсе для удобства работы
количество уровней передаваемых данных максимально урезано с помощью суффиксов в названиях элементов данных.
Т.е., к примеру, вместо attr[1][name], нужно будет передавать attr_name[1], и т.д.
При этом сопоставляться данные массивы будут по индексу, указанному в скобках, т.е.,
к примеру, attr_name[1] будет сосоставлен attr_code[1], а также attr_type[1] и т.д.
Также, действуют такие правила:
1. Если вы не хотите менять набор атрибутов у существующего продукта, или вновь создаваемый продукт не
имеет атрибутов, то нижеописанные данные передавать вовсе не нужно.
2. Однако, если вы передаете эти данные, то набор атрибутов у продукта будет переназначен полностью
в соответствии с этими данными. Т.е. вы каждый раз при смене хоть одного атрибута или опции у атрибута
должны передавать полный набор атрибутов данного продукта.
3. Если вы хотите уничтожить атрибуты у существующего товара, не создавая ему новых, вы
не должны передавать нижеописанные параметры, а дожны передать один параметр: drop_attrs=1
Набор параметров, необходимых для работы с атрибутами:
attr_name[] - назание атрибута (к примеру: Color или Sizе). Обязательное. Строка до 50 символов
attr_type[] - тип атрибута - целое число от 0 до 3. Обязательное.
Существующие типы атрибутов:
0 - обязательный для выбора покупателем атрибут,
1 - опциональный атрибут - т.е. не обязательный,
2 - атрибут множественного выбора,
3 - текстовое поле для заполнения кастомером при покупке.
attr_code[] - уникальный (в пределах продукта) код атрибута (к примеру: color). Строка до 50-ти символов.
Поле не обязательно. Если не передано или не уникально, то система сама автоматически
подберет уникальный код.
attr_description[] - описание атрибута. Строка до 255-ти символов.
attr_min_length[] - для атрибута типа 3, минимальная требуемая длина текста. Если отстутствует
или равна 0 - этот атрибут (текстовое поле) кастомеру заполнять необязательно.
attr_max_length[] - для атрибута типа 3, максимальная разрешенная длина текста.
Также, для каждого атрибута типов 0-2 должен быть передан набор опций (т.е. его возможных значений). Данный набор
передается с помощью нескольких двумерных массивов, где первый индекс массива (в первых скобках) -
это индекс аттрибута, а второй индекс (во вторых скобках) - индекс опции. К примеру:
attr_option_name[color][red] или attr_option_name[1][1], и т.д. Сопоставляться значения будут по индексам.
attr_option_name[][] - название опции. Обязательное. Строка до 50-ти символов. К примеру: Red Metallic
attr_option_code[][] - уникальный (в пределах аттрибута) код опции (к примеру: red-metal). Строка до 50-ти символов.
Поле не обязательно. Если не передано или не уникально, то система сама автоматически
подберет уникальный код.
attr_option_price[][] - стоимость опции (может отсутствовать, тогда 0).
Добавляется к стоимости товара при выборе опции покупателем, может быть положительной и отрицательной
attr_option_weight[][] - вес опции (может отсутствовать, тогда 0).
Добавляется к весу товара при выборе опции покупателем, может быть положительным и отрицательным.
attr_option_quantity[][] - доступное количество товаров с данной опцией (может отсутствовать, тогда не ограничено).
Если у продукта определены атрибуты, для него можно также определить комбинации атрибутов,
которые задают параметры продукта, когда определенные атрибуты принимают определенные значения
(т.е. когда их выбирает покупатель). Подобно атрибутам, комбинации атрибутов задаются с помощью
совмещаемых по ключам элементов данных с суффиксами в названии, например
attr_comb_definition[1] <=> attr_comb_price[1] и т.д.
Для комбинаций атрибутов определяются такие же параметры, как для одиночных атрибутов - добавляемые к основным данным
цена и вес, а также доступное количество продуктов с этой комбинацией атрибутов. Есть особенность:
если у продукта определены комбинации атрибутов, продукт считается доступным только в этих комбинациях,
заказ продукта в других комбинациях невозможен. При этом если для комбинации и участвующих в ней атрибутов определены
одноименные параметры (например, добавочный вес), то учитываются параметры комбинации,
а параметры отдельных атрибутов игнорируются.
Также, действуют такие правила:
1. Если вы не хотите менять набор комбинаций атрибутов у существующего продукта, или вновь создаваемый продукт не
имеет комбинаций атрибутов, то нижеописанные данные передавать вовсе не нужно.
2. Однако, если вы передаете эти данные, то набор комбинаций атрибутов у продукта будет переназначен полностью
в соответствии с этими данными. Т.е. каждый раз при смене хоть одной комбинации атрибутов,
вы должны передавать полный набор комбинаций атрибутов данного продукта.
3. Если вы хотите уничтожить комбинации атрибуты у существующего товара, не создавая ему новых, вы
не должны передавать нижеописанные параметры, а дожны передать один параметр: drop_attr_combs=1
4. Если у продукта удаляются или пересоздаются атрибуты, все имеющиемя у него комбинации атрибутов автоматически удаляются,
и их, при необходимости, нужно пересоздать
Набор параметров, необходимых для работы с атрибутами:
attr_comb_definition[] - определение комбинации атрибутов - перечисленные через пробел пары вида
attribute_code#option_code, задающие код атрибута (только типа 0 или 1) и код его опции,
разделенные символом # (атрибуты и их опции с соответствующими кодами должны существовать).
Например: «color#gold size#xl».
attr_comb_price[] - стоимость комбинации (может отсутствовать, тогда 0).
Добавляется к стоимости товара при выборе комбинации покупателем, может быть положительной и отрицательной
attr_comb_weight[] - вес комбинации (может отсутствовать, тогда 0).
Добавляется к весу товара при выборе комбинации покупателем, может быть положительным и отрицательным.
attr_comb_quantity[] - доступное количество товаров в данной комбинации (может отсутствовать, тогда не ограничено).
Напоминаем, что все параметры необязательны, кроме тех, где это специально указано.
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML id нового/старого продукта:
<id> - id продукта, целое число
12. Список комментариев к заказу (comments.php).
Чтобы получить список комментариев к заказу, вы должны вызвать файл:
comments.php
Параметры вызова (обязательно присутствие хотя бы одного):
id - id комментария. Чтобы выбрать несколько, можно указать несколько id
через запятую или передать этот параметр в формате массива (id[])
ordID - id заказа. Чтобы выбрать комментраии к нескольким заказам, можно указать несколько id
через запятую или передать этот параметр в формате массива (ordID[])
Возврат:
В ответе, вам вернет в XML информацию об найденных объектах (комментариях):
<comments> - внешний контейнер
<comment> - Комментарий (повторяется для каждого найденного комментария)
id - id (уникальный идентификатор) комментария. Целое число.
ordID - id заказа. Целое число.
time - время создания в виде UNIX_TIMESTAMP
time_str - время создания в виде человекопонятной строки
admin* - username последнего редактировавшего этот комментарий администратора
(может отстутствовать, например, если комментарий создавался через API)
<content> - содержание комментария
13. Удаление комментария к заказу (comment_delete.php).
Чтобы удалить комментарий, вы должны вызвать файл:
comment_delete.php
Параметры вызова:
id - id комментария
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
14. Создание нового комментария к заказу/редактирование старого (comment_edit.php).
Чтобы создать новый или отредактировать старый комментарий, вы должны вызвать файл:
comment_edit.php
Параметры вызова (не обязательны, если не указано персонально):
id - id комментария - передавать только в случае редактирования старого. Для создания нового не передавать или передать 0.
ordID - id заказа - обязательное при создании нового комментария
content - содержания комментария (обязательно)
mail - установить в 1, если комментарий следует послать заказчику
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML id новой/старой категории:
<id> - id комментария, целое число
15. Коррекция суммы заказа (order_edit_correction.php).
Чтобы внести коррекцию в сумму заказа, вы должны вызвать файл:
order_edit_correction.php
Параметры вызова (необязательны, если не указано персонально):
id - id заказа (обязатен)
amount - сумма коррекции заказа (обязательна, может быть отрицательной). Не модифицирует, а заменяет
сумму коррекции, прежде установленную для заказа, если таковая была.
description - описание коррекции, заменяет прежнее описание, если таковое было.
Обязательно, если amount ненулевой. Если amount=0 и description пустой - коррекция заказа отменяется,
т.е. заказ принимает изначальный вид.
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
16. Коррекция данных заказа о покупателе (order_edit_customer.php).
Чтобы внести коррекцию в данные покупателя (адреса и т.п.), вы должны вызвать файл:
order_edit_customer.php
Параметры вызова (необязательны, если не указано персонально):
id - id заказа (обязателен)
email - email заказчика
comment - комментарий заказчика к заказу
Shipping-адрес:
ship_first_name - first name
ship_last_name - last name
ship_company - company name
ship_address1 - address line 1
ship_address2 - address line 2
ship_city - city
ship_state - state/province (код, см. таблицу внизу)
ship_zip - zip/postal code
ship_country - country (2-буквенный ISO-3166 код)
ship_tel - telephone
ship_fax - fax
Billing-адрес:
bill_first_name - first name
bill_last_name - last name
bill_company - company name
bill_address1 - address line 1
bill_address2 - address line 2
bill_city - city
bill_state - state/province (код, см. таблицу внизу)
bill_zip - zip/postal code
bill_country - country (2-буквенный ISO-3166 код)
bill_tel - telephone
bill_fax - fax
Возврат:
В ответе, если не возникло ошибки, вам вернет в XML статус операции:
<status> - 1 если операция успешна
Таблица кодов ошибок (пропущенные номера зарезервированы на будущее)
| Код ошибки (ID) |
Название ошибки |
Пояснение |
| 1 | Store ID incorrect | | | 2 | API-key for this store has not been setted | | | 3 | API-key incorrect | | | 4 | Store is deactivated | | | 10 | Incorrect format of input parameter | Если у переданного параметра недопустимый формат или не передан обязательный параметр. В дополнительной информации будет указано название некорректного параметра |
|
Таблица статусов заказа
| Код статуса |
Название |
| 1 | Pending | | 11 | Need Confirm | | 9 | Ready To Ship | | 2 | Shipped | | 3 | Cancelled | | 4 | Deleted | | 5 | Possible fraud | | 6 | Fraud | | 7 | Delayed | | 8 | Return |
|
Таблица кодов штатов/провинций
| Код штата/провинции |
Название |
| Australia (AU) | | ACT | Australian Capital Territory | | NSW | New South Wales | | NT | Northern Territory | | QLD | Queensland | | SA | South Australia | | TAS | Tasmania | | VIC | Victoria | | WA | Western Australia | | Austria (AT) | | BL | Burgenland | | KN | Kдrnten | | NO | Niederцsterreich | | OO | Oberцsterreich | | SB | Salzburg | | ST | Steiermark | | TI | Tirol | | VB | Voralberg | | WI | Wien | | Canada (CA) | | AB | Alberta | | BC | British Columbia | | MB | Manitoba | | NB | New Brunswick | | NF | Newfoundland | | NT | Northwest Territories | | NS | Nova Scotia | | NU | Nunavut | | ON | Ontario | | PE | Prince Edward Island | | QC | Quebec | | SK | Saskatchewan | | YT | Yukon Territory | | Germany (DE) | | BAW | Baden-Wьrttemberg | | BAY | Bayern | | BER | Berlin | | BRG | Brandenburg | | BRE | Bremen | | HAM | Hamburg | | HES | Hessen | | MEC | Mecklenburg-Vorpommern | | NDS | Niedersachsen | | NRW | Nordrhein-Westfalen | | RHE | Rheinland-Pfalz | | SAR | Saarland | | SAS | Sachsen | | SAC | Sachsen-Anhalt | | SCN | Schleswig-Holstein | | THE | Thьringen | | Spain (ES) | | A Coruсa | A Coruсa | | Alava | Alava | | Alicante | Alicante | | Almeria | Almeria | | Asturias | Asturias | | Avila | Avila | | Badajoz | Badajoz | | Baleares | Baleares | | Barcelona | Barcelona | | Burgos | Burgos | | Caceres | Caceres | | Cadiz | Cadiz | | Cantabria | Cantabria | | Castellon | Castellon | | Ceuta | Ceuta | | Ciudad Real | Ciudad Real | | Cordoba | Cordoba | | Cuenca | Cuenca | | Girona | Girona | | Granada | Granada | | Guadalajara | Guadalajara | | Guipuzcoa | Guipuzcoa | | Huelva | Huelva | | Huesca | Huesca | | Jaen | Jaen | | La Rioja | La Rioja | | Las Palmas | Las Palmas | | Leon | Leon | | Lleida | Lleida | | Lugo | Lugo | | Madrid | Madrid | | Malaga | Malaga | | Melilla | Melilla | | Murcia | Murcia | | Navarra | Navarra | | Ourense | Ourense | | Palencia | Palencia | | Pontevedra | Pontevedra | | Salamanca | Salamanca | | Segovia | Segovia | | Sevilla | Sevilla | | Soria | Soria | | Tarragona | Tarragona | | Tenerife | Tenerife | | Teruel | Teruel | | Toledo | Toledo | | Valencia | Valencia | | Valladolid | Valladolid | | Vizcaya | Vizcaya | | Zamora | Zamora | | Zaragoza | Zaragoza | | Switzerland (CH) | | AG | Aargau | | AR | Appenzell Ausserrhoden | | AI | Appenzell Innerrhoden | | BL | Basel-Landschaft | | BS | Basel-Stadt | | BE | Bern | | FR | Freiburg | | GE | Genf | | GL | Glarus | | GR | Graubьnden | | JU | Jura | | LU | Luzern | | NE | Neuenburg | | NW | Nidwalden | | OW | Obwalden | | SH | Schaffhausen | | SZ | Schwyz | | SO | Solothurn | | SG | St. Gallen | | TI | Tessin | | TG | Thurgau | | UR | Uri | | VD | Waadt | | VS | Wallis | | ZG | Zug | | ZH | Zьrich | | United States (US) | | AL | Alabama | | AK | Alaska | | AS | American Samoa | | AZ | Arizona | | AR | Arkansas | | AF | Armed Forces Africa | | AA | Armed Forces Americas | | AC | Armed Forces Canada | | AE | Armed Forces Europe | | AM | Armed Forces Middle East | | AP | Armed Forces Pacific | | CA | California | | CO | Colorado | | CT | Connecticut | | DE | Delaware | | DC | District of Columbia | | FM | Federated States Of Micronesia | | FL | Florida | | GA | Georgia | | GU | Guam | | HI | Hawaii | | ID | Idaho | | IL | Illinois | | IN | Indiana | | IA | Iowa | | KS | Kansas | | KY | Kentucky | | LA | Louisiana | | ME | Maine | | MH | Marshall Islands | | MD | Maryland | | MA | Massachusetts | | MI | Michigan | | MN | Minnesota | | MS | Mississippi | | MO | Missouri | | MT | Montana | | NE | Nebraska | | NV | Nevada | | NH | New Hampshire | | NJ | New Jersey | | NM | New Mexico | | NY | New York | | NC | North Carolina | | ND | North Dakota | | MP | Northern Mariana Islands | | OH | Ohio | | OK | Oklahoma | | OR | Oregon | | PW | Palau | | PA | Pennsylvania | | PR | Puerto Rico | | RI | Rhode Island | | SC | South Carolina | | SD | South Dakota | | TN | Tennessee | | TX | Texas | | UT | Utah | | VT | Vermont | | VI | Virgin Islands | | VA | Virginia | | WA | Washington | | WV | West Virginia | | WI | Wisconsin | | WY | Wyoming |
|
|
