Skip to content

Instantly share code, notes, and snippets.

@jellyninjadev

jellyninjadev/bazarpnzAPI.md

Last active August 29, 2015 14:02
Show Gist options
  • Save jellyninjadev/320094e97c7b4fad5599 to your computer and use it in GitHub Desktop.
Save jellyninjadev/320094e97c7b4fad5599 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
bazarpnzAPI.md

BazarPNZ

Ревизия 38.

API представляет собой statless RESTfull интерфейс для работы мобильного приложения. Префикс всех запросов api/, пример http://bazarpnz.ru/api/sections/1. Все запросы с аутентификацией желательно проводить используя HTTPS, иначе вся схема безопасности не имеет смысла. формат даты: 2014-06-22T18:34:15.012Z. Каждый запрос к апи имеет сам запрос(Request), ответ(Response). В случае если запрос-ответ не указан, имеется ввиду ответ.

Оглавление

  • Формат ошибок
  • Коды ошибок
  • Сущности
  • АПИ

Формат ошибок

{
	"error": {
		"message": "Error message text",
		"status": 404
	}
}

Коды ошибок

Коды ошибок соответствуют стандарту RFC 7231 если не описаны иначе.

200 ок

204 No content

400 Bad request

404 Not found

500 Server error

Сущности

Categories

(или рубрики по другому)

Featured - выделенные категории Age - ограничение по возрасту

  • id: integer
  • title: string
  • count: integer
  • thumbnail: url/to/image
  • categories: [category, category, ...]
  • featured: true
  • age: 18

АПИ

GET /sections

Показать все рубрики.

Response

{
	"sections" : [
		{
			"id": 123,
			"thumbnail": "path/to/image",
			"title": "Продажа автомобилей",
			"paid": 1,
			"type": "estate",
			"count": 15453,
			"featured": 20,
			"featured_cat" : 40,
			"categories": [
				{ 
					"id": 13, 
					"title": "Недвижимость", 
					"count": 150,
					"featured": 20,
					"featured_cat" : 40,
					"age": 18,
					"thumbnail": "path/to/image",
					"categories": [
						{...}, {...}
					]
				}
			],
		},
		{...}
	],
	"updated_at": "2014-06-22T18:34:15.012Z"
}
  • type - может быть auto, estate, other, resume

GET /sections/:id/counts

  • id - id родителя

Response

{
	"categories": [{
		"id": 3,
		"count": 300
	}, {...}],
	"updated_at": "2014-06-22T18:34:15.012Z"
}
  • id - id подкатегории

Если массив пустой то идет запрос на список объявлений (постов)

Request

  • type - может быть auto, estate, other, resume

GET /posts

Отфильтровать по следующим параметрам

Request

{
	"category_id": 345,
	"adv_type": 1,
	"district": 2,
	"price_min": 566,
	"price_max": 3576,
	"with_photo": 1,
	"type": "estate",
	"estate": {
		// estate, auto, other, simple, resume
	}

}
  • category_id = id рубрики

В зависимости от типа значение и объект меняется на следующие

Estate

Дополнительные параметры для недвижимости

{
	"area": {/* coords or street */},
	"rooms": 4,
	"living_size": 46,
	"main_size": 45
}

Auto

Для авто

{
	"marka": "sthntsdth", // mark
	"kuzov": 23,
	"gv_from": "YYYY",
	"gv_to": "YYYY",
	"typ_dvig": 1,
	"stock": 1,
	"kpp": 1, 
	"probeg": 324
}

Other

Если остальные, то нет дополнительных опций.

Simple

Упрощенные для айпада, только type_adv

GET /category/:id/posts/:last_post

Показать 30 постов у категории.

id - id категории last_post - номер объявления последнего в списке

Если "noposts": 1 то если следующих постов нет. В обычном случае noposts не передается.

Сортировка по id поста

Response

