REST API onboard24.ru interface – Шлюз Сервиса Интернет Объявлений

Уважаемый посетитель!

На этой странице описаны методы работы с интерфейсом АПИ Сервиса Интернет Объявлений версии 1.0. Используя АПИ, вы можете организовать полноценную работу с Сервисом на уровне “сырых” данных.

В частности, данный АПИ позволяет:

подавать объявления (методы new_adv и post_adv);
просматривать содержимое поданных объявлений (метод view_adv);
получать статус объявления и прямые ссылки (метод get_adv_status);
запрашивать баланс учетной записи (метод balance);
получать справочники городов, схем размещения, доступных полей и т.д. (метод get_fields).

Все обращения к методам осуществляются по ссылке http://api.onboard24.ru/rest/v1/METHOD/{ID}, где METHOD– название метода, {ID} – уникальный номер объявления (для некоторых методов не используется).

Перед началом работы с АПИ-интерфейсом необходимо пройти регистрацию на сайте onboard24.ru/register и отправить заявку на активацию АПИ по адресу info@onboard24.ru. Подключение услуги абсолютно бесплатно. Оплата в виде аванса на внутренний счет используется только за фактические размещения.
Далее по тексту будет представлена документация по работе с методами и примеры кода на языке PHP.

Подготовка

Все запросы требуют передачи авторизационных данных в виде логина и пароля от Кабинета на сайте onboard24.ru для идентификации текущего пользователя. Логин и пароль кодируются алгоритмом base64 и передаются в заголовке запроса.
Например, если ваш логин и пароль равны myLogin и myPassword, то авторизационный заголовок будет получен так:


<?php
	$headers = array (
		'Authorization: Basic ' . base64_encode( 'myLogin' . ':' . 'myPassword' ),
	);
?>

Теперь, получив заголовок с данными авторизации, можно записать код, через который осуществляются запросы.
Для GET-запросов:


<?php
	$headers = array (
		'Authorization: Basic ' . base64_encode( 'myLogin' . ':' . 'myPassword' ),
	);
	$api_url = 'http://api.onboard24.ru/rest/v1/';
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $api_url . $method . '/' . $id);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
	$server_output = curl_exec ($ch);
	curl_close ($ch);
?>

Для POST-запросов:


<?php
	$headers = array (
		'Authorization: Basic ' . base64_encode( 'myLogin' . ':' . 'myPassword' ),
	);
	$api_url = 'http://api.onboard24.ru/rest/v1/';
	$post_vars = array(
		'param1' => 'value1',
		...
	);
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $api_url . $method . '/' . $id);
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post_vars));
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
	$server_output = curl_exec ($ch);
	curl_close ($ch);
?>

где $api_url – адрес шлюза (API-интерфейса), $method – имя метода, $id – айди объявления, $post_vars – массив параметром, передаваемых в POST-запросе.
Формат возвращаемых данных – JSON.
Далее рассматривается работа с каждым из доступных методов.

Методы

new_adv

Ссылка: http://api.onboard24.ru/rest/v1/new_adv/
Тип запроса: POST
Используется для занесения нового объявления в систему onboard24.ru. Плата на данном этапе не взимается. Объявление просто заносится в память системы и может быть передано в размещение позже.
Пример массива данных для отправки POST-запроса на заведение нового объявления:


<?php
	$post_vars = array(
		"skhema" => '5',
		"ishop" => 1,
		"ishop_regions" => array(2,12,20),
		"category" => 2,
		"buysell" => 3,
		"advhead" => "Оцифровка аудиокассет и видеокассет в Москве",
		"advtext" => "Производим оцифровку аудиокассет с последующей записью на диск или флешку. 
Переписываем содержимое видеокассет формата VHS, VHS-C на DVD. 
Предлагаем разработку фирменной обложки с вашими фотографиями. 
По желанию заказчика можем выгрузить видео на или файловый архив YouTube и скрыть от посторонних. Таким образом только вы и те, кому вы сообщили ссылку, смогут посмотреть это видео в любой точке мира.",
		"price" => 90,
		"username" => "Александр",
		"region" => 77,
		"email" => 'info@onboard24.ru',
		"city" => "Москва",
		"site" => "http://somesite.ru",
		"phone" => array('+79523806548' , '809212345678', '97860845'),
		"pic" => array(
			'http://***.jpg',
			'https://***.png',
			'http://***.jpg',
		),
	);
?>

Полный список возможных параметров, используемых при заведении объявления в систему onboard24.ru, можно получить из метода get_fields.

Формат успешного ответа:


{
  "success": {
    "un_id": "14611690346",
    "boards": "100",
    "ishop": 1,
    "ishop_regions": "[\"2\",\"12\",\"20\"]",
    "category": "1",
    "buysell": "3",
    "advhead": "Оцифровка аудиокассет и видеокассет в Москве",
    "advtext": "Производим оцифровку аудиокассет с последующей записью на диск или флешку. \r\nПереписываем содержимое видеокассет формата VHS, VHS-C на DVD. \r\nПредлагаем разработку фирменной обложки с вашими фотографиями. \r\nПо желанию заказчика можем выгрузить видео на или файловый архив YouTube и скрыть от посторонних. Таким образом только вы и те, кому вы сообщили ссылку, смогут посмотреть это видео в любой точке мира.",
    "price": "90",
    "username": "Александр",
    "region": "77",
    "city": "Москва",
    "tel1": "+79523806548",
    "tel2": "809212345678",
    "email": "admin@onboard24.ru",
    "site": "somesite.ru",
    "pic1": "http://***-1.jpg",
    "pic2": "http://***-2.jpg",
    "pic3": "http://***-3.jpg"
  },
  "warnings": {
    "phones": {
      "wrong_number": [
        "97860845"
      ]
    },
  },
  "errors": null
}

Поля структуры ответа метода new_adv:
В поле success выводятся результаты в случае успешного добавления объявления. Помимо переданных в самом теле объявления параметров, в поле success возвращается un_id – внутренний уникальный идентификатор объявления. Значение un_id необходимо сохранить в вашей системе для дальнейшей работы с данным объявлением.
boards – количество досок объявлений, на которые будет происходить размещение. Зависит от выбранной схемы размещения (skhema в методе get_fields).
В полях warnings и errors выводятся предупреждения и ошибки, которые могут возникнут при подаче объявления.

post_adv

Ссылка: http://api.onboard24.ru/rest/v1/post_adv/
Тип запроса: POST
Используется для передачи объявления в размещение через отправку в запросе un_id = ID. Внимание! При использовании метода post_adv происходит снятие средств с вашего баланса в Кабинете onboard24.ru, равное величине стоимости размещения объявления за вычетом скидки (если такая установлена Администрацией).
ID – уникальный идентификатор объявления в системе onboard24.ru, полученный в методе new_adv.

Формат успешного ответа:


{
  "success": {
    "balance_before": 1323.11,
    "cost": 155,
    "balance_after": 1168.11
  },
  "warnings": null,
  "errors": null
}

Поля структуры ответа метода post_adv:
balance_before, balance_after – баланс в Кабинете на сайте onboard24.ru до и после оплаты.
cost – стоимость размещения объявления в зависимости от выбранной схемы и скидки (если установлена Администратором). Величину вашей скидки вы можете узнать в методе balance.
При передаче объявления в размещение для него автоматически создается почтовый ящик на одном из наших поддоменов. Данный почтовый ящик используется для всех необходимых действий, проводимых с объявлением во время размещения (подтверждения подачи, авторизации и т.д.). Получить доступ к ящику можно с помощью метода view_adv после оплаты размещения. Ящик создается один с привязкой к е-мейлу или телефонному номеру (если е-мейл не передан). Вход в ящик осуществляется через mail.yandex.ru.

get_adv_status

Ссылка: http://api.onboard24.ru/rest/v1/get_adv_status/ID
Тип запроса: GET
Используется для получения статуса объявления в системе, количества размещенных досок и ссылок на сайты с уже размещенным объявлением.
Применяется только для оплаченных объявлений.

Формат успешного ответа:


{
  "status": "in_process",
  "count": 47,
  "total": 50,
  "links": [
    {
      "boardname": "someboard.ru",
      "linkurl": "http://***.html"
    },
	...
  ]
}

Поля структуры ответа метода get_adv_status:
status – текущий статус объявления. Может принимать значения: new (размещение еще не начиналось), in_process (объявление размещается), ready (объявление размещено на требуемом количестве досок), unpayed (объявление не оплачено);
count – количество размещенных объявлений;
total – требуемое количество размещений;
links – массив, содержащий название доски и прямую ссылку на объявление.

view_adv

Ссылка: http://api.onboard24.ru/rest/v1/view_adv/ID
Тип запроса: GET
Используется для получения информации по объявлению с айди ID.
Формат успешного ответа:


