tcgunel/omniship-hepsijet

HepsiJet carrier for Omniship shipping library

v0.0.2 2026-03-13 09:04 UTC

Requires

• php: ^8.2
• tcgunel/omniship-common: ^0.0.1

Requires (Dev)

• guzzlehttp/guzzle: ^7.0
• guzzlehttp/psr7: ^2.0
• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.0

MIT

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

Parameter	Description	Required
username	HepsiJet API username	Yes
password	HepsiJet API password	Yes
companyName	Company name (provided by HepsiJet during onboarding)	Yes
abbreviationCode	Company abbreviation code (provided by HepsiJet)	Yes
companyAddressId	Sender address ID (provided by HepsiJet)	Yes
currentXDockCode	Cross-dock/sorting center code (provided by HepsiJet)	Yes
testMode	Use sandbox environment	No (default: false)

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: '[e-mail]',
    ),
    '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

Environment	URL
Test	https://integration-apitest.hepsijet.com
Production	https://integration.hepsijet.com

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

Operation	Method	Endpoint
Create Shipment	POST	/rest/delivery/sendDeliveryOrderEnhanced
Track Shipment	POST	/rest/delivery/integration/track
Cancel Shipment	POST	/rest/delivery/deleteDeliveryOrder/{barcode}
Get Label	POST	/delivery/barcodes-label?format=PDF

Status Mapping

HepsiJet Status	ShipmentStatus
NEO	PRE_TRANSIT
ACCEPTED	PICKED_UP
OUT_FOR_DELIVERY	OUT_FOR_DELIVERY
DELIVERED	DELIVERED
FAILED_ATTEMPT	FAILURE
RETURNED	RETURNED
CANCELLED	CANCELLED
DELETED	CANCELLED

Response Format

All responses follow the envelope:

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

Testing

vendor/bin/pest

License

MIT