{
	"noposts": 1, 
	"posts": [{
		"id": 123,
		"thumbnail": "path/to/image",
		"title": "Магазин запчасией для иномарок",
		"price": {
			"rub": 500
		},
		"selected": 1,
		"showcase": 0,
		"attached": 1,
		"date":  "2014-06-22T18:34:15.012Z"
	}],
	"type": "estate"
}
  • type - тип категории, может быть auto, estate, other, simple, resume

Обнулить счетчики у поста

GET /posts/:id/reset-counters

Request

{
	"access_token": "string"
}

Response 204 No content

Показать посты витрины

GET /showcase/:id/posts/:last_post_id

Response

{
	"noposts": 0,
	"posts": [{
		"id": 123,
		"thumbnail": "path/to/image",
		"title": "Магазин запчасией для иномарок",
		"price": {
			"rub": 500
		},
		"selected": 1,
		"attached": 1,
		"date": "2014-06-22T18:34:15.012Z" 
	}, {...}],
	"type": "estate"
}

GET /posts/:id

Response

{
	"id": 123,
	"url": "http://url/to/post",
	"type": "auto",
	"active": 1,
	"type_adv":1,
	"credit": 0,
	"showcase": 0,
	"owner_id": 3,
	"images": [
		{
			"thumb": "path/to/image",
			"large": "path/to/image",
		}, 
		{
			"thumb": "path/to/image",
			"large": "path/to/image"
		},
		{...}
	],
	"title": "Продам резонатор ВАЗ 2110 (подходит на приору седан)",
	"desc": "Новинка! в наличии газо-маслянные...",
	"breadcrumbs":[
		{
			"title": "Авто",
			"id": 334,
		}, {
			"title": "Автозапчасти и принадлежности",
			"id": 554,
		}
	],
	"price": {
		"rub": 500
	},
	"date_created": "2014-06-22T18:34:15.012Z",
	"date_post": "2014-06-22T18:34:15.012Z",
	"date_updated": "2014-06-22T18:34:15.012Z",
	"date_end": "2014-06-22T18:34:15.012Z",
	"views": 6,
	"contacts": {
		"type": "company/user"
		...,
	},
	"characteristics": {
		// estate, auto, other, simple, resume
		}
}

type - авто, недвижимость, разное, resume type_adv - тип объявления: Продам, Куплю, Меняю auto может быть estate(недвижимость) и other. url - ссылка на объявление characteristics - дополнительные поля credit - возможность покупки в кредит

characteristics - Auto

	{
		"marka":"Acura",
        "model":"CL",
        "gv":2005,
        "sost":1,
        "hod":1,
        "customs":1,
        "color":30,
        "kuzov":6,
        "typ_dvig":2,
        "privod":3,
        "kpp":2,
        "rul":1,
        "pts":2,
        "stock":1,
        "obmen":4,
        "probeg": 4591,
		"options": {
			"abs":1,
			"abuks":1,
			"comp":1,
			"gbo":0,
			"d_rain":1,
			"d_light":1,
			"cruis":1,
			"csenon":1,
			"lit_disk":1,
			"lyk":1,
			"mag":2,
			"navi":1,
			"ob_zerkal":1,
			"ob_rulya":1,
			"ob_siden":1,
			"om_far":0,
			"ohr_syst":1,
			"parkt":1,
			"pod_bez":3,
			"regs_vod":3,
			"regs_pass":2,
			"regs_rul":2,
			"typ_salona":2,
			"sys_kurstab":1,
			"clymat":1,
			"usil_rul":1,
			"centr_zam":1,
			"el_zerk":1,
			"el_pod_stek":1
		}
	}

characteristics - Estate

{
	"area": {/* coords or street */},
	"living_size": 46,
	"main_size": 45,
	"subheading": 1,
	"town": 3,
	"street": 2,
	"flor": 3,
	"numberOfFloors": 3,
	"rooms": 3,
	"planning": 3,
	"totalArea": 4,
	"floorArea": 2,
	"kitchenArea": 2,
	"ceilingHeight": 3,
	"state": 2,
	"yearBuilt": 2,
	"materialOfConstruction": 3,
	"heating": 2,
	"bathroom": 3,
	"balcony": 2,
	"options": {
	 	"gas": 1,
	 	"hot_water": 1,
	 	"cold_water": 1,
	 	"sewage": 1,
	 	"elevator": 1,
	 	"internet": 1,
	 	"phone": 1,
	 	"garage": 1,
	 	"cellar": 1,
	 	"basement": 1
	}
}

