За разработчици | Еконт | Получаване на списък с населени места, адреси и офиси, до които работи Еконт

Получаване на списък с населени места, адреси и офиси, до които работи Еконт

Въведение

За да доставим пратката точно където трябва, е необходимо да валидирате всяко населено място с базата ни данни. Според населеното място ще можете да покажете на клиентите на магазина и информация за наличните в него адреси (а при XML интеграцията – и дни, в които магазинът ще обслужи пратките им).

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

Препоръчваме ви да не позволявате на клиентите на магазина да въвеждат свободно населени места, а да ги валидирате с полученото от нашата база данни. Ако подадете заявка към нашите системи с населено място или адрес в него, който не съществува, няма да може да създадем товарителница. Ще трябва търговецът да се свърже с клиента си, за да свери информацията за доставка.

Препоръчваме да показвате падащо меню, от което клиентите да избират конкретно населено място. Препоръчваме зареждането на това падащо меню да има и анимация, показваща това зареждане (прелоудър), за да покаже, че системата извършва конкретно действие. В противен случай търговецът рискува да загуби клиент, ако по някаква причина падащото меню не се покаже коректно.

Какво получава търговецът с интеграцията

За да дадем максимална свобода при създаването на форми за поръчка, можете да получите и да кеширате при вас (или да теглите в реално време, което не препоръчваме) списък с всички населени места, до които доставяме в дадена държава.

В зависимост от начина на интеграция, който е избрал собственикът на магазина, можете да получите и допълнителна информация за населеното място: например дните за доставка, типовете пратки, които обслужваме, и др.

Важно: За да разполагате с възможно най-добре работеща интеграция и да не се налага да повторна проверка на населени места, препоръчваме да показвате падащо меню, от което клиентите на магазина да избират конкретно населено място. Препоръчваме зареждането на това падащо меню да има и анимация, показваща това зареждане (прелоудър), за да покаже, че системата на магазина извършва конкретно действие. В противен случай търговецът рискува да загуби клиент, ако по някаква причина падащото меню не се покаже коректно.

Как да използвате пощенска пратка

1. Достави с Еконт

Няма нужда от допълнително действие от ваша страна. След като сте избрали държавите, до които искате да доставяте, изборът на населено място във всяка една от тях се поема от системата.

2. Интеграция с XML

При интеграция с XML е нужно да изпращате регулярно (препоръчваме да ъпдейтвате веднъж на 24 часа) заявка към системата ни със следната структура:

<cities>
	<report_type></report_type>
	<id_zone></id_zone>
	<city_name></city_name>
	<city_name></city_name>
</cities>

Ще получите отговор, в който ще се съдържа следната информация:

id – идентификатор (ID) на населеното място
post_code – пощенски код на населеното място
type – тип на населеното място. Възможни стойности: ‘гр.’, ‘с.’
id_zone – идентификатор (ID) на зоната, в която се намира населеното място
name – име на населеното място
name_en – име на населеното място на латиница
region – име на региона, в който се намира населеното място
region_en – име на региона, в който се намира населеното място на латиница
id_country – държавата, в която попада населеното място
id_office – главният офис на обслужване на населеното място
service_days – дни на обслужване на населеното място. Дните са в полета от 1 до 7 (понеделник – неделя). Възможни стойности са ‘1’ (обслужва в дадения ден) и ‘0’ (не обслужва в дадения ден). С тази информация ще може да дадете данни на клиентите си кога могат да очакват най-рано пратките си и да си спестите излишни телефонни обаждания. Тази секция не се връща при запитване с параметър report_type = ‘short’
updated_time – време на последната редакция на записа в SQL формат (yyyy-mm-dd hh:mm:ss)
hub_code – код на офиса, Логистичен център за населеното място
hub_name – име на офиса, Логистичен център за населеното място
hub_name_en – име на латиница на офиса, Логистичен център за населеното място
courier_request_begin_time – начало на работното време за заявки за куриер
courier_request_begin_time_saturday - начало на работното време за заявки за куриер в събота
courier_request_end_time – край на работното време за заявки за куриер
courier_request_end_time_saturday – край на работното време за заявки за куриер в събота. С тази информация отново можете да дадете допълнителни данни на клиентите на магазина, например за това дали ще могат да получат пратката си в събота, и до колко часа
attach_offices – офиси, които обслужват населеното място. Тази секция не се връща при запитване с параметър report_type = ‘short’
courier_shipments – офиси, които обслужват куриерски пратки
cargo_palet_shipments – офиси, които обслужват карго палет пратки (пратки на код 82, 84, 87)
cargo_expres_shipments – офиси, които обслужват карго експрес пратки (пратки на код 81, 83)
post_shipments – офиси, които обслужват пощенски пратки
from_door – офиси, които вземат пратки от адрес на клиента
from_office – офиси, които приемат пратки от рецепция
to_door – офиси, които доставят пратки до врата на клиента
to_office – офиси, които предават пратки от рецепция
office_code – код на офиса, който обслужва съответния тип пратки според начина на доставка

