api.onboard — REST API onboard.net.ua interface

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

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

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

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

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

Перед началом работы с АПИ-интерфейсом необходимо пройти регистрацию на сайте onboard.net.ua/register и отправить заявку на активацию АПИ по адресу [email protected]. Подключение услуги абсолютно бесплатно. Оплата в виде аванса на внутренний счет используется только за фактические размещения.
Далее по тексту будет представлена документация по работе с методами и примеры кода на языке PHP.

Подготовка

Все запросы требуют передачи авторизационных данных в виде логина и пароля от Кабинета на сайте onboard.net.ua для идентификации текущего пользователя. Логин и пароль кодируются алгоритмом 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.onboard.net.ua/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.onboard.net.ua/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.onboard.net.ua/rest/v1/new_adv/
Тип запроса: POST
Используется для занесения нового объявления в систему onboard.net.ua. Плата на данном этапе не взимается. Объявление просто заносится в память системы и может быть передано в размещение позже.
Пример массива данных для отправки POST-запроса на заведение нового объявления:

	$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" => 21,
		"email" => '[email protected]',
		"city" => "Харьков",
		"site" => "http://somesite.ua",
		"phone" => array('+380577860845' , '+380689860845', '7860845'),
		"pic" => array(
			'http://***.jpg',
			'https://***.png',
			'http://***.jpg',
		),
	);

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

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

{
  "succsess": {
    "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": "21",
    "city": "Харьков",
    "code1": "057",
    "tel1": "7860845",
    "code2": "068",
    "tel2": "9860845",
    "email": "[email protected]",
    "site": "somesite.ua",
    "pic1": "http://***-1.jpg",
    "pic2": "http://***-2.jpg",
    "pic3": "http://***-3.jpg"
  },
  "warnings": {
    "phones": {
      "wrong_number": [
        "7860845"
      ]
    },
  },
  "errors": null
}

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

post_adv

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

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

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

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

get_adv_status

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

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

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

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

view_adv

Ссылка: http://api.onboard.net.ua/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": "UAH",
  "period": "2",
  "pic1": "http://***-1.jpg",
  "pic2": "http://***-2.jpg",
  "pic3": "http://***-3.jpg",
  "regemail": "***@***",
  "reglogin": "***",
  "regpwd": "***",
  "username": "Олег",
  "company": "Одежда для всех",
  "region": "4",
  "city": "Днепропетровск",
  "code1": "097",
  "tel1": "1234567",
  "code2": "095",
  "tel2": "1234567",
  "code3": "063",
  "tel3": "1234567",
  "email": "dre****@gmail.com",
  "site": "dre***.com.ua",
}

Поля структуры ответа метода view_adv:
un_id — айди объявления в системе onboard.net.ua;
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 — город объявления;
code1, tel1, … , code3, tel3 — код города/оператора и номер телефона в объявлении;
email — е-мейл заказчика (в объявлении не публикуется, используется для идентификации регистрационных данных);
site — сайт в объявлении.

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

balance

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

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

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

get_fields

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

{
  "skhema": {
    "1": {
      "total": "25",
      "boards": "15",
      "title": "Эконом"
    },
	...
  },
  "ua_regions": {
    "2": "Винницкая область",
    "3": "Волынская область",
    "4": "Днепропетровская область",
	...
  },
  "buysell": {
    "1": "Продам",
    "2": "Куплю",
	...
  },
  "category": {
    "1": "Товары",
    "2": "Услуги",
	...
  },
  "currency": {
    "UAH": "Гривна",
    "EUR": "Евро",
	...
  },
  "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.onboard.net.ua/rest/v1/get_boards/CAT
Тип запроса: GET
Используется для получения списка досок для категории с номером CAT. Номера категорий доступны в методе get_fields.
Формат успешного ответа:

{
  "succsess": {
    "site1.com.ua",
    "site2.com.ua",
	...
    "siten.com.ua"
  }
}

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

Пожалуйста, присылайте ваши вопросы и пожелания на почту [email protected]. Также подписывайтесь на наши новости в соцсетях: Facebook, Вконтакте.