characteristics - Other

{
	"title": "lalala",
	"category_id": 4
}

Если other то дополнительных полей нет.

Главное изображение - первое в списке.

В блоке contacts выводится соответствубщая сущность.

characteristics - Resume

{
	"rub_select": "Администраторы",
	"bd_year": "1994",
	"sex": "Мужской",
	"nationality": "Россия",
	"family": "Женат/Замужем",
	"kids": 0,
	"education": "Высшее",
	"speciality": "Специальность текста",
	"other_lang": "Язык",
	"computer": "Не работа",
	"driver": 0,
	"main_experience": 25,
	"spec_experience": 9,
	"direct_experience": 5,
	"add_prof_education": "Text",
	"add_education": "Text"
}
Contacts

тип Витрина

{
	"type": "company",
	"id": 12344,
	"thumbnail": "path/to/image",
	"img": "path/to/image",
	"name": "Магазин автозапчестей",
	"description": "Огромный выбор автозапчастей...",
	"phone_primary": "9022042505",
	"phones_secondary": "89022042505",
	"available_time": "c 5 до 7",
	"city": "Пенза",
	"district": "Шуист",
	"address": "ул. Красная, д. 5, кв. 6",
	"email": "avtovagrantmail.com"
}

тип Пользователь

{
	"type": "user",
	"id": 12344,
	"name": "Андрей",
	"city": "Пенза",
	"district": "Шуист",
	"phones":
		[
			"89022042505",
			"89022042250"
		],
	"skype":"my_skype"
}
Characteristic

тип Авто (auto)

Создание нового объявления

POST /posts

Request

{
	"type": "auto",
	"type_adv":1,
	"title": "Продам резонатор ВАЗ 2110 (подходит на приору седан)",
	"desc": "Новинка! в наличии газо-маслянные...",
	"category_id": 123, // авто
	"price": {
		"rub": 500
	},
	"period": 1,
	"credit": 1,
	"contacts": {
		"type": "company/user"
		...,
	},
	"timetocalldesc":"Звонить с 9 до 19 кроме выходных",
	"characteristics": {
		// cущность characteristics
	},
	"paid_code": 23456
}
  • category_id - id конечной рубрики

Объявление передается через multipart form data под переменной post. В этой переменной содержится json объявления (все кроме изображений). Каждое изображение передается как переменная image[0], где 0 индекс изображения. Ограничение на количество картинок - 7.

Конечный запрос будет выглядеть в таком виде

POST /posts HTTP/1.1 Host: 192.168.22.10 Cache-Control: no-cache

----WebKitFormBoundaryE19zNvXGzXaLvS5C Content-Disposition: form-data; name="image[0]"; filename="image.jpg" Content-Type: image/jpeg

----WebKitFormBoundaryE19zNvXGzXaLvS5C Content-Disposition: form-data; name="image[1]"; filename="image.jpg" Content-Type: image/jpeg

----WebKitFormBoundaryE19zNvXGzXaLvS5C Content-Disposition: form-data; name="post"

