README

HepsiJet (Hepsiburada Logistics) carrier driver for Omniship.

Uses HepsiJet's REST/JSON API with token-based authentication.

Installation

composer require tcgunel/omniship-hepsijet

Quick Start

use Omniship\Omniship;
use Omniship\Common\Address;
use Omniship\Common\Package;

$carrier = Omniship::create('HepsiJet');
$carrier->initialize([
    'username' => 'your-username',
    'password' => 'your-password',
    'companyName' => 'YourCompany',
    'abbreviationCode' => 'YRCMPNY',
    'companyAddressId' => 'ADDR-001',
    'currentXDockCode' => 'XD_CENTER',
    'testMode' => true,
]);

Configuration Parameters

Operations

Create Shipment

HepsiJet requires the caller to provide a unique barcode/tracking number (customerDeliveryNo). This must be 9-16 characters, prefixed with your company abbreviation code.

$response = $carrier->createShipment([
    'customerDeliveryNo' => 'YRCMPNY123456789',
    'shipFrom' => new Address(
        name: 'Ahmet Yılmaz',
        street1: 'Atatürk Cad. No:42',
        city: 'İstanbul',
        district: 'Kadıköy',
    ),
    'shipTo' => new Address(
        name: 'Mehmet Demir',
        street1: 'Kızılay Mah. 123. Sok. No:5',
        city: 'Ankara',
        district: 'Çankaya',
        postalCode: '06420',
        phone: '05559876543',
        email: 'mehmet@example.com',
    ),
    'packages' => [
        new Package(
            weight: 2.5,
            length: 30,
            width: 20,
            height: 15,
            description: 'Elektronik ürün',
        ),
    ],
    'deliveryType' => 'RETAIL',   // RETAIL, MARKET_PLACE, EXPRESS, RETURNED
    'productCode' => 'HX_STD',   // HX_STD, HX_SD, HX_ND, HX_EX
])->send();

if ($response->isSuccessful()) {
    echo $response->getTrackingNumber();  // "YRCMPNY123456789"
    echo $response->getBarcode();         // Same as tracking number
    echo $response->getShipmentId();      // Same as tracking number
}

Track Shipment

$response = $carrier->getTrackingStatus([
    'trackingNumber' => 'YRCMPNY123456789',
])->send();

if ($response->isSuccessful()) {
    $info = $response->getTrackingInfo();
    echo $info->status->name;         // "DELIVERED"
    echo $info->trackingNumber;       // "YRCMPNY123456789"
    echo $info->signedBy;             // "Mehmet Demir" (if delivered)

    foreach ($info->events as $event) {
        echo $event->description;     // "ACCEPTED", "OUT_FOR_DELIVERY", etc.
        echo $event->occurredAt->format('Y-m-d H:i');
        echo $event->location;        // "Istanbul", "Ankara", etc.
    }
}

Cancel Shipment

Cancels a shipment before it has been picked up by HepsiJet.

$response = $carrier->cancelShipment([
    'trackingNumber' => 'YRCMPNY123456789',
    'deleteReason' => 'IPTAL',       // Optional, defaults to "IPTAL"
])->send();

if ($response->isSuccessful() && $response->isCancelled()) {
    echo 'Shipment cancelled';
}

API Details

Endpoints

Authentication

Two-step token authentication:

1. GET /auth/getToken with HTTP Basic Auth (username:password)
2. All subsequent requests use X-Auth-Token: {token} header

Token expires after 60 minutes.

Key Features

• REST/JSON API: Modern JSON-based API
• Caller-provided barcode: You generate the tracking number (customerDeliveryNo), 9-16 chars, prefixed with abbreviation code
• Nested address format: city.name, town.name, district.name structure
• Delivery types: RETAIL, MARKET_PLACE, EXPRESS, RETURNED
• Product codes: HX_STD (Standard), HX_SD (Same Day), HX_ND (Next Day), HX_EX (Express)
• Delivery slots: 0=Off, 1=Morning(09-13), 2=Noon(13-18), 3=Evening(18-23)
• Separate label endpoint: Labels are not returned in the create response; use /delivery/barcodes-label separately

API Methods

Status Mapping

Response Format

All responses follow the envelope:

{
    "status": "OK",
    "data": { ... },
    "message": null
}

Testing

vendor/bin/pest

License

MIT