За разработчици | Еконт | Създаване на документ за изпращане (товарителница)

Създаване на документ за изпращане (товарителница)

Въведение

Автоматичното създаване на товарителница е едно от основните предимства на интеграцията на магазина със системата на Еконт. По този начин търговецът ограничава до минимум възможността за грешка при доставка на артикули от магазина и спестява ресурс за ръчно попълване на данните.

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

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

При подаването на успешна заявка за създаване на товарителница, търговецът получава следните предимства:

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

Как да използвате тази функционалност

За да генерирате успешно товарителница, трябва да разполагате със следната информация:

Валидирани с нашата система място за изпращане и място за получаване. Валидацията включва:

Местоположение на изпращане (офис или Еконтомат с правилен код, валиден адрес, сравнен с наличните в базата ни данни)
Време на изпращане и получаване (т.е. да сте проверили дали в избраните дни и часове за получаване и изпращане на пратките куриерите и офисите ни работят)

Информация за пратката

Брой части и описание
Валидни типове услуги, които искате да използвате на база формата на пратката, местата на изпращане и получаване и свързаните допълнителни услуги
Валидни допълнителни услуги, които да добавите към доставката (например Преглед, тест и избор)

Валидно Указание за връщане на пратката в случай на частична доставка или отказана доставка

Как да валидирате информацията, вижте тук.

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

Генерираните за пратките товарителници можете да видите и да разпечатате директно в PDF файл във формат, избран през настройките на Достави с Еконт.

Форматът на товарителницата може да редактирате в меню Настройки, секция Общи настройки, секция Вид на транспортни етикет. Може да избирате между А4, 15х10 см. и 10х9 см. като формати.

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

Номер на товарителница. Това означава, че за дадената пратка е генерирана товарителница в избрания от вас формат, която може да достъпите като кликнете с линка на номера ѝ. Ако последвате препратката в съседната колона Доставка можете да проследите и статуса на самата пратка, както и дали е доставена до клиента
Препратка „изпрати“, което означава, че пратката все още не е подготвена. При клик на тази препратка ще генерираме товарителница, в която дата на изпращане ще бъде първата възможна според конфигурацията на самата пратка (например, ако натиснете бутона в събота вечер, при избрана конфигурация изпращане от Офис на Еконт, товарителницата ще бъде подготвена с дата на изпращане понеделник от дадения офис)

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

За да генерирате товарителница с Достави с Еконт е необходимо:

Да имате конфигуриран магазин в Достави с Еконт (виж Внедряване на Достави с Еконт в електронния магазин или Внедряване на Достави с Еконт в статични сайтове (бутон Достави с Еконт))
Да сте интегрирали формата за поръчки (виж Внедряване на Достави с Еконт в електронния магазин или Внедряване на Достави с Еконт в статични сайтове (бутон Достави с Еконт))

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

За да генерирате товарителница посредством XML интеграция, трябва да изпратите XML заявка със следната структура:

Системни настройки (<system>), виж Системни настройки
Потребител в e-Econt (<client>)
Пратка с информация за нея (секция <loadings>, като всяка отделна пратка – ако генерирате повече от една накуп, следва да бъде отделена в отделен таг <row>):

Върната пратка (<returned_loading>)
Подател (<sender>), виж Данни за подател
Получател (<receiver>), виж Данни за получател
Заявка за куриер (ако е налична такава) (<courier_request>), Виж Автоматизиране на заявка за куриер
Начин на плащане на пратката (т.е. коя страна колко ще плати - <payment>), Виж Плащане на пратката
Информация за товарителницата (<shipment>), виж Как изглежда една заявка за пратка към Еконт
Допълнителни услуги (<services>), виж Допълнителни варианти за търговците и клиентите – като в тази секция е наличен и Наложеният платеж (виж Наложен платеж)
Указания (<instructions>) – виж Указания към куриер, доставящ пратката и Указания за връщане на пратка
Опис на пратката (ако има такъв - <packing_list>) – виж Преглед, тест и избор
Тегло на пратката
Брой части на пратката
Тип на пратката (виж Типове пратки, с които искате да доставяме поръчките на магазина)

Пълният код за заявка на товарителница може да изглежда така:

<?xml version="1.0"?>
<parcels>
	<system>
		<validate>0</validate>
		<response_type>HTML</response_type>
		<only_calculate>0</only_calculate>
		<process_all_parcels>1</process_all_parcels>
		<e-mail_errors_to></e-mail_errors_to >
	</system>
	<client>
		<username></username>
		<password></password>
	</client>
	<loadings>
	<row>
		<returned_loading>
			<first_loading_num></first_loading_num>
			<first_loading_receiver_phone></first_loading_receiver_phone>
			</returned_loading>
		<sender>
			<country_code></country_code>
			<city></city>
			<post_code></post_code>
			<office_code></office_code>
			<name></name>
			<name_person></name_person>
			<e-mail></e-mail>
			<quarter></quarter>
			<street></street>
			<street_num></street_num>
			<street_bl></street_bl>
			<street_vh></street_vh>
			<street_et></street_et>
			<street_ap></street_ap>
			<street_other></street_other>
			<phone_num></phone_num>
			<e-mail_on_delivery></e-mail_on_delivery>
		</sender>
		<receiver>
			<country_code></country_code>
			<city></city>
			<post_code></post_code>
			<address_zip></address_zip>
			<office_code></office_code>
			<name></name>
			<name_person></name_person>
			<e-mail></e-mail>
			<quarter></quarter>
			<street></street>
			<street_num></street_num>
			<street_bl></street_bl>
			<street_vh></street_vh>
			<street_et></street_et>
			<street_ap></street_ap>
			<street_other></street_other>
			<phone_num></phone_num>
			<sms_no></sms_no>
			<bic></bic>
			<iban></iban>
			<provider_id></provider_id>
		</receiver>
		<courier_request>
			<only_courier_request></only_courier_request>
			<time_from></time_from>
			<time_to></time_to>
		</courier_request>
		<payment>
			<side></side>
			<method></method>
			<receiver_share_sum></receiver_share_sum>
			<share_percent></share_percent>
			<key_word></key_word>
		</payment>
		<shipment>
			<envelope_num></envelope_num>
			<shipment_type></shipment_type>
			<description></description>
			<pack_count></pack_count>
			<weight></weight>
			<tariff_code></tariff_code>
			<tariff_sub_code></tariff_sub_code>
			<invoice_before_pay_CD></invoice_before_pay_CD>
			<pay_after_accept></pay_after_accept>
			<pay_after_test></pay_after_test>
			<send_date></send_date>
			<delivery_day></delivery_day>
			<size_under_60cm></size_under_60cm>
			<order_num></order_num>
			<keep_upright></keep_upright>
		</shipment>
		<services>
			<p type=""></p>
			<e></e>
			<e1></e1>
			<e2></e2>
			<e3></e3>
			<dc></dc>
			<dc_cp></dc_cp>
			<dp></dp>
			<irregular></irregular>
			<pack1></pack1>
			<pack2></pack2>
			...
			<pack12></pack12>
			<ref></ref>
			<sms_notification></sms_notification>
			<oc></oc>
			<oc_currency></oc_currency>
			<money_transfer></ money_transfer >
			<money_transfer_express></money_transfer_express>
			<cd type=""></cd>
			<cd_currency></cd_currency>
			<cd_agreement_num></cd_agreement_num>
			<cd_pay_options>
				<name></name>
				<phone></phone>
				<e-mail></e-mail>
				<money_transfer></money_transfer>
				<express></express>
				<method>bank</method>
				<BIC></BIC>
				<IBAN></IBAN>
				<bank_currency></bank_currency>
				<pay_schedule_type></pay_schedule_type>
				<pay_date></pay_date>
				<pay_weekday_1></pay_weekday_1>
				<pay_weekday_2></pay_weekday_2>
				...
				<pay_weekday_5></pay_weekday_5>
				<office_code></office_code>
				<city></city>
				<post_code></post_code>
				<quarter></quarter>
				<street></street>
				<street_num></street_num>
				<other></other>
				<instruction></instruction>
			</cd_pay_options>
		</services>
		<instructions>
			<e>
				<template></template>
			</e>
			<e>
				<type>take</type>
				<title></title>
				<description></description>
				<file_name></file_name>
				<file_content></file_content>
			</e>
			<e>
				<type>give</type>
				<title></title>
				<description></description>
				<file_name></file_name>
				<file_content></file_content>
			</e>
			<e>
				<type>return</type>
				<days_until_return></days_until_return>
				<delivery_fail_action></delivery_fail_action>
				<dp_ap></dp_ap>
				<dp_bl></dp_bl>
				<dp_city></dp_city>
				<dp_post_code></dp_post_code>
				<dp_e-mail></dp_e-mail>
				<dp_et></dp_et>
				<dp_face></dp_face>
				<dp_name></dp_name>
				<dp_office></dp_office>
				<dp_office_code></dp_office_code>
				<dp_other></dp_other>
				<dp_payment_side></dp_payment_side>
				<dp_phone></dp_phone>
				<dp_quarter></dp_quarter>
				<dp_return_to></dp_return_to>
				<dp_street></dp_street>
				<dp_street_num></dp_street_num>
				<dp_type></dp_type>
				<dp_vh></dp_vh>
				<print_return_loading></print_return_loading>
				<reject_delivery_payment_side></reject_delivery_payment_side>
				<reject_return_payment_side></reject_return_payment_side>
				<return_ap></return_ap>
				<return_bl></return_bl>
				<return_city></return_city>
				<return_post_code></return_post_code>
				<return_e-mail></return_e-mail>
				<return_et></return_et>
				<return_face></return_face>
				<return_name></return_name>
				<return_office></return_office>
				<return_office_code></return_office_code>
				<return_other></return_other>
				<return_phone></return_phone>
				<return_quarter></return_quarter>
				<return_street></return_street>
				<return_street_num></return_street_num>
				<return_vh></return_vh>
				<pd_service></pd_service>
				<pen_color></pen_color>
				<number_of_signatures></number_of_signatures>
				<page_numbers></page_numbers>
				<pd_other_instructions></pd_other_instructions>
			</e>
		</instructions>
			<packing_list>
			<partial_delivery></partial_delivery>
			<type></type>
				<row>
					<e>
						<inventory_num></inventory_num>
						<description></description>
						<weight></weight>
						<price></price>
						<file_name></file_name>
						<file_content></file_content>
					</e>
				</row>
			</packing_list>
		</row>
		<row>
		...
		</row>
		...
	</loadings>
