# Symelo Bulgarian Shipping for WooCommerce

URL: https://dev.symelo.com/bg/tools/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce

Speedy, Econt, Pigeon Express и BOX NOW за WooCommerce: доставка до офис, автомат или адрес с актуални цени, товарителници, проследяване и месечния файл за НАП.

Version 1.0.0, released 2026-10-14. Requires WordPress 6.4 and PHP 7.4; tested up to WordPress 7.1. License: GPLv2 or later.

## Описание

Symelo Bulgarian Shipping свързва вашия WooCommerce магазин с българските куриери и автомати за пратки – от страницата за плащане до доставения колет.

#### На страницата за плащане

* **Доставка до офис, автомат и адрес** със **Speedy**, **Econt**, **Pigeon Express** и **BOX NOW**. Всяка от тях е обикновен метод за доставка в WooCommerce, така че го добавяте към зоните си за доставка и задавате цената му като на всеки друг.
* **Избор, който намира написаното от клиента**: населени места, офиси и автомати на кирилица или латиница („sofia“, „Sofiq“ и „соф“ намират София), с областта до селата с еднакви имена.
* **Доставка до адрес по списъците на самия куриер**: населено място, квартал, улица, номер, блок, вход, етаж и апартамент, така че товарителниците се приемат от първия път.
* **Карта** за избор на офис или автомат – вградена (OpenStreetMap или избран от вас доставчик на плочки) или картата на самия куриер, когато има такава (Speedy, Econt, BOX NOW).
* **Актуални цени** от Speedy, Econt и Pigeon Express, включително таксата за наложен платеж, или фиксирана цена, таблица по тегло или безплатна доставка. Безплатна доставка над определена стойност на поръчката или с купон, надценка като сума или процент, закръгляне.
* **Клиентът плаща на куриера** или **цената е включена в поръчката**: по ваш избор за всяка опция.
* **Работи с блока „Страница за плащане“ и с класическата страница за плащане**, взема шрифтовете, цветовете и полетата на темата ви и лесно се донастройва с CSS променливи (custom properties).
* Скрива адресните полета, които стават излишни при избран офис или автомат, запомня избора на завръщащите се клиенти и проверява българските телефонни номера.

#### След поръчката

* **Товарителници** от екрана на поръчката (с проверка на цената), групово от списъка с поръчки или автоматично, когато поръчката бъде платена. Колети, тегло, наложен платеж, обявена стойност, „преглед/тест преди плащане“, SMS, съдържание и бележки.
* **Печат на товарителници**: страница с етикетите, които чакат печат, и с вече отпечатаните. Отпечатайте един етикет или изберете много и ги получете всички в един PDF, от всички куриери наведнъж. Отпечатаните товарителници се отбелязват автоматично (или ръчно), с броя на колетите и сумата на наложения платеж за избраните, както и опис на пратките, който куриерът да подпише. Етикети във формат A4 или A6.
* **Проследяване** на всеки няколко часа (при BOX NOW и чрез webhook): статус, история и линк за проследяване в имейлите на WooCommerce и на страницата на поръчката за клиента. Имейли „Поръчката е изпратена“ и „Пратката е готова за получаване“.
* **Анулиране, товарителници за връщане и заявки за куриер**, когато куриерът ги предлага.
* **Известия за доставката** по имейл: отказани или върнати пратки, проблеми с доставката, неуспешни автоматични товарителници, пратки без движение, наложен платеж, който не е изплатен навреме.
* **Изплащанията на наложен платеж** се съпоставят с вашите пратки (Speedy, Econt, Pigeon Express).
* **Статуси на поръчките**, които следват пратката, с допълнителни статуси „Изпратена“, „Доставена“ и „Върната“ по избор.
* **Дневник** на всяка заявка към куриера и на отговора му (паролите и ключовете са маскирани).

#### Месечен файл за НАП

За онлайн магазини, които регистрират плащанията с карта и другите безкасови плащания с „документ за регистриране на продажба“ (Наредба Н-18, чл. 3, ал. 17):

* всяка платена поръчка получава 10-цифрен номер на документ, а клиентът получава документа с QR кода му в имейлите за поръчката;
* всеки месец преглеждате и изтегляте стандартизирания одиторски файл (Приложение № 38) в евро, проверен спрямо официалната схема на НАП и готов за подаване до 15-о число;
* за всеки метод на плащане избирате кода на плащане за НАП, номера на виртуалния ПОС терминал и доставчика на платежни услуги; възстановените суми се включват автоматично.

Файлът се създава на вашия сървър; за него никакви данни за поръчки не напускат сайта ви.

#### За разработчици

