Skip to content
Класс для работы с API АвтоВебОфис
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
AwoApi.php
README.md

README.md

Класс упрощает работу с апи сервиса АвтоВебОфис

Как этим пользоваться:

1. Создаем объект

$api = new AwoApi();

$api->setKeys([
    'apiKeyRead' => '',  // API KEY GET
    'apiKeyWrite' => '', // API KEY SET
    'subdomain' => 'mastergroup'
]);

или

$api = new AwoApi([
    'apiKeyRead' => '', // API KEY GET
    'apiKeyWrite' => '', // API KEY SET
    'subdomain' => 'mastergroup'
]);

2. Устанвавливаем сущность для работы, например контакты

$api->contact();

3. Используем нужный метод для работы с данными

$response = $api->get(2);

Методы можно писать "цепочкой", например

// получаем данные контакта с ID = 2
$contact = $api->contact()->get(2);

// получаем список контактов, у которых есть партнер, элементы с 101 по 200, 
// отсортированные по партнеру
$items = $api->contact()
    ->pageSize(100)
    ->page(2)
    ->orderBy([
        'id_partner' => 'ASC', 
    ])
    ->getAll([
        'hasPartner' => -1
    ]);

Доступные сущности:

Для каждой сущности существует свой метод. Это позволяет использовать автодополнение в вашей IDE.

  • contact() - Контакты
  • organization() - Организации
  • employee() - Сотрудники
  • cost() - Расходы
  • costCategory() - Статьи расходов
  • invoiceLine() - Строки счета
  • invoice() - Счета
  • product() - Товары
  • productCategory() - Категории товаров
  • productColor() - Цвета товаров
  • productSize() - Размеры товаров
  • callcenterRequest() - Запросы в Call-центр
  • subscriberGroup() - Группы подписчиков
  • subscriber() - Подписчики
  • subscription() - Подписки (только создание)
  • advertisingCompany() - Рекламные кампании
  • advertisingChannel() - Каналы рекламы
  • advertisingChannelStatistics() - Каналы рекламы - Статистика
  • mainSettings() - Основные настойки магазина
  • partner() - Партнеры
  • productPinCode() - Пин коды к товарам
  • funnelContact() - Контакты в автоворнках

Доступные методы:

create(array $inputData) - Добавление

Создает новую сущность (или несколько сущностей). Ожидает получить массив с данными объектов (массив массивов). Даже при добавлении одной новой сущности требуется обернуть ее в отдельный массив.

// Создание нескольких контактов
$response = $api->contact()->create([
    [
        'fieldName' => 'fieldValue',
    ],
    [
        'fieldName' => 'fieldValue',
    ],
    ...
 ]);
 
// Создание одного контакта
$response = $api->contact()->create([
    [
        'fieldName' => 'fieldValue',
    ],
 ]);

Возвращает массив с данными созданных сущностей

array(3) {
 [0]=>
 object(stdClass)#3 (64) {
   ["id_contact"]=>
   string(5) "66018"
   ...
 }
 [1]=>
 object(stdClass)#4 (64) {
   ["id_contact"]=>
   string(5) "66019"
   ...
 }
 [2]=>
 object(stdClass)#5 (64) {
   ["id_contact"]=>
   string(5) "66020"
   ...
 }
}

Если в каком-либо добавляемом элементе обнаруживается ошибка (например, неверные параметры), вместо объекта добавленного элемента будет объект с ошибками следующего вида:

object(stdClass)#4 (2) {
  ["error"]=>
  string(71) "Email не является правильным E-Mail адресом."
  ["inputData"]=>
  object(stdClass)#5 (2) {
    ["name"]=>
    string(12) "Ильнур"
    ["email"]=>
    string(17) "fx5559_1552998894"
  }
}

Поле error содержит текстовое описание ошибки, поле inputData содержит данные, которые были переданы на сервер.

Ниже представлен пример ответа сервера на добавление 3-х элементов, второй из которых содержит неверные данные

array(3) {
  [0]=>
  object(stdClass)#3 (64) {
    ["id_contact"]=>
    string(5) "66024"
    ...
  }
  [1]=>
  object(stdClass)#4 (2) {
    ["error"]=>
    string(71) "Email не является правильным E-Mail адресом."
    ["inputData"]=>
    object(stdClass)#5 (2) {
      ["name"]=>
      string(12) "Ильнур"
      ["email"]=>
      string(17) "странный текст, не похожий на email"
    }
  }
  [2]=>
  object(stdClass)#6 (64) {
    ["id_contact"]=>
    string(5) "66025"
    ...
  }
}