<letters>
<row>
	<e>
		<type>ПИСМОГ</type>
		<count>0.5</count>
	</e>
	<e>
		<type>DC</type>
		<count>1</count>
	</e>
	</row>
</letters>
</parcels>

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

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

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

В зависимост дали искате да генерирате една или повече товарителници, следва да използвате различни методи – createLabel за една товарителница или createLabels за повече от една товарителница.

Важно: Тези методи се използват и за изчисляване на цена, затова е важно при генерирането и валидирането на товарителница да окажете коректния mode – create.

При подаването на заявка, методът изисква следното съдържание:

Клас ShippingLabel с пълното съдържание на съответните му компоненти
В случай че искате да заявите и куриер, който да дойде да вземе пратката, трябва да подадете параметрите requestCourierTimeFrom (от колко) и requestCourierTimeTo – до колко часа да дойде куриерът, за да вземе пратката от зададения адрес за взимане на пратката
mode – или цел на подадената заявка. Параметърът може да има 3 стойности:
- calculate – за изчисляване на цена
- validate – за валидиране на информация за товарителница
- create – за създаване на товарителница

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

Данни за подател (senderClient), виж Данни за подател
Адрес на подател (senderAddress), виж Валидиране на адрес по пратка
Данни за получател (receiverClient), виж Данни за получател
Заявка за куриер, ако е налична такава (requestCourierTimeFrom и requestCourierTimeTo
Брой части на пратката (packCount)
Тип на пратката (shipmentType) – виж Типове пратки, с които искате да доставяме поръчките на магазина
Тегло на пратката (weight)
Описание на пратката (shipmentDescription)
Какъв тип е заявката (mode) – за създаване на пратка следва да бъде create
Инструкции за връщане (клас ReturnInstructionParams)

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

Указания към приемащ и предаващ куриер (Instruction), виж Указания към куриера, който доставя пратката
Допълнителни услуги към пратката (ShippingLabelServices), виж Допълнителни варианти за търговците и клиентите на магазина
Опис на пратката (PackingListElement)

Съдържанието на класа ShippingLabel може да бъде:

Параметър	Описание
shipmentNumber	Номер на пратката
previousShipmentNumber	Номер на предходна пратка
previousShipmentReceiverPhone	Телефон на получател на предходна пратка
senderClient	подател (клиентски профил)
senderAgent	Упълномощено лице за изпращане на пратката от клиентски профил
senderAddress	Адрес на подател
senderOfficeCode	Код на офис за оставяне на пратката (виж Избор на офис за доставка)
e-mailOnDelivery	Имейл за уведомление при доставяне на пратката
smsOnDelivery	Индикатор дали към пратката да бъде добавено известяване със SMS за получател (Виж имейл или SMS известяване)
receiverClient	Получател
receiverAgent	Упълномощено лице на получател
receiverAddress	Адрес на получател
receiverOfficeCode	Код на офис за получаване на пратка (виж Избор на офис за доставка)
receiverProviderID	ID на получател
receiverBIC	BIC на банката на получател
receiverIBAN	IBAN на сметка на получател
envelopeNumbers	Брой пликове
packCount	Брой части на пратката
shipmentType	Тип на пратката (виж Типове пратки, с които искате да доставяме поръчките)
weight	Общо тегло на пратката
sizeUnder60cm	Предоставя информация дали и трите размера (ширина, височина и дължина) на пратката са под 60 см. Стойността на параметъра трябва да бъде „1“, ако искате да изпращате пощенска пратка като тип (shipmentType)
shipmentDimensionsL	Дължина на пратката
shipmentDimensionsW	Ширина на пратката
shipmentDimensionsH	Височина на пратката
shipmentDescription	Описание на пратката
orderNumber	Номер на поръчката
sendDate	Дата на изпращане на поръчката
holidayDeliveryDay	Кога да бъде доставена пратката – да бъде ли доставена в следващия възможен ден, дори и да е празник (отбелязвате със стойност на параметъра halfday), в следващия нормален работен ден (workday) или на специфична дата
keepUpright	Показва дали пратката трябва да бъде транспортирана изправена
services	Допълнителни услуги, маркирани с класа ShippingLabelServices (виж Допълнителни услуги за търговеца и клиентите на магазина)
instructions	Указания, подадени с класа Instruction (виж Указания към куриера, който доставя пратката)
payAfterAccept	Показва дали пратката е с Вариант Преглед (виж Преглед)
payAfterTest	Показва дали пратката е с Вариант Преглед и тест (виж Преглед и тест)
packingListType	Дава информация на системата какъв тип е описанието на съдържанието на пратката (file – отделен файл, digital - дигитален, loading – в товарителница)
packingList	В случай че описанието на съдържанието на пратката е digital, следва да подадете клас PackingListElement към заявката, в който да опишете всяка отделна част на самата пратка (виж Преглед, тест и избор)
partialDelivery	Показва дали да бъде позволена частична доставка, т.е. дали ще сте използвали услугата Преглед, тест и избор (виж Преглед, тест и избор)
paymentSenderMethod	Как ще плати подателят: оставете празно, ако подателят няма да плаща услугата cash – ако плащането ще е в брой credit – ако плащането ще е по договор
paymentReceiverMethod	Как ще плати получателят услугата: оставете празно, ако получателят няма да плаща cash – ако плащането ще е в брой credit – ако плащането ще е по договор
paymentReceiverAmount	Каква сума ще плати получателят (виж Плащане на пратката)
paymentReceiverAmountIsPercent	Какъв процент от сумата за доставка следва да плати получателят
paymentOtherClientNumber	Клиентски номер, в случай че плащането ще е от трета страна
paymentOtherAmount	Сума, която да бъде начислена за плащане на третата страна
paymentOtherAmountIsPercent	Процент от стойността на пратката, която да бъде заплатена от третата страна
mediator	Посредник на доставката

Примерна JSON заявка за генериране на товарителница:

{
	"label":{
		"senderClient":{
			"name":"Иван Иванов",
			"phones":["0888888888"]
		},
		"senderAddress":{
			"city":{
				"country":{
					"code3":"BGR"
				},
				"name":"Русе",
				"postCode":"7012"
			},
			"street":"Алея Младост",
			"num":"7"
		},
		"receiverClient":{
			"name":"Димитър Димитров",
			"phones":["0876543210"]
		},
		"receiverAddress":{
			"city":{
				"country":{
					"code3":"BGR"
				},
				"name":"Русе",
				"postCode":"7010"
			},
			"street":"Муткурова",
			"num":"84",
			"other":"бл. 5, вх. А, ет. 6"
		},
		"packCount":1,
		"shipmentType":"PACK",
		"weight":5,
		"shipmentDescription":"обувки"
	},
	"mode":"create"
}

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

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

Следващи стъпки

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