Филтри: `symelo_shipping_capability`, `symelo_shipping_carriers`, `symelo_shipping_draft`, `symelo_shipping_rate_cost`, `symelo_shipping_method_available`, `symelo_shipping_cod_gateways`, `symelo_shipping_logo_url`, `symelo_shipping_http_timeout`, `symelo_shipping_alert`, `symelo_shipping_tabs`, `symelo_shipping_more_from_symelo`.

Действия (actions): `symelo_shipping_loaded`, `symelo_shipping_shipment_created`, `symelo_shipping_shipment_canceled`, `symelo_shipping_return_created`, `symelo_shipping_create_failed`, `symelo_shipping_status_changed`, `symelo_shipping_carrier_saved`, `symelo_shipping_settings_saved`, `symelo_shipping_tab_{slug}`.

Константа: `SYMELO_SHIPPING_KEY` (ключ за криптиране на запазените пароли и ключове за куриерите, поне 32 знака).

REST API (за мениджъри на магазина): `/wp-json/symelo-shipping/v1/` status, settings, carriers, carriers/{id}, carriers/{id}/test, carriers/{id}/sync, quote, orders/{id}/delivery, orders/{id}/quote, orders/{id}/shipments, shipments, shipments/printed, shipments/{id}, shipments/{id}/cancel, shipments/{id}/track, shipments/{id}/label, shipments/{id}/return, print, print/{job}, print/{job}/pdf, tracking/run, payouts/sync, logs, logs/{id}, nap/{year}/{month}, zones/setup, self-test. Публични маршрути за избора на офис или адрес на страницата за плащане: cities, points, map, streets, quarters. Webhook на BOX NOW: webhook/boxnow (проверява се по подписа му).

WP-CLI: `wp symelo-shipping status|test|sync|create|track|cancel|label|print|nap|payouts`.

## Инсталиране

1. Инсталирайте и активирайте плъгина (WooCommerce трябва да е активен).
2. Отидете в **WooCommerce → Доставка в България → Куриери**, въведете API профила си при куриера и проверете връзката. Населените места, офисите и автоматите се изтеглят във фонов режим.
3. Щракнете върху **Добавяне към зона за България** (или добавете методите към своя собствена зона за доставка) и задайте цените им в **WooCommerce → Настройки → Доставка**.
4. По избор: в **Товарителници и автоматизация** изберете кога да се създават товарителниците, статусите на поръчките и известията, и настройте **Отчет за НАП**.

Необходим ви е API профил при всеки куриер, когото използвате. Econt публикува публичен демо профил, с който да изпробвате плъгина (изберете среда „Тестова (демо)“); Pigeon Express и BOX NOW предоставят тестови ключове при поискване.

## Често задавани въпроси

#### Работи ли с блока „Страница за плащане“?

Да, както и с класическата страница за плащане. И в двата случая изборът на офис или адрес се показва под опциите за доставка.

#### Могат ли клиентите да платят доставката на куриера, вместо да я платят в поръчката?

Да. В метода за доставка задайте на „Клиентът плаща доставката“ стойност „На куриера при доставка“. Страницата за плащане показва очакваната цена, а в товарителницата е посочено, че плаща получателят.

#### Откъде идват цените?

Speedy, Econt и Pigeon Express ги изчисляват в реално време за избрания офис или адрес (кешират се за 30 минути). BOX NOW няма ценова листа в API-то си, затова задавате фиксирана цена или таблица по тегло. Всеки метод може също да използва фиксирана цена, таблица по тегло или да бъде безплатен.

#### Има ли значение валутата на магазина?

Куриерите работят в евро, както и България от 1 януари 2026 г. При магазините, които все още показват цените в лева, сумите се превалутират по фиксирания курс 1,95583.

#### Какво съдържа файлът за НАП?

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

#### Защитени ли са паролите ми за куриерите?

Съхраняват се криптирани, не се показват повече след запазване и са маскирани в дневника. Дефинирайте `SYMELO_SHIPPING_KEY` в wp-config.php, за да използвате ключ, който не се пази в базата данни.

## Външни услуги

Плъгинът се свързва само с куриерите, които сте настроили, и само за да изпълни това, което използвате: показване на офиси, цени и улици на страницата за плащане, създаване и проследяване на товарителници, печат на етикети. Към Symelo LTD не се изпраща нищо: няма проследяване на потребителите, статистика или отдалечен код.

#### Speedy

Използва се, когато настроите профил в Speedy. Офисите и населените места се изтеглят ежедневно от api.speedy.bg; на страницата за плащане плъгинът изпраща заявки към api.speedy.bg за имена на улици и цени (с дестинацията, теглото и сумата на наложения платеж); товарителниците, етикетите, анулиранията, проследяването, заявките за куриер и справките за изплащания се изпращат към api.speedy.bg с името, телефона и имейла на получателя, офиса или адреса за доставка и данните за пратката. Ако изберете картата на Speedy, браузърът на клиента я зарежда от services.speedy.bg, когато картата бъде отворена. Линковете за проследяване водят към speedy.bg.

