Содержание

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

• Введение

Пользователям АвтоВебОфис предоставлено несколько способов интеграции и обмена информацией с другими системами: API и оповещения сторонних скриптов (вебхуки).

ВНИМАНИЕ! Для удобства работы с АПИ Вы можете использовать готовый класс на PHP

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

  1. GET (API KEY GET) - от Вас приходит запрос по API на получения данных, например, о созданном счете, и они Вам отсылаются массивом
  2. SET (API KEY SET) - от Вас приходит запрос по API на внесение данных в нашу систему, например, создание или изменение счета в Вашем магазине АвтоВебОфис.

В сервисе действует гибкая система доступных ключей для работы с АПИ, для получения данных требуется ключ API KEY GET, для создания записей в системе требуется ключ API KEY SET. Посмотреть, какие ключи доступны на Вашем тарифе Вы можете тут.

Требуемые ключи находятся в разделе Настройки-API Вашего магазина

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

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

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

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

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

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

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

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

• Структура API

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

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

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

Ресурсы

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

У каждого ресурса есть свой уникальный 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 KEY «Только чтение» для вызова метода, изменяющего данные, возвращается ответ с HTTP-статусом 403 Forbidden.

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

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

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

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

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

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

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

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

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, представлено в виде ресурсов: получение статистики, список счетов, добавление расходов, управление каналами рекламы и т. д.

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

  1. читать содержимое и текущее состояние ресурса (GET);
  2. изменять содержимое и состояние и записывать его в ресурс (PUT);
  3. удалять ресурс (DELETE);
  4. выполнять специальные действия ― например, добавлять новые элементы в список (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


Успехов Вам и до новых встреч!
Служба заботы о клиентах сервиса АвтоВебОфис