8 926 559-17-40AutoWebOffice 

  

API магазина на платформе АвтоВебОфис

Введение

Структура API

Вызов методов

Авторизация

Формат входных данных

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

Справочник ресурсов

Независимые константы

 

Введение

API сервиса АвтоВебОфис (АвтоОфис) построен по REST-принципам.

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

То есть ресурс — это некая целостная часть системы, с которой можно работать:

- читать содержимое и текущее состояние ресурса (GET);

- изменять содержимое и состояние и записывать его в ресурс (PUT);

- удалять ресурс (DELETE);

- выполнять специальные действия ― например, добавлять новые элементы в список (POST).

У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами протокола HTTP на URL'ы ресурсов.

Например, чтобы получить информацию о счете, необходимо сделать GET-запрос на URL ресурса «Счета». А чтобы создать новый счет, необходимо сделать POST-запрос с телом счета на URL ресурса «Счета».

 

Справочник содержит описание программного интерфейса к магазину, зарегистрированному в сервисе АвтоОфис.

Справочник предназначен для разработчиков, заинтересованных в получении программного доступа к функциям сервиса. Предполагается, что разработчики уже знакомы с возможностями платформы АвтоОфис.

Для иллюстрации возможностей программного интерфейса в справочнике приведены примеры обращения к магазину, зарегистрированному в сервисе АвтоОфис, посредствам API. Методы в примерах возвращают демонстрационные данные, доступные для просмотра всем пользователям.

 

Структура API

Целью создания API является предоставление сторонним автоматизированным системам интерфейса взаимодействия с функциями платформы АвтоОфис, исключая пользовательский веб-интерфейс.

Например, API может использоваться в системах следующих типов:

- CMS- и blog-инсталляторах;
- хостинг-площадках;
- сторонних веб-сервисах.

API АвтоОфис построен по REST-принципам.

Ресурсы

Все, чем можно управлять через API, представлено в виде ресурсов: статистика, собственно счетчик, цель счетчика, фильтр счетчика, доступ к счетчику и т. д. То есть ресурс — это некая целостная часть системы, с которой можно работать:

- читать содержимое и текущее состояние ресурса (GET);
- изменять содержимое и состояние и записывать его в ресурс (PUT);
- выполнять специальные действия ― например, добавлять новые элементы в список (POST).
- удалять ресурс (DELETE);

У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами защищенного протокола HTTPS на URL'ы ресурсов.

Например, чтобы получить информацию о счетах, выписанных в интернет магазине, необходимо сделать GET-запрос на URL счета. А чтобы создать новый счет, необходимо сделать POST-запрос с телом счета на URL ресурса «Счета».

Полный список всех ресурсов и доступных для них операций приведен в Справочнике ресурсов.

 

Вызов методов

Примечание: Запросы к API Метрики могут передаваться только по протоколу HTTPS.

Запрос к сервису задается в следующем формате:

<тип_метода>https://<идентификатор_магазина>.autoweboffice.ru/?r=api/rest/<имя_метода>&<параметры>

<тип_метода> ― GET, POST, PUT или DELETE.

<идентификатор_магазина> ― уникальный идентификатор вашего интернет магазина, зарегистрированного  в сервисе АвтоОфис

<имя_метода> ― URL ресурса, над которым выполняется действие. Список ресурсов приведен в справочнике ресурсов.

<параметры> ― обязательные и необязательные параметры запроса, которые не входят в состав URL ресурса.

Поиск и сортировка получаемых данных

Для передачи параметров поиска в запрос, используется параметр:

search[<свойство>]= <значение>

Где:

<свойство> – наименование поля, по которому будет осуществлен поиск
<значение> – передаваемое значение для поиска

 

Для передачи параметров сортировки получаемых данных, используется параметр:

param[sort] = <поле><вид>

Где:

<поле> – наименование поля, по которому будет осуществлена сортировка
<вид> – вид сортировки ASCили DESC. По умолчанию значение ASC

 

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

param[pagesize] = <pagesize>

param[currentpage] = <currentpage>

Где:

