Courier Integrations

Mozhe integrates with multiple courier services for automatic shipment creation, tracking, and label printing. This guide covers the available courier integrations and how to configure them.

Available Couriers

GLS

GLS is a European parcel service operating across Serbia and the region.

Features:

• Automatic shipment creation
• Parcel tracking
• Label printing
• Delivery status updates
• COD (Cash on Delivery) support

Coverage: Serbia, European Union

BEX

BEX (formerly Box Express) is a Serbian courier service specializing in e-commerce deliveries.

Features:

• Automatic shipment creation
• Parcel tracking
• Label printing (A4 and A6 formats)
• Delivery status updates
• COD support with bank transfer settlement
• Municipality and settlement database

Coverage: Serbia

DExpress

DExpress is a Serbian courier service with extensive domestic coverage and parcelbox/parcelshop delivery options.

Features:

• Automatic shipment creation
• Barcode generation
• Comprehensive status tracking (40+ status codes)
• Delivery status webhooks
• COD support with bank transfer settlement
• Town and municipality database
• Parcelbox and Parcelshop delivery

Coverage: Serbia

Prerequisites

Before configuring courier integrations:

• Active shipping method with courier API selected
• Courier merchant account with API access
• API credentials from the courier
• Configured pickup address in your organization

GLS Configuration

Step 1: Obtain GLS Credentials

Contact GLS to receive:

• Client ID: Your GLS customer number
• Username: API username
• Password: API password (may have multiple for different services)
• Identity Card Number: Required for sender verification

Step 2: Configure GLS in Mozhe

1. Go to Organization Settings > Shipping
2. Create or edit a shipping method
3. Select as the API Provider

Step 3: Pickup Address

Configure your pickup location:

1. Go to Organization Settings > Addresses
2. Add or verify your pickup address
3. Ensure postal code matches GLS database

GLS Shipment Flow

1. Order Prepared: Mark order as ready to ship
2. Submit to GLS: Mozhe calls GLS PrepareLabels API
3. Get Label: Retrieve and print shipping label
4. Track: Monitor parcel status via GetParcelStatuses
5. Delivered: GLS confirms delivery

GLS COD Configuration

For Cash on Delivery orders:

• COD amount is automatically calculated from order total
• GLS collects payment from customer
• Funds deposited to your configured bank account
• Reference includes order number

GLS Services

Available GLS service options:

BEX Configuration

Step 1: Obtain BEX Credentials

Contact BEX to receive:

• Client ID: Your BEX customer number
• API Token: Authentication token for API requests

Step 2: Configure BEX in Mozhe

1. Go to Organization Settings > Shipping
2. Create or edit a shipping method
3. Select BEX as the API Provider
4. Enter credentials:

Step 3: Address Database Sync

BEX uses municipality and settlement IDs for addressing:

1. Mozhe automatically syncs BEX address database
2. Customers select settlements from dropdown at checkout
3. Settlement ID is stored with the order

BEX Shipment Flow

1. Order Prepared: Mark order as ready to ship
2. Submit to BEX: Mozhe calls BEX postShipments API
3. Get Label: Retrieve shipping label (A6 format recommended)
4. Track: Monitor shipment status
5. Delivered: BEX confirms delivery

BEX COD Configuration

For Cash on Delivery orders:

• Set payType to 6 (bank transfer)
• Configure bank account in organization settings
• BEX collects payment and transfers to your account
• Reference format: "Porudzbina {order_number}"

BEX Task Structure

BEX uses tasks for pickup and delivery:

Pickup Task (Type 1)

• Sender name and address
• Contact phone number
• Pickup time window

Delivery Task (Type 2)

• Recipient name and address
• Contact phone number
• Pre-notification settings (e.g., 60 minutes before)
• Delivery notes

BEX Label Printing

Get labels for printing:

pageSize: 6 (A6) or 4 (A4)
pagePosition: 1-4 (position on A4 sheet)

A6 labels are recommended for thermal printers.

Deleting BEX Shipments

To cancel a shipment before pickup:

1. Go to order details
2. Click Cancel Shipment
3. BEX shipment is invalidated
4. Order status updated

DExpress Configuration

Step 1: Obtain DExpress Credentials

Contact DExpress to receive:

• Client ID: Your DExpress customer number
• Username: API username
• Password: API password
• Barcode Prefix: Your assigned barcode prefix (e.g., "MOZ")

Step 2: Configure DExpress in Mozhe

1. Go to Organization Settings > Shipping
2. Create or edit a shipping method
3. Select as the API Provider

Step 3: Barcode Configuration

DExpress requires pre-generated barcodes:

• Format: {prefix}{10-digit-counter}
• Example: MOZ0000000042
• Mozhe manages counter automatically

DExpress Shipment Flow

1. Order Prepared: Mark order as ready to ship
2. Generate Barcode: Mozhe creates unique tracking code
3. Submit to DExpress: Call addshipment API
4. Track: Monitor via status webhooks
5. Delivered: DExpress confirms delivery

DExpress COD Configuration

For Cash on Delivery orders:

• Amount converted to "para" (multiply by 100)
• Bank account stored in order metadata
• BuyOut amount set for customer collection
• BuyOutAccount for settlement destination

DExpress Status Codes

DExpress provides detailed status tracking:

Full status list includes 40+ codes for detailed tracking.

DExpress Webhooks

DExpress can send status updates via webhooks:

1. Configure webhook URL in DExpress merchant portal
2. Mozhe receives status updates automatically
3. Order status updated in real-time

Webhook endpoint: /api/webhooks/dexpress

DExpress Delivery Options

Delivery Types:

• Regular (DlTypeID: 2)
• Urgent (DlTypeID: 1)

Payment Options:

• Sender pays (PaymentBy: 0)
• Receiver pays (PaymentBy: 1)

Automatic Tracking Updates

All couriers support automatic tracking:

Background Jobs

Mozhe runs scheduled jobs to:

1. Check pending shipment statuses
2. Update order status based on courier status
3. Send customer notifications on status changes

Status Mapping

Courier statuses are mapped to Mozhe order statuses:

Label Printing

Thermal Printers

For thermal label printers:

1. Use A6 format (105mm x 148mm)
2. BEX: pageSize = 6
3. GLS: Standard label format
4. DExpress: Generated barcode label

A4 Printers

For standard A4 printers:

1. Use A4 format with multiple positions
2. BEX: pageSize = 4, pagePosition = 1-4
3. Print 4 labels per sheet

Printing Workflow

1. Go to order details
2. Click Print Label
3. Label downloads as PDF
4. Print using appropriate printer settings

Testing Integrations

Test Mode

Before going live:

1. Use test credentials provided by courier
2. Create test shipments
3. Verify label generation
4. Check status tracking
5. Test COD flow (amounts may be zeroed in test mode)

Validation

Before each shipment:

• Verify address data is complete
• Check phone number format
• Ensure postal code is valid
• Confirm settlement/town IDs for BEX/DExpress

Troubleshooting

GLS Issues

"PrepareLabelsError"

• Check pickup and delivery addresses
• Verify postal codes exist in GLS database
• Ensure client credentials are correct

"GetPrintDataError"

• Shipment may not exist
• Parcel ID may be incorrect
• Wait for label to be ready

BEX Issues

"reqstate: false"

• Check authentication token
• Verify request payload format
• Review error message in reqerr

"Municipality/place not found"

• Update BEX settlement database
• Verify customer selected valid settlement
• Check postal code mapping

DExpress Issues

"ModelState errors"

• Check phone number format (381xxxxxxxxx)
• Verify town IDs are valid
• Review address length limits

"Missing barcode prefix"

• Configure barcode prefix in settings
• Contact DExpress for prefix assignment

Webhook Setup

GLS Webhooks

GLS uses callback URLs:

1. Configure callback URL in shipment request
2. GLS sends POST on status changes
3. Endpoint: /api/webhooks/gls

BEX Webhooks

BEX uses email reports:

1. Configure report email addresses
2. Reports sent for pickup, delivery, issues
3. Manual status updates may be needed

DExpress Webhooks

DExpress sends POST requests:

1. Configure in DExpress merchant portal
2. Requires shared secret for verification
3. Endpoint: /api/webhooks/dexpress

Next Steps

• Configure shipping methods with courier integration
• Enable Cash on Delivery for COD support
• Set up payment methods to complete checkout