* Условия: https://www.speedy.bg/en/terms-and-conditions
* Политика за поверителност: https://www.speedy.bg/en/gdpr

#### Econt

Използва се, когато настроите профил в Econt (ee.econt.com или demo.econt.com за тестовата среда), по същия начин като при Speedy: населени места, офиси, улици и квартали, цени, товарителници (с данните на получателя), етикети, анулирания, проследяване, заявки за куриер и справки за изплащания. Ако изберете картата на Econt, браузърът на клиента зарежда officelocator.econt.com, когато картата бъде отворена. Линковете за проследяване водят към econt.com.

* Условия: https://www.econt.com/en/econt-express/common-terms
* Политика за поверителност: https://www.econt.com/en/econt-express/privacy-policy

#### Pigeon Express

Използва се, когато настроите профил в Pigeon Express (api.pigeonexpress.com или api-demo.pigeonexpress.com за тестовата среда), по същия начин: населени места, офиси и автомати, търсене на улици, цени, товарителници (с данните на получателя), етикети, анулирания, проследяване, заявки за куриер и справки за изплащания. Линковете за проследяване водят към track.pigeonexpress.com.

* Условия: https://pigeonexpress.com/terms
* Политика за поверителност: https://pigeonexpress.com/privacy

#### BOX NOW

Използва се, когато настроите профил в BOX NOW. Списъкът с автомати се изтегля ежедневно от locationapi-production.boxnow.bg (locationapi-stage.boxnow.bg за тестовата среда); товарителниците (заявки за доставка с името, телефона и имейла на получателя и автомата), етикетите, анулиранията, връщанията и проследяването се изпращат към api-production.boxnow.bg (api-stage.boxnow.bg). Ако дадете на поддръжката на BOX NOW адреса на своя webhook, BOX NOW изпраща обновления на статусите към сайта ви. Ако изберете картата на BOX NOW, браузърът на клиента я зарежда от widget-v5.boxnow.bg, когато картата бъде отворена. Линковете за проследяване водят към boxnow.bg.

* Условия: https://boxnow.bg/en/terms-of-use-for-shipping-services
* Политика за поверителност: https://boxnow.bg/en/personal-data-processing-notice-en

#### Плочки на картата (OpenStreetMap)

Когато вградената карта е включена и клиент я отвори, браузърът му зарежда изображенията на картата от tile.openstreetmap.org (или от доставчика на плочки, който сте въвели в настройките). Сървърът за плочки получава IP адреса на клиента и показваната област. Библиотеката за картата (Leaflet) е част от плъгина.

* Правила за използване на плочките: https://operations.osmfoundation.org/policies/tiles/
* Условия: https://osmfoundation.org/wiki/Terms_of_Use
* Политика за поверителност: https://osmfoundation.org/wiki/Privacy_Policy

## Благодарности

Картата използва Leaflet 1.9.4 (BSD-2-Clause, https://leafletjs.com/), включена в `assets/vendor/leaflet` заедно с четимия си изходен код.

Speedy, Econt (ЕКОНТ), Pigeon Express и BOX NOW, както и техните лога, са търговски марки на съответните им притежатели. Плъгинът ги използва единствено за да покаже на клиентите и служителите на магазина кой куриер доставя; той не е създаден, нито одобрен от тези компании.

## Бележка за обновяване

#### 1.0.0
Първа версия.

## Downloads

- [Symelo Bulgarian Shipping for WooCommerce 1.0.0](https://dev.symelo.com/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce/1.0.0/symelo-bulgarian-shipping-for-woocommerce-1.0.0.zip) (2026-10-14, 669 KB, SHA-256 f4d330365cea4e9b72bc0bed0dde8574caa04b19acf5db205f61b328d6b4f342)
  * Първа версия: Speedy, Econt, Pigeon Express и BOX NOW; избор на офис или адрес с карта за блока „Страница за плащане“ и класическата страница за плащане; товарителници, етикети и страницата „Печат на товарителници“ (един PDF за много етикети), проследяване, връщания, известия; месечният файл за НАП.

## Documentation

- [Symelo Bulgarian Shipping for WooCommerce: ръководство за потребителя](https://dev.symelo.com/bg/tools/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce/docs/user-guide)

## Related pages

- [All tools](https://dev.symelo.com/bg/tools)
- [Agent documentation](https://dev.symelo.com/llms.txt)