<pagesize> – количество элементов отображаемых на странице
<currentpage> – номер отображаемой страницы с данными

 

Обработка ошибок

В случае неверно составленного запроса методы API возвращают сообщения об ошибках.

 

Авторизация

Для использования API АвтоОфис необходимо получить авторизационный API KEY в настройках API вашего магазина зарегистрированного в сервисе АвтоОфис. API KEY необходимо передавать во всех запросах, в которых нужна авторизация. Если метод API вызван без авторизации или в запросе передан недействительный API KEY, сервер АвтоОфис возвращает HTTP-статус 401 Unauthorized.

Авторизационные API KEY различаются уровнем доступа, который присваивается при выдаче API KEY и в дальнейшем не меняется. Существуют уровни доступа:

- «Только чтение» — позволяет вызывать методы, возвращающие информацию об объектах, например статистику или параметры созданных счетов;
- «Изменение» — позволяют изменять, добавлять и удалять данные в вашем магазине, зарегистрированном в сервисе АвтоОфис, средствами API.

При использовании API KEY «Только чтение» для вызова метода, изменяющего данные, возвращается ответ с HTTP-статусом 403 Forbidden.

Для получения API KEY, соответствующих вашему интернет магазину, вам необходимо прости в раздел «Настройки->API».

 

Формат входных данных

Входные структуры данных POST- и PUT-методов передаются в теле запроса. Входные структуры совпадают с выходными структурами GET-методов соответствующих ресурсов.

Совет: Чтобы корректно сформировать входную структуру для POST- или PUT-метода, вызовите GET-метод для уже существующего ресурса. Скопируйте полученную структуру и задайте нужные значения полей.

POST- и PUT-методы API принимают входные данные в формате XML

Примечание: Примеры запросов приведены в разделе Примеры запросов.

Сервис возвращает HTTP-статус 400 Bad Request в следующих случаях:

- переданные данные невалидны ни как XML;
- в структуре данных содержатся ошибки;

 

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

API возвращает ответы в кодировке UTF-8. Ответы имеют формат JSON.

Полный пакет примеров php-кодов для работы с API платформы АвтоОфис, вы можете скачать по ссылке: https://autoweboffice.com/resources/php-examples.zip

Пример запроса на получения Счетов:

GET https://<идентификатор_магазина>.autoweboffice.ru/?r=api/rest/accounts&<параметры>

Пример: см. файл «Список счетов.php» в архиве «php-examples.zip»

 

Пример запроса на изменение конкретного Контакта:

PUT https://<идентификатор_магазина>.autoweboffice.ru/?r=api/rest/contacts&<параметры>&id=1329

Пример: см. файл «Изменение контакта.php» в архиве «php-examples.zip»

 

Пример запроса на добавление Контактов:

POST https://<идентификатор_магазина>.autoweboffice.ru/?r=api/rest/contacts&<параметры>

Пример: см. файл «Добавление контактов.php» в архиве «php-examples.zip»

 

Примечание: Благодаря тому, что данные добавляется в формате XML, вы можете осуществлять массовое (пакетное) добавление данных одним запросом. Т.е. составить XML с информацией по нескольким ресурсам и разом передать всю необходимую информацию в ваш интернет магазин, зарегистрированный в АвтоОфис.

 

Пример запроса для удаления Статьи расхода:

DELETE https://<идентификатор_магазина>.autoweboffice.ru/?r=api/rest/costsarticle&<параметры>&id=4

Пример: см. файл «Удаление расхода.php» в архиве «php-examples.zip»

В случае успешного удаления данных, система вернет результат «200 OK»

 

Справочник ресурсов

API сервиса АвтоВебОфис (АвтоОфис) построен по REST-принципам.

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

То есть ресурс — это некая целостная часть системы, с которой можно работать:

- читать содержимое и текущее состояние ресурса (GET);

- изменять содержимое и состояние и записывать его в ресурс (PUT);

- удалять ресурс (DELETE);

- выполнять специальные действия ― например, добавлять новые элементы в список (POST).

У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами протокола HTTP на URL'ы ресурсов.

