Описание API

Всё просто

Наше API имеет всего три метода: расчёт стоимости доставки и пару справочных для поиска индекса и кода КЛАДР.

Сценарий расчёта стоимости доставки

Мы исходим из того, что покупатель знает свой почтовый индекс, на его основе наш сервис предлагает найденные населённые пункты с кодами КЛАДР. После уточнения покупателем своего населённого пункта из предложенного списка уже можно вызвать метод расчёта стоимости доставки.

Методы нашего API позволяют получить полный расчёт стоимости доставки, если о населённом пункте покупателя известны код КЛАДР и почтовый индекс. Эти два параметра необходимы одновременно, так как транспортные компании используют разнообразные идентификаторы населённых пунктов, в том числе почтовые индексы и коды КЛАДР, а соответствие между ними не всегда однозначное. Часто одним почтовым отделением обслуживаются несколько малонаселённых пунктов с разными кодами КЛАДР, или наоборот - в крупном городе, имеющим один код КЛАДР, есть множество почтовых отделений.

Сервис использует актуальную официальную базу ФИАС для получения необходимой информации о населённых пунктах и почтовых отделениях в них.

Получение кода КЛАДР по почтовому индексу

Cервис позволяет проверить корректность почтового индекса и найти коды КЛАДР и названия населённых пунктов.

Пример запроса к сервису:

http://go.ac4print.ru/info/?postcode=400002

Пример ответа сервиса:

{
    "postcode":"400002",
    "info":[
	{
	    "kladrcode":"34000001000",
	    "guid":"a52b7389-0cfe-46fb-ae15-298652a64cf8",
	    "location":"г. Волгоград, обл. Волгоградская",
	    "location_simple":"г. Волгоград",
	    "timezone":"UTC+04:00"
	}
    ]
}

Получение кода КЛАДР и почтового индекса по названию города и региона

Cервис позволяет найти коды КЛАДР и названия населённых пунктов. Регион не является обязательным параметром. Для каждого населённого пункта сервис возвращает один из наиболее популярных почтовых индексов.

Пример запроса к сервису:

http://go.ac4print.ru/info/?city=Ильёвка&region=Волгоградская

Пример ответа сервиса:

{
    "city":"Ильёвка",
    "region":"Волгоградская",
    "info":[
	{
	    "kladrcode":"34010000016",
	    "guid":"62fb72f6-68e2-4357-af06-9f9980fb8c56",
	    "postcode":"404521",
	    "location":"п. Ильевка, р-н. Калачевский, обл. Волгоградская",
	    "location_simple":"п. Ильевка",
	    "timezone":"UTC+04:00"
	},
    ]
}

Расчёт стоимости доставки

Для расчёта стоимости доставки достаточно знать почтовые индексы населённых пунктов отправителя и получателя, вес и объём посылки. Для более точного расчёта нужно знать ещё и коды КЛАДР.

Сервис позволяет получить все варианты доставки, или единственный с наименьшей стоимостью. Это удобно, например, для отображения стоимости доставки в карточке товара.

Пример запроса к сервису:

http://go.ac4print.ru/calc/?srcCity=400112&dstCity=670040&dstCityKladr=03000001000&weight=1.4&volume=0.2&insurancePrice=1000&date=2018-06-15&isPickUp=0&isDelivery=1&isHP=0&appKey=B9609AD5-DED9-14F3-E762-6070B1DD120F

Пример ответа сервиса:

{
    "srcCity":"400112",
    "dstCity":"670040",
    "dstCityKladr":"03000001000",
    "weight":"1.4",
    "volume":"0.2",
    "insurancePrice":"3000",
    "date":"2020-05-29",
    "isPickUp":"0",
    "isDelivery":"1",
    "isHP":"0",
    "appKey":"B9609AD5-DED9-14F3-E762-6070B1DD120F",
    "srcCityKladr":"34000001000",
    "srcCityGuid":"a52b7389-0cfe-46fb-ae15-298652a64cf8",
    "dstCityGuid":"9fdcc25f-a3d0-4f28-8b61-40648d099065",
    "srcCityName":"г. Волгоград, обл. Волгоградская",
    "dstCityName":"г. Улан-Удэ, Респ. Бурятия",
    "srcCityNameSimple":"г. Волгоград",
    "dstCityNameSimple":"г. Улан-Удэ",
    "srcTimezone":"UTC+04:00",
    "dstTimezone":"UTC+08:00",
    "delivery":{
	"dellin":{
	    "0":{
		"id":"COURIER#",
		"name":"курьером до подъезда",
		"address":"",
		"time":13,
		"time_full":14,
		"price":3199,
		"info":"Курьер доставит вашу посылку до двери.",
	    },
	    "title":"Деловые линии",
	    "transfer":"2020-05-29",
	    "transfer_text":"Отправка сегодня до 18:00",
	    "total_time":4.559015
	},
	"jde":{
	    "0":{
		"id":"COURIER#",
		"name":"курьером до подъезда",
		"address":"",
		"time":19,
		"time_full":20,
		"price":2363
		"info":"Курьер доставит вашу посылку до двери.",
	    },
	    "title":"Желдорэкспедиция",
	    "transfer":"2020-05-29",
	    "transfer_text":"Отправка сегодня до 18:00",
	    "total_time":0.749245
	}
	"cdek":{
	    "0":{
		"id":"COURIER#233",
		"name":"курьером до подъезда",
		"address":"",
		"time":20,
		"time_full":21,
		"price":4910,
		"tariff_name":"Экономичная посылка склад-дверь",
		"info":"Доставка посылки производится до пункта выдачи заказов в ближайшем населённом пункте.",
	    },
	    "title":"СДЭК",
	    "transfer":"2020-05-29",
	    "transfer_text":"Отправка сегодня до 18:00",
	    "total_time":1.468121
	},
    }
}

Для получения информации о доставке с наименьшей стоимостью в запрос необходимо добавить параметр min, при этом в выдаче исключаются способы доставки самовывозом со своих складов.

Параметр "date" не обязательный, если он отсутствует, то расчёт стоимости и сроков доставки осуществляется текущим временем отправителя.
Параметр "date" может быть заменён на "transferDuration", который сообщает дополнительное время в часах необходимое магазину для передачи груза представителю транспортной компании. При этом, сервис произведёт расчёт даты передачи в транспортую компанию с учётом рабочего времени, выходных, сокращённых и праздничных дней.

Если в запросе присутствует параметр "danger", то сервис отфильтрует варианты доставки, которые не подходят для доставки опасных грузов.