# Symelo Bulgarian Shipping for WooCommerce: user guide

Version 1.0.0. Speedy, Econt, Pigeon Express and BOX NOW for WooCommerce.

## 1. Set up a courier

1. **WooCommerce → Bulgarian Shipping → Couriers**, choose the courier.
2. Tick **Offer this courier**, enter the API account and click **Save**. The connection is tested right away; the sender profiles, contracts and warehouses it finds appear in the sender fields.
3. Fill in the **Sender**: who sends (client or profile), whether you hand parcels in at an office (choose it) or the courier picks them up from your address, and a contact phone.
4. Check the **Waybill defaults**: service, label size, cash-on-delivery agreement, options such as SMS.

Cities, offices and lockers download in the background (a minute or two) and refresh every day. **Update now** refreshes them on demand.

Where to get an API account:

| Courier | Account | Test environment |
|---|---|---|
| Speedy | Ask api.registration@speedy.bg with your contract number | No public one; Speedy gives test accounts on request |
| Econt | Your e-Econt login (ee.econt.com) | Choose **Test**; Econt publishes a demo account (`iasp-dev` / `1Asp-dev`) |
| Pigeon Express | Ask support@pigeonexpress.com for API keys | Sandbox keys on request |
| BOX NOW | Client ID and secret from integrationsupport@boxnow.bg | Stage keys on request |

## 2. Show the delivery options at checkout

Click **Add to a zone for Bulgaria** (Overview or Checkout tab): it creates the zone if needed and adds the options of every connected courier. Then open **WooCommerce → Settings → Shipping → Bulgaria** and edit each option:

- **Title** shown at checkout, e.g. "Доставка до офис на Speedy".
- **Show** (office options): offices and lockers, offices only, or lockers only. Add the option twice to offer offices and lockers separately.
- **Price**: the courier's price (calculated live for the chosen office or address), a fixed price, a weight table ("2 = 4.50" lines) or free. **Adjust the price** adds an amount or a percentage; **Round the price** rounds it up.
- **The customer pays the delivery**: with the order, or to the courier on delivery (the checkout shows the expected price; the waybill says the recipient pays).
- **Free from an order of**, **Free shipping coupons**, **Hide above (kg)**, **Hide above an order of**.
- **Prices include VAT**: couriers quote with VAT; with WooCommerce taxes on, VAT is taken out so the customer pays the same total.

## 3. What customers see

Under each courier option: a city box (type in Cyrillic or Latin), then the office or locker list, with a map button and the working hours of the chosen office. For door delivery: city and postcode, quarter, street and number, block, entrance, floor, apartment and a note, all from the courier's lists (free text is accepted when a street isn't listed).

The address fields the choice makes unnecessary are hidden, and the office or address becomes the order's shipping address. Returning customers get their last choice back.

**Checkout tab** settings: hiding address fields, the address form, phone check, the map (OpenStreetMap or your own tile provider, or the courier's own map), the look (theme fields or boxed), accent colour and logos. For more, add CSS in **Appearance → Customize → Additional CSS**, e.g.:

```css
.symelo-shipping, .symelo-modal { --symelo-shipping-accent: #c2185b; --symelo-shipping-radius: 0; }
```

## 4. Waybills

- **Order screen → Bulgarian Shipping box**: change the office or address if needed, check the price, adjust parcels, weight, cash on delivery, declared value, who pays and "open/test before paying", then **Create the waybill**. Print the label (A4 or A6), update tracking, create a return waybill or cancel it there.
- **Orders list**: bulk **Create waybills**, **Print shipping labels** (several labels come as one PDF), **Update shipment tracking**. The **Shipment** column shows the waybill and its status.
- **Shipments tab**: every waybill with filters (courier, status, "need attention", dates) and bulk labels, tracking, courier pickup requests and cancellations.
- **Automatic waybills** (Waybills & automation): when an order becomes Processing, On hold or Completed, for all or some couriers. Failures are noted on the order and emailed.

Cash on delivery is the order total for orders paid with the payment methods you mark as cash on delivery (Waybills & automation → Waybills).

### Print waybills

**WooCommerce → Print waybills** (also a tab of Bulgarian Shipping) lists the labels to print:

- **To print**: waybills not printed yet and not picked up by the courier (last 30 days). **Printed**: the printed ones, last printed first, with the time and who printed them.
- Counters on top: waybills and parcels to print, those waiting since before today, printed today, created today. Filters: courier, delivery type, shipments or returns, dates, waybill or order number.
- **Print** under a waybill prints that one. Select several (or all) and **Print selected**: the labels of every courier come in one PDF, in a new window, with progress while they're fetched. Under the list you see how many waybills and parcels are selected and their cash on delivery.
- Printed waybills are marked as printed and leave **To print**. Mark them by hand with **Mark as printed** / **Mark as not printed**, or **Mark all as printed** for the whole list.
- **Handover list**: a page for the courier to sign, one sheet per courier, with the waybills, recipients, parcels, cash on delivery and totals.
- **Label size**: each courier's setting, or A4 / A6 for this print.

A label that can't be fetched or combined is listed with the reason and a link to print it on its own.

## 5. Tracking, statuses and alerts

Shipments are tracked every two hours by default (BOX NOW can also push updates: send the webhook address shown on its settings page to BOX NOW support). The customer sees the status and history on their order page and gets the tracking link in WooCommerce's emails, plus the **Order shipped** and (optional) **Parcel ready for pickup** emails (WooCommerce → Settings → Emails).

Order statuses can follow the parcel: when the waybill is created, delivered, refused or returned, with optional "Shipped", "Delivered" and "Returned" statuses.

**Alerts** go to the shop's email: failed automatic waybills, refused or returning parcels, delivery problems, and a daily summary of parcels without movement, cash on delivery not paid out in time and courier APIs that keep failing.

**Cash-on-delivery payouts** (Speedy, Econt, Pigeon Express) are matched with shipments every day and noted on the orders.

## 6. НАП monthly file

For e-shops that register card and other non-cash payments with a "документ за регистриране на продажба" (Наредба Н-18, чл. 3, ал. 17):

1. **НАП report tab**: tick **НАП module**, enter the ЕИК, the e-shop number from НАП, the web address as registered and the seller details for the document.
2. Under **Payment methods**, give every payment method that belongs in the file its code (1 bank transfer, 2 card through a virtual POS with its terminal number, 4 a payment provider with its identifier…) and how refunds go back. Methods without a code are left out (usually cash on delivery).
3. Every paid order then gets a 10-digit document number, and the customer's order emails and order page show the document with its QR code.
4. Before the 15th of each month: choose the month, **Preview** (orders, refunds, anything left out, and a check against НАП's official schema), then **Download the XML** and upload it in НАП's e-services ("Подаване на стандартизиран одиторски файл от лице по чл. 3, ал. 17"). A reminder appears from the 1st to the 15th until the file is downloaded.

Amounts are in euro from January 2026. The file is built on your server.

## 7. Log and troubleshooting

- **Log tab**: every courier request and answer with the courier's own error message (passwords and keys are masked; labels aren't stored). Choose how much is logged and for how long under Waybills & automation → Log and data.
- **Support tab**: system information to paste into a support email.
- Background work (location lists, tracking, automatic waybills) runs through WooCommerce's Action Scheduler: WooCommerce → Status → Scheduled Actions, group `symelo-shipping`.

## 8. For developers

See `readme.txt` (hooks, REST API, WP-CLI) and `docs/architecture.md`.