Например, чтобы получить информацию о счете, необходимо сделать GET-запрос на URL ресурса «Счета». А чтобы создать новый счет, необходимо сделать POST-запрос с телом счета на URL ресурса «Счета».

Содержит перечень ресурсов, которые поддерживаются API АвтоОфис, и доступных для них операций.

Ресурс

URL

Методы

Параметры

Контакты

?r=api/rest/contacts

GET

PUT

POST

DELETE

id_contact - код контакта

id_partner - код партнера

last_name - фамилия

name - имя

middle_name - отчество

email - адрес электронной почты

password - пароль от личного кабинета клиента

not_to_write - просил не писать

spam_clicked - пожаловался на СПАМ

spam_clicked_date - дата жалобы на спам

unsubscribe_date - дата отписки от новостей магазина

email_not_exist - признак не существования email

phone_number - номер телефона

do_not_call - просил не звонить

id_country - код страны

zip_code - почтовый индекс

area - область

city - город

delivery_address - адрес доставки

skype - skype клиента 

ban - признак блокировки клиента

ban_reason - причина блокировки клиента

sex - пол (1 - муж., 2 - жен.)

date_of_birth - дата рождения

brief_description - краткое описание

date_registration - дата регистрации в системе

id_employee_responsible - код ответственного сотрудника

id_employee_created - код сотрудника, зарегистрировавшего контакт

id_advertising_channel_page - API код канала рекламы

advertising_channel_keyword - ключевое слово

advertising_channel_location - место размещения

advertising_channel_type_traffic - тип трафика

Организации

?r=api/rest/organization

GET

PUT

POST

DELETE

id_organization - код организации

organization - название

inn - ИНН

kpp - КПП

set_account - расчетный счет

bank - наименование банка

bik - БИК

pk - корсчет

creation_date - дата создания

id_employee_created - код сотрудника, создавшего организацию

Сотрудники

?r=api/rest/employee

GET

PUT

POST

DELETE

id_employee - код сотрудника

employee - сотрудник

login - email сотрудника (логин)

id_contact - код контакта

ban - признак увольнения (блокировки)

temporary - признак "временный сотрудник"

num_in_tracking - номер в менеджере задач

show_in_tracking - показывать или нет в менеджере задач

date_registration - дата регистрации

id_employee_created - код зарегистрировавшего сотрудника

Расходы

?r=api/rest/costs

GET

PUT

POST

DELETE

id_costs - код расхода

id_costs_article - код строки расхода

costs_date - дата расхода

costs_sum - сумма

costs_comment - комментарий

id_employee_created - код создавшего сотрудника

creation_date - дата создания

Статьи расхода

?r=api/rest/costsarticle

GET

PUT

POST

DELETE

id_costs_article - код статьи расхода

costs_article - статья расхода

costs_article_description - описание

id_employee_created - код создавшего сотрудника

creation_date -дата создания

Строки счета

?r=api/rest/accountline

GET

PUT

POST

DELETE

id_account_line - код строки счета

id_partner - код партнера

number - номер в счете

goods - название товара на момент заказа

price_full - полная цена товара на момент заказа

price - цена товара

quantity - количество товара

sum_price - сумма строки счета

id_account - код счета

id_goods - код твоара

id_goods_kind - код вида товара

id_goods_kits - код комплекта товаров

id_goods_offers - код офера

id_goods_discounts - код дополнительной скидки к товару

id_goods_discount_on_quantity - код скидки от количества товара 

id_goods_offers_change_offer - код дополнительного предложения к оферу

id_super_discount_statistics_provide - код Суперскидки

id_goods_color - код цвета товара

id_goods_size - код размера товара

creation_date - дата создания

id_employee_created - код создавшего сотрудника

Счета

?r=api/rest/accounts

GET

PUT

POST

DELETE

id_account - код счета

id_partner - код партнера

account_number - номер счета

account_sum - общая сумма счета

id_account_status - код статуса счета

close_account - признак закрытия счета

id_payment_system - код платежной системы

close_date - дата закрытия счета

date_of_order - дата создания счета

goods_return - признак возврата товара