Если параметр AwoApi::doNotFallOnError установить в false (по умолчанию true) - поведение становится немного другим (обычно api ведет себя именно таким образом, это поведение оставлено для совместимости со старым кодом):

Если какие-то параметры неверные, то в ответе сервер выдаст ошибку в виде текста. При этом, если вы добавляете множество сущностей за раз (к примеру 1000), и у вас 500-ый элемент содержит неверные данные, то 499 будут добавлены, на 500-ом сервер выдаст ошибку в виде текста и дальше добавление уже не продолжится.

В случае ошибок валидации, когда например у вас email явно некорректный, вместо строки сервер возвращает массив с ошибкой.

array(1) {
  [0]=>
  string(71) "Email не является правильным E-Mail адресом."
}

update($id, $inputData) - Изменение

Обновление (изменение) сущности. Первый агрумент - уникальный ID сущности, второй - массив с новыми данными в виде "название поля" => "значение поля"

// обновляем контакт с ID 65711
$response = $api->contact()->update(65711, [
    'name' => 'Рон',
    'last_name' => 'Матусалем',
    'email' => 'ron.matusalem@hotmail.com'
])

Возвращает объект с новыми данными.

object(stdClass)#2 (64) {
  ["id_contact"]=>
  string(5) "65711"
  ...
}

Или массив с ошибками, если сохранить не удалось

array(1) {
  [0]=>
  string(71) "Email не является правильным E-Mail адресом."
}

Или текст ошибки, если, к примеру, ID неверный

string(67) "Error: Didn't find any model contacts with ID 865711."

delete($id) - Удаление

Удаляет элемент (для некоторых сущностей - помещает в корзину). Принимает один аргумент - уникальный ID сущности. Возвращает этот же ID в случае успеха или текст ошибки. При попытке удаления уже удаленного эелемента сервер также вернет его ID.

// удаляем контакт с ID 255
$response = $api->contact()->delete(255)

get($id), getAll($searchParams = []) - Методы получения данных

get($id)

Получает данные одного элемента по его ID. Возвращает объект с данными этого эелемента или текст ошибки в случае если получить данные элемента не удалось.

$response = $api->product()->get(1279)

getAll($searchParams = [])

Получает массив элементов. Если указаны параметры поиска - возвращает только элементы - соответствующие заданным критериям.

// получаем список товаров, в названии которых встречается "курс"
$prods = $api
    ->product()
    ->getAll([
        'goods' => 'курс',
    ]);

Если ничего не найдено - в ответе будет текст (а не пустой массив, как можно ожидать)

string(38) "No items where found for model "

orderBy($sort = [])

Сортировка получаемых элементов. Единственный аргумент - массив, в котором указываются поля для сортировки и порядок (ASC или DESC). Обратите внимание на правильность названий полей, если в них будут опечатки, сервер выдаст ошибку 500. Также стоит отметить что сортировка иногда вызывает ошибки, если используются связанные таблицы для фильтрации.

// сортируем сначала по дате создания, потом по названию
$prods = $api
    ->orderBy([
        'creation_date' => 'DESC', 
        'goods' => 'ASC'
    ]);

pageSize($pageSize)

Устанавливает количество получаемых элементов (размер страницы). Принимает целое число от 1 до 1000. По умолчанию 50.

page($page)

Устанавливает страницу. Если результатов больше, чем установленный pageSize, то оставшиеся результаты можно получить через установку этого параметра. Номера страниц начинаются с 1 (если обращатся к апи напрямую, а не через этот класс, то первая страница 0).

Примеры использования класса API

В папке examples есть примеры кодов для большинства сценариев работы с АПИ

  • subscribe.php - Подписка контакта на группу подписчиков
  • changeGroup.php - Перенос подписчика из одной группы в другую
  • checkPurchase.php - Проверка покупки (покупал ли контакт, указанный товар)
  • checkSubscription.php - Проверка подписки
  • getPaymentLink.php - Получение ссылки на оплату счета
  • getSubscribers.php - Получаем всех подписчиков групп(ы) подписчиков
  • order.php - Оформление заказа (Создание нового счета)
  • payOrder.php - Изменение статуса счета на "оплачен"
You can’t perform that action at this time.