{
  "un_id": "13740377023",
  "data_adv": "2016-07-17",
  "total": "99",
  "your_total": "79.2",
  "boards": "50",
  "ishop": "1",
  "ishop_regions": "[\"15\",\"16\",\"22\"]",
  "category": "1",
  "buysell": "1",
  "advhead": "Сарафаны и туники. Коллекция жаркого лета",
  "advtext": "За окном жаркое лето, а значит, самое время для легких, струящихся нарядов. Наша компания презентует коллекцию жаркого лета – летних женских сарафанов и туник. Качественные ткани, изящество силуэтов и стильные образы – это основа женской одежды от производителя. \r\nЧтобы приобрести сарафан или тунику из модной коллекции женской одежды, достаточно просмотреть каталог женской летней одежды и заказать понравившийся вариант. Для тех, кто желает купить женскую одежду оптом, в каталоге имеется оптовая цена.",
  "price": "210",
  "currency": "RUB",
  "period": "2",
  "pic1": "http://***-1.jpg",
  "pic2": "http://***-2.jpg",
  "pic3": "http://***-3.jpg",
  "regemail": "***@***",
  "reglogin": "***",
  "regpwd": "***",
  "username": "Олег",
  "company": "Одежда для всех",
  "region": "77",
  "city": "Москва",
  "tel1": "1234567",
  "tel2": "1234567",
  "tel3": "1234567",
  "email": "dre****@gmail.com",
  "site": "dre***.ru",
}

Поля структуры ответа метода view_adv:
un_id – айди объявления в системе onboard24.ru;
data_adv – дата занесения объявления в систему;
total – полная стоимость размещения объявления (берется из skhema в методе get_fields);
your_total – стоимость размещения объявления с учетом вашей скидки (если задана Администрацией);
boards – количество досок, на которое будет произведено размещение (берется из skhema в методе get_fields);
ishop – признак того, что производится размещение по регионам Украины;
ishop_regions – массив регионов Украины, по которым производится размещение;
category – категория объявления (см. метод get_fields );
buysell – тип объявления (см. метод get_fields );
advhead – заголовок объявления;
advtext – текст объявления;
price – цена в объявлении;
currency – валюта объявления (см. метод get_fields );
period – период размещения объявления (см. метод get_fields );
pic1, pic2, pic3 – ссылки на изображения;
regemail, reglogin, regpwd – е-мейл, логин и пароль, используемые при размещении (отображаются только у оплаченных объявлений);
username – имя в объявлении;
company – название компании;
region – основной регион объявления (область Украины);
city – город объявления;
tel1, … , tel3 – код города/оператора и номер телефона в объявлении;
email – е-мейл заказчика (в объявлении не публикуется, используется для идентификации регистрационных данных);
site – сайт в объявлении.

В данном примере показаны поля для типового объявления раздела “Товары”. Список всех возможных полей доступен в методе get_fields.

balance

Ссылка: http://api.onboard24.ru/rest/v1/balance/
Тип запроса: GET
Используется для получения текущего баланса на счете на сайте onboard24.ru.
Формат успешного ответа:


{
  "success": {
    "balance": 5268.11,
    "credit": "-100",
    "discount": 0.15,
    "api": "1"
  }
}

Поля структуры ответа метода balance:
balance – сумма на текущем счете сайта onboard24.ru;
credit – кредитный лимит (допустимая сумма долга на текущем счете);
discount – величина скидки в системе;
api – признак того, что работа с АПИ-интерфейсом активна.

get_fields

Ссылка: http://api.onboard24.ru/rest/v1/get_fields/
Тип запроса: GET
Используется для получения справочников, используемых при подаче объявлений.
Формат успешного ответа:


{
  "skhema": {
    "1": {
      "total": "155",
      "boards": "15",
      "title": "Эконом"
    },
	...
  },
  "ru_regions": {
    "1": "Адыгея",
    "2": "Башкортостан",
    "3": "Бурятия",
	...
  },
  "buysell": {
    "1": {
      "1": "Продам",
      "2": "Куплю"
    },
	...
  },
  "category": {
    "1": "Товары",
    "2": "Услуги",
	...
  },
  "currency": {
    "RUB": "Рубль",
	...
  },
  "period": {
    "1": "Неделя",
    "2": "Месяц",
	...
  },
  "fields": {
    "advhead": "Заголовок",
    "advtext": "Текст объявления",
    "price": "Цена",
	...
  },
  "required_fields": [
    "buysell",
    "advhead",
    "advtext",
	...
  ]
}

Поля структуры ответа метода balance:
skhema – доступные схемы размещений (total – стоимость, boards – количество досок в схеме, title – название схемы);
buysell – тип объявления;
category – категория объявления;
currency – валюта в стоимости объявления;
period – срок размещения;
fields – все допустимые поля при подаче или при просмотре содержимого объявления;
required_fields – обязательные поля при подаче объявления.

get_boards

Ссылка: http://api.onboard24.ru/rest/v1/get_boards/CAT
Тип запроса: GET
Используется для получения списка досок для категории с номером CAT. Номера категорий доступны в методе get_fields.
Формат успешного ответа:


{
  "success": {
    "site1.ru",
    "site2.ru",
	...
    "siten.ru"
  }
}

Поля структуры ответа метода balance:
site1.ru, site2.ru, … , siten.ru – адреса досок объявлений для выбранной категории CAT.

Пожалуйста, присылайте ваши вопросы и пожелания на почту info@onboard24.ru.