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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные возможности API

Если у Вас еще остались какие-либо вопросы, пожалуйста, обращайтесь в нашу Службу поддержки через кнопку Обратиться в поддержку, по email zakaz@autoweboffice.com или в окне консультанта на сайте http://autoweboffice.com

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