Содержание
API аккаунта на платформе АвтоВебОфис
• Введение
Пользователям АвтоВебОфис предоставлено несколько способов интеграции и обмена информацией с другими системами: API и оповещения сторонних скриптов (вебхуки).
ВНИМАНИЕ! Для удобства работы с АПИ Вы можете использовать готовый класс на PHP
API работает по системе запроса пользователя, т.е. инициатором выступаете Вы, есть 2 режима:
- GET (API KEY GET) - от Вас приходит запрос по API на получения данных, например, о созданном счете, и они Вам отсылаются массивом
- SET (API KEY SET) - от Вас приходит запрос по API на внесение данных в нашу систему, например, создание или изменение счета в Вашем магазине АвтоВебОфис.
В сервисе действует гибкая система доступных ключей для работы с АПИ, для получения данных требуется ключ API KEY GET, для создания записей в системе требуется ключ API KEY SET. Посмотреть, какие ключи доступны на Вашем тарифе Вы можете тут.
Требуемые ключи находятся в разделе Настройки-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 платформы АвтоВебОфис вы можете скачать здесь: 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 - пароль от личного кабинета клиента telegram_user_id - ID контакта в Телеграме telegram_user - Username контакта в Телеграме telegrambotcontactlnk - подписки контакта на ботов в телеграм. Пример использования тут id_telegram_bot - код бота в АВО id_contact - код контакта в АВО 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 - тип трафика vk_user_id - идентификатор vk контакта roistat - Роистат link_personal_auth - Персональная временная ссылка на вход в личный кабинет клиента |
| Организации | ?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 - код статуса счета (1 - создан, 2 - отказ, 3 - в обработке, 4 - ошибка, 5 - оплачен) 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 - тип трафика roistat - Роистат |
| Рекуррентные счета | ?r=api/rest/ContactRecurringPayments | GET PUT POST DELETE | id_contact_recurring_payments - уникальный идентификатор подписки контакта id_contact - код контакта id_goods - код товара по покупка которого привела к подписке id_account_line - код строки счета id_payment_system - код платежной системы date_last_payments - дата последнего платежа date_next_payments - дата следующего платежа date_lock - дата блокировки unsubscribe - признак отписки recurring_payment_failed - признак НЕуспешного платежа по подписке (списание не удалось) unsubscribe_date - дата отписки creation_date - дата создания записи deleted - признак удаления deleted_date - дата удаления записи |
| Товары | ?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 - рекомендуемая свободная цена id_currency - код валюты товара |
| Категории товаров | ?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/goodscolor | 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/goodssize | 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 - описание канала рекламы advertising_channel_page_url - URL страницы id_advertising_channel_page - API код |
| Каналы рекламы - Статистика | ?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 - язык страниц оформления заказа магазина |
| Партнеры | ?r=api/rest/partner | GET PUT POST DELETE | id_partner - код партнера id_partner_parent - код родительского партнера (кем был привлечен) id_contact - код контакта партнера legal_entity - Тип регистрации физ лицо ( = 1) или юр лицо (= 2) partner - имя партнера login - email партнера для входа в л/к password - пароль для входа в л/к organization - организация url_partner_site - адрес основного сайта партнера data_on_purses - данные по кошелькам партнера activated - признак активации (1 = активирован) ban - признак блокировки ban_reason - причина блокировки date_registration - дата регистрации партнера not_to_write - признак того, что нельзя слать письма этому партнеру id_partner_external_system - код партнера на внешних сервисах id_partner_parent_external_system - код родительского партнера на внешних сервисах Параметры, отмеченные *, обязательны для создания запроса. |
Независимые константы
| Константа | Допустимые значения |
|---|---|
| Код вида товара | 1 - Электронная версия (Запись) 2 - Физический товар 3 - Услуга |
| Код статуса счета | 1 - Создан 2 - Отказ 3 - В обработке 4 - Ошибка 5 - Оплачен |
| Код валюты товара | 987 - RUB (Рубли) 980 - UAH (Гривны) 978 - EUR (Евро) 933 - BYN (Бел.рубли) 840 - USD (Доллары) 398 - KZT (Тенге) |
| Код платежной системы (способа оплаты) | 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 - Тинькофф Кредитные Системы |
• Дополнительные возможности API
| Ресурс | URL | Методы | Параметры |
|---|---|---|---|
| Отправка email оповещения клиенту о создании/оплате существующего счета | ?r=api/rest/accountssendmail | GET | id - код счета (id_account) key - API KEY SET |
| Получения персональной ссылки на оплату товара (уникальная для контакта) Контакт сразу попадает на страницу выбора платежной системы, минуя форму заполнения контактных данных | ?r=api/rest/geturlgoodsordering | GET | key - API KEY GET id_goods - КОД_ТОВАРА id_contact - КОД_КОНТАКТА rp - для получения ссылки на оплату рекуррента (rp=1) |
Если у Вас еще остались какие-либо вопросы, пожалуйста, обращайтесь в нашу Службу поддержки через кнопку Обратиться в поддержку, по email zakaz@autoweboffice.com или в окне консультанта на сайте http://autoweboffice.com
Успехов Вам и до новых встреч!
Служба заботы о клиентах сервиса АвтоВебОфис