date_of_payment - дата оплаты счета

goods_return_date - дата возврата товара

last_name - фамилия заказчика

name - имя заказчика

middle_name - отчестство заказчика

email - электронный адрес заказчика

phone_number - телефон заказчика

skype - skype заказчика

account_comment - комментарий к счету

id_organization - код организации

id_delivery_region - код региона доставки

id_delivery_region_method - код способа доставки для региона

id_country - код страны

area - область

city - город

delivery_address - адрес доставки

zip_code - почтовый индекс

barcode - почтовый идентификатор

id_employee_created - код создавшего сотрудника

id_advertising_channel_page - API код канала рекламы

advertising_channel_keyword - ключевое слово

advertising_channel_location - место размещения

advertising_channel_type_traffic - тип трафика

Товары

?r=api/rest/goods

GET

PUT

POST

DELETE

id_goods - код товара

marking - артикул твоара

id_goods_category - код категории товаров

in_affiliate - признак участия в партнерской программе магазина

show_in_affiliate - признак отображения в партнерской программе магазина

goods - товар

variants_name - варианты названия

image - изображение

url_external_image - Url внешнего изображения 

url_external_image_used - признак использования внешнего изображения

brief_description - краткое описание

price - цена

price_purchase - цена закупки

url_page - url страницы описания

not_sold - признак снятия в продажи

not_sold_message - сообщение выводимое если товар снят с продажи

new_of_sales - признак "Новинка"

hit_of_sales - признак "Хит продаж"

special_offer - признак "Специальное предложение"

id_goods_kind - код вила товара

creation_date - дата создания

rest_in_stock - остаток товара на складе

id_supplier - код поставщика

id_manufacturer - код производителя

id_employee_created - код создавшего сотрудника

goods_color_name - название свойства "Цвет товара"

goods_size_name - название свойства "Размер товара"

goods_color_used - использовать свойства "Цвет товара"

goods_size_used - использовать свойства "Размер товара"

free_price - признак свободной цены

free_price_min - минимальная свободная цена

free_price_recommend - рекомендуемая свободная цена

Категории товаров

?r=api/rest/goodscategory

GET

PUT

POST

DELETE

id_goods_category - код категории товаров

goods_category - название

brief_description - краткое описание

id_goods_category_parent - код категории родителя

id_employee_created - код создавшего сотрудника

creation_date - дата создания

Цвет товара

?r=api/rest/goodssize

GET

PUT

POST

DELETE

id_goods_color - код цвета товара

num - порядковый номер

goods_color - цвет товара

goods_color_hex - HEX-код цвета товара

change_price - настройка изменения цены для цвета товара

id_goods - код товара

used - признак "Используется"

creation_date - дата создания

id_employee_created - код создавшего сотрудника

Размер товара

?r=api/rest/goodscolor

GET

PUT

POST

DELETE

id_goods_size - код размера товара

num -порядковый номер

goods_size - размер товара

change_price - настройка изменения цены для размера товара

id_goods - код товара

used - признак "Используется"

creation_date - дата создания

id_employee_created - код создавшего сотрудника

Запросы в Call-центр

?r=api/rest/callcenterrequest

GET

PUT

POST

DELETE

id_callcenter_request - код запроса

id_contact - код контакта

callcenter_request_comment - комментарий к запросу

id_callcenter_request_result - код результата обработки запроса

id_callcenter_request_lists - код списка запросов

id_employee - код ответственного сотрудника

processed - признак "Обработан"

processed_date - дата обработки

id_employee_processed - код обработавшего сотрудника

appointment_date - дата назначения ответственного

id_training_lessons - код обучающего курса

date_next_call - дата следующего звонка

creation_date - дата создания

id_employee_created - код создавшего сотрудника

id_account - код счета

id_callcenter_purpose_call - код цели звонка

id_advertising_channel_page - API код канала рекламы

advertising_channel_keyword - ключевое слово

advertising_channel_location - место размещения

advertising_channel_type_traffic - тип трафика

do_not_send_notification - не отправлять оповещение клиенту о создание запроса в Call-центр

Группы подписчиков

?r=api/rest/newsletter

GET

PUT

POST

DELETE

id_newsletter - код группы подписчиков

id_path_client_crossroad - код цепочки касаний

newsletter - название рассылки

short_description - краткое описание

page_confirm_subscription - текст страницы с просьбой подтвердить подписку

email_confirm_subscription_subject - тема письма с просьбой подтвердить подписку

email_confirm_subscription_text - текст сообщения с просьбой подтвердить подписку

page_subscription - текст на странице успешного подтверждения подписки

email_subscription_subject - тема сообщения после подтверждения подписки

email_subscription_text - текст сообщения после подтверждения подписки

page_already_subscribed - текст на странице уже подписан на рассылку

page_unsubscription - текст на странице с информацией после отписки от рассылки

author - автор рассылки

author_email - email автора рассылки

additional_urls - дополнительные url-адреса

product_launch - признак "Используется для запуска"

product_launch_date_start - дата начала запуска

product_launch_date_end - дата завершения запуска

date_creation - дата создания

Подписчики групп подписчиков

?r=api/rest/contactnewsletterlinks

GET

PUT

POST

DELETE

id_contact_newsletter_links - код связи контакта и группы подписчиков

id_contact - код контакта

id_newsletter - код группы подписчиков

id_partner - код партнера

creation_date - дата создания

confirmed - признак подтверждения подписки

confirmed_date - дата подтверждения подписки

id_advertising_channel_page - API код канала рекламы

advertising_channel_keyword - ключевое слово

advertising_channel_location - место размещения

advertising_channel_type_traffic - тип трафика

Рекламные кампании

?r=api/rest/advertisingchannelcompany

GET

PUT

POST

DELETE

id_advertising_channel_company - код рекламной кампании

advertising_channel_company - название рекламной кампании

description - описание рекламной кампании

Каналы рекламы

?r=api/rest/advertisingchannel

GET

PUT

POST

DELETE

id_advertising_channel - код канала рекламы

id_advertising_channel_company - код рекламной кампании

advertising_channel - название канала рекламы

description - описание канала рекламы

Каналы рекламы - Статистика

?r=api/rest/advertisingchannelstatistics

GET

Принимаемые параметры:

id - код канала рекламы (id_advertising_channel)

start - дата начала выборки

end - дата конца выборки

Возвращаемые параметры:

unique_transitions - уникальные переходы по каналу

unique_contacts - контакты

num_accounts - кол-во счетов

num_paid_accounts - кол-во оплаченных счетов

sum_paid_accounts - сумма оплаченных счетов

Основные настойки магазина

?r=api/rest/mainsettings

GET

id_stores - код магазина

stores_logo - логотип магазина

site_stores_url - URL сайта магазина

stores_name - название магазина

stores_description - описание магазина

stores_admin_email - email администратора магазина 

id_store_status - код статуса магазина

id_currency - код валюты магазина

stores_language - язык страниц оформления заказа магазина

 

Независимые константы

Константа

Допустимые значений

Код вида товара

1 - Электронная версия (Запись)

2 - Физический товар

3 - Услуга

Код статуса счета

1 - Создан

2 - Отказ

3 - В обработке

4 - Ошибка

5 - Оплачен

Код платежной системы (способа оплаты)

1 - Яндекс.Деньги для физ. лиц

2 - RBK Money

3 - QIWI (QIWI Wallet)

4 - Оплата через российский банк

5 - Z-payment

6 - WebMoney

7 - LiqPay

8 - InterKassa

9 - Наличные

12 - Юридическим лицам

13 - Наложенный платеж

14 - 2CheckOut

15 - PayPal

16 - ROBOKASSA

17 - Яндекс.Деньги для юр. лиц (Яндекс.Касса)

18 - Оплата через украинский Банк

19 -  Единый кошелек (WalletOne)

20 - Свой способ оплаты

21 - PayOnline

22 - IntellectMoney

23 - PayMaster

24 - PayAnyWay

26 - Яндекс.Деньги перевод на банковский счет

27 - Тинькофф Кредитные Системы