Примерен XML отговор:

<response>
	<cities>
		<e>
			<id></id>
			<post_code></post_code >
			<type></type>
			<id_zone> </id_zone>
			<name> </name>
			<name_en> </name_en>
			<region> </region>
			<region_en> </region_en>
			<id_country> </id_country>
			<id_office> </id_office>
			<service_days>
				<day1></1>
				<day2></2>
				<day3></3>
				<day4></4>
				<day5></5>
				<day6></6>
				<day7></7>
			</service_days>
			<updated_time></updated_time>
			<hub_code></ hub_code>
			<hub_name></ hub_name>
			<hub_name_en></ hub_name_en>
			<courier_request_begin_time></ courier_request_begin_time>
			<courier_request_begin_time_saturday></ courier_request_begin_time_Saturday>
			<courier_request_end_time></ courier_request_end_time>
			<courier_request_end_time_saturday></ courier_request_end_time_saturday>
			<attach_offices>
				<courier_shipments>
					<from_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_door>
					<from_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_office>
					<to_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_door>
					<to_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_office>
				</courier_shipments>
				<cargo_palet_shipments>
					<from_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_door>
					<from_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_office>
					<to_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_door>
					<to_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_office>
				</cargo_palet_shipments>
				<cargo_expres_shipments >
					<from_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_door>
					<from_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_office>
					<to_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_door>
					<to_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_office>
				</cargo_expres_shipments >
				<post_shipments >
					<from_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_door>
					<from_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</from_office>
					<to_door>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_door>
					<to_office>
						<office_code></office_code>
						<office_code></office_code>
						<office_code></office_code>
					</to_office>
				</post_shipments >
			</attach_offices>
		</e>
		<e>
		…
		</e>
	</cities>
</response>

3. Интеграция със SOAP/JSON

За да извлечете списък с населени места в държавите, които обслужва магазинът, ползвайте метода getCities с параметър код на държавата (countryCode – който съдържа ISO Alpha-3 кода на всяка държава – например BGR, GRE и др.).

Стойност	Описание
cities	Списък с всички градове в исканите държави

В отговора се съдържа и информация за населеното място, в която влиза:

id – ID на населеното място
postCode – пощенски код на населеното място
name – име на населеното място
nameEn – име на населеното място на латиница
phoneCode – телефонен код на населеното място
location – местоположение (GPS координати) на населеното място
expressCityDeliveries – позволяват ли се експресни доставки в рамките на населеното място

Примерна JSON заявка:

{
		"countryCode":"LUX"
}

Примерен JSON отговор:

{
	"cities": [
		{
			"id": 204964,
			"country": {
				"id": null,
				"code2": "LU",
				"code3": "LUX",
				"name": "Люксембург",
				"nameEn": "Luxembourg",
				"isEU": true
			},
			"postCode": "0",
			"name": "LUXEMBOURG",
			"nameEn": "LUXEMBOURG",
			"regionName": "",
			"regionNameEn": "",
			"phoneCode": "0",
			"location": null,
			"expressCityDeliveries": false
		},
		{
			"id": 204965,
			"country": {
				"id": null,
				"code2": "LU",
				"code3": "LUX",
				"name": "Люксембург",
				"nameEn": "Luxembourg",
				"isEU": true
			},
			"postCode": "0",
			"name": "ESCH LALLANGE",
			"nameEn": "ESCH LALLANGE",
			"regionName": "",
			"regionNameEn": "",
			"phoneCode": "0",
			"location": null,
			"expressCityDeliveries": false
		}
	]
}

4. Интеграция с модул за платформа за електронна търговия

Подобно на Достави с Еконт, ако ползвате модул за интеграция с готова платформа за електронна търговия, не е нужно да конфигурирате каквото и да било при извличането на населени места. Вече сме го направили вместо вас. Трябва само да изберете държавите, до които търговецът иска да доставя продуктите си сред тези, в които доставя Еконт.