{ "type": "auto", "type_adv":1, "title": "Продам резонатор ВАЗ 2110 (подходит на приору седан)", "desc": "Новинка! в наличии газо-маслянные...", "category_id": 123, // авто "price": { "rub": 500 }, "period":"1m", "credit": 1, ...} ----WebKitFormBoundaryE19zNvXGzXaLvS5C

Response

{
	"id": 34,
	"type": "auto",
	"type_adv":1,
	"images": [
			{"large": "path/to/image"},
			{"large": "path/to/image"},
			...
	],
	"queue": 334,
	"url": "http://path/to/url",
	"title": "Продам резонатор ВАЗ 2110 (подходит на приору седан)",
	"desc": "Новинка! в наличии газо-маслянные...",
	"category_id": 123, // авто
	"price": {
		"rub": 500
	},
	"period":"1m",
	"credit": 1,
	"contacts": {
		"type": "company/user"
		...,
	},
	"timetocalldesc":"Звонить с 9 до 19 кроме выходных",
	"characteristics": {
		// cущность characteristics
	}
}
  • queue - номер в очереди объявления

после получения каждая images пережимается в large(большую) и мальнекую(thumb)

Errors В случае если пошли какие либо ошибки

{
	"error": {
		"message": "Wrong Code",
		"status_code": 403
	}
}

POST /posts/:id

Редактирование объявления

Response

	post // сущность обьявления

GET /currency-rates

Показать курсы валют.

Response

{   
	"currency": {
		"usd": 34.3,
		"eur": 46.7
	},
	"updated_at": "2014-11-13T00:00:00Z"
}

Response

204 No Content

Продлить объявление

POST /posts/:id/extend

Request

{
	"access_token": "1234pgdt5",
	"days": 23
}

Response

204 No Content

Поднять обявление

GET /robokassa.php

Request

{
	"type": "top", 
	"phone": 79ХХХХХХХХХ,
	"id": 3
}

Получить код подъема объявления

GET /robokassa.php

{
	"type": "pay_top",
	"phone": 79ХХХХХХХХХ,
	"lot": "10"
}
  • lot - Количество кодов подъема (1..10, 15,20)

Выделение объявления

GET /robokassa.php

{
	"type": "hot", 
	"phone": 79ХХХХХХХХХ,
	"days": 3,
	"id": 3
}

Прикрепление объявления

{
	"type": "stk",
	"days": 23,
	"phone": 79ХХХХХХХХХ,
	"id": 3,
	"total": 3
}
  • total - номер рубрики (0 - на главной, 1 - во всех)

DELETE /posts/:id

Request

{
	"access_token": "1234pgdt5"
}

Response

204 No Content

POST /posts/:id/report

Response 204 No conten

GET /search

Поиск

Request

{
	"fuzzy": 1,
	"category": 1,
	"query": "rsj7l8ue"
}
  • category = 0 - по всему сайту
  • category = -1 - по номеру объявления

Response 204 No content

Вопросы и ответы

GET /support

Request

{
	"last_id": 23,
	"size": 20	
}
  • если указан last_id отдавать количество(size) с последнего last_id
  • количество вопросов к выдаче (опционален, есть смысл проверять на верхний предел, например не больше чем 60 в целях оптимизации)

Response

{
	"questions": [{
		"id": 1,
		"name": "Username",
		"text": "Я написал объявление",
		"answer": "Ответ"
	}, {...}]
}

POST /support

Request

{
	"name": "username",
	"text": "rpgjluekb",
	"email": "mailgmail.com",
	"post_id": 3465,
}

Response

{
	"id": 3,
	"name": "username",
	"text": "Question",
}

User

GET /users/self

Request

{
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA="
}

Response

{
	"id": 3,
	"name": "Андрей",
	"email": "andy32@gmail.com",
	"city": "Пенза",
	"district": "Шуист",
	"phones": [{
		"number": "+79622340535",
		"time": "с 7 до 5"
	}, {...}],
	"skype": "skype_username"
}

Registration

POST /users

Request

{
	"name": "Андрей",
	"email": "andy32@gmail.com",
	"password": "string",
	"city": "Пенза",
	"district": "Шуист",
	"phones": [{
		"number": "+79622340535",
		"time": "с 7 до 5"
	}, {...}],
	"skype": "skype_username",
	"udid": "token"
}

Response

{
	"id": 3,
	"name": "Андрей",
	"email": "andy32@gmail.com",
	"city": "Пенза",
	"district": "Шуист",
	"phones": [{
		"number": "+79622340535",
		"time": "с 7 до 5"
	}, {...}],
	"skype": "skype_username",
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"expires_in": 36000,
	"refresh_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA="
}

Authorization

Логин

POST /auth

Request

{
	"type": "password",
	"email": "andy32@gmail.com",
	"password": "string",
	"udid": "string"
}

Response

{
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"refresh_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"expires_in": 36000
}

Request new token

POST /auth

Request

{
	"type": "token",
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"udid": "string"
}

*udid - device token

Response

{
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"refresh_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA=",
	"expires_in": 36000
}

Password reminder

POST /remind

Request

{
	"email": "andy32@gmail.com"
}

Response 204 No Content

Posts

GET /users/self/posts

Request

{
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA="
}

Response

{
	"noposts": 1, 
	"posts": [{
		"id": 123,
		"thumbnail": "path/to/image",
		"on_moderation": 1,
		"queue": 345
		"title": "Магазин запчасией для иномарок",
		"price": {
			"rub": 500
		},
		"selected": 1,
		"showcase": 0,
		"attached": 1,
		"date":  "2014-06-22T18:34:15.012Z"
	}],
	"type": "estate"
}
  • queue - очередь на модерацию

запрос аналогичен запросу получить посты от категории лишь с новым полем on_moderation

Забрать список объявленить по id (мои объявления если пользователь не зарегестрирован)

GET /posts

Request

{
	"ids": [1, 2, 3, 4, 5]
}

Response

{
	"noposts": 1, 
	"posts": [{
		"id": 123,
		"thumbnail": "path/to/image",
		"title": "Магазин запчасией для иномарок",
		"price": {
			"rub": 500
		},
		"selected": 1,
		"showcase": 0,
		"attached": 1,
		"date":  "2014-06-22T18:34:15.012Z"
	}],
}

Favorites (draft)

GET /users/self/favorites

Request

{
	"access_token": "sdzc2hc/RbkY8K1WVde1CUFzJioetOcFVyCd3oNvrHA="
}

Response

{
	"showcase": [
		{
			"id": 1234,
			"img": "path/to/img",
			"name": "Magaz",
			"email": "example@mail.com",
			"addess": "Kirova",
			"city": "Moscow",
			"district": "Central",
			"phones": [98562345111],
			"detail": "Magaz number one in Europe",
			"website": "http://path/to/url",
			"type": "company"
		}, {...}
	],
	"post": [
		{
			"id": 123,
			"title": "ra43567jln",
			"thumbnail": "/path/to/img",
			"date": "2014-06-22T18:34:15.012Z"
		}, {...}
	],
	"requests": [
		{
			"title": "234567jln",
			"id": 56
			}, {...}
	]
}

204 No Content

POST /users/self/favorites

Request

{
	"access_token": "34567lnhdts",
	"type": "post",
	"id": 2, // for posts and showcase
	"request": "string"
}

Response

{
	"id": 5,
	"type": "post",
	"request": "string"
}

204 No content

POST /users/self/favorites/delete

Request

{
	"id": 123,
	"access_token": "s45678uenhd"
}

Response

204 No content

POST /users/self/favorites/deleteall

Request

{
	"access_token": "s45678uenhd"
}

Response

204 No content

Response 204 No content

Получить количество объявлений на сайте

GET /posts/count

Response

{
	"count": 3456
}
@ademkovich
Copy link

"id - id подкатегории
Если массив пустой то идет запрос на список объявлений (постов)" - удалить из API

@ademkovich
Copy link

"GET /posts" - добавить тип объявлений резюме

@ademkovich
Copy link

"{
"usd": 34.3,
"eur": 46.7,
"rub": 45
}"

Убрать параметр "rub"
Добавить параметр "updated_at": "2014-11-13T00:00:00Z" - время обновления курса валют на сайте

@ademkovich
Copy link

Добавить в объявления параметры:

Модерация(Moderation\approve\rejected)
Активность объявления(active\end)

@ademkovich
Copy link

Во всей спецификации привести телефоны пользователя к виду:

"phones": [{
"number": "+79622340535",
"time": "с 7 до 5"
}, {...}],

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment