README

Aras Kargo carrier driver for the Omniship shipping library.

Installation

composer require tcgunel/omniship-aras

Usage

Initialize

use Omniship\Omniship;

$carrier = Omniship::create('Aras');
$carrier->initialize([
    'username' => 'your-username',
    'password' => 'your-password',
    'testMode' => true, // false for production
    'senderAccountAddressId' => '', // optional
]);

Create Shipment

use Omniship\Common\Address;
use Omniship\Common\Package;
use Omniship\Common\Enum\PaymentType;

$response = $carrier->createShipment([
    'shipTo' => new Address(
        name: 'Ahmet Yilmaz',
        street1: 'Ataturk Cad. No:1',
        city: 'Istanbul',
        district: 'Kadikoy',
        phone: '05551234567',
    ),
    'packages' => [
        new Package(
            weight: 1.5,
            length: 30,
            width: 20,
            height: 15,
            description: 'Elektronik urun',
        ),
    ],
    'integrationCode' => 'ORD-001',       // required - your order reference
    'invoiceNumber' => 'INV-001',          // optional
    'tradingWaybillNumber' => 'TWB-001',   // required - irsaliye no
    'barcodes' => ['BARCODE-001'],         // one barcode per piece
    'paymentType' => PaymentType::SENDER,  // or PaymentType::RECEIVER
    'cashOnDelivery' => false,
    'codAmount' => 0.0,
])->send();

if ($response->isSuccessful()) {
    echo $response->getShipmentId();    // InvoiceKey
    echo $response->getBarcode();       // same as InvoiceKey
    echo $response->getTrackingNumber(); // integrationCode
} else {
    echo $response->getMessage();       // error description
    echo $response->getCode();          // Aras result code
}

Integration Code & Barcodes

Per Aras Kargo requirements:

• integrationCode must be unique, minimum 6 characters, numeric only
• barcodes are auto-generated from integrationCode + 2-digit piece suffix if not provided
• Single piece: integrationCode=12345678 → barcode 1234567801
• Multi piece: integrationCode=12345678 → barcodes 1234567801, 1234567802

You can also provide explicit barcodes (one per piece):

'barcodes' => ['1234567801', '1234567802'],

If a package has quantity: 3, you need 3 barcodes for that package's pieces.

Generate Labels

Aras Kargo does not provide labels — they must be designed by the integrator. The built-in label generator creates print-ready HTML labels with barcodes (via Google Fonts Libre Barcode 128).

// Generate labels using default template
$html = $carrier->generateLabels([
    'shipFrom' => $shipFrom,
    'shipTo' => $shipTo,
    'packages' => $packages,
    'integrationCode' => '12345678',
    'paymentType' => PaymentType::SENDER,
    'cashOnDelivery' => false,
]);

// Output or save the HTML
file_put_contents('labels.html', $html);

Each package piece gets its own label with:

• Carrier name and date
• Sender name
• Receiver name, phone, address
• Payment type or COD info
• Integration code with barcode
• Piece barcode with barcode
• Piece number (e.g. Paket: 1/3)

Custom Label Template

You can provide your own HTML template with placeholders:

$customTemplate = '<div class="my-label">
    <h1>{{carrierName}}</h1>
    <p>{{receiverName}} - {{receiverPhone}}</p>
    <p>{{receiverAddress}}</p>
    <p>Entegrasyon: {{integrationCode}}</p>
    <p>Barkod: {{barcodeNumber}}</p>
    <p>Paket: {{pieceNumber}} / {{totalPieces}}</p>
</div>';

$html = $carrier->generateLabels($shipmentData, $customTemplate);

Available placeholders: {{carrierName}}, {{date}}, {{senderName}}, {{receiverName}}, {{receiverPhone}}, {{receiverAddress}}, {{paymentTypeText}}, {{codLine}}, {{codDisplay}}, {{paymentDisplay}}, {{integrationCode}}, {{barcodeNumber}}, {{pieceNumber}}, {{totalPieces}}.

Raw Label Data

For full control over rendering, get LabelData objects directly:

$labels = $carrier->getLabelData($shipmentData);

foreach ($labels as $label) {
    echo $label->integrationCode;
    echo $label->barcodeNumber;
    echo "{$label->pieceNumber}/{$label->totalPieces}";
}

### Track Shipment

Tracking uses the `GetOrderWithIntegrationCode` SOAP method to look up shipment by integration code.

```php
$response = $carrier->getTrackingStatus([
    'trackingNumber' => 'ORD-001', // your integration code
])->send();

if ($response->isSuccessful()) {
    $info = $response->getTrackingInfo();
    echo $info->trackingNumber;
    echo $info->status->value;  // PRE_TRANSIT, IN_TRANSIT, DELIVERED, etc.
    echo $info->carrier;        // "Aras Kargo"

    foreach ($info->events as $event) {
        echo $event->description;
        echo $event->occurredAt->format('Y-m-d H:i');
        echo $event->location;
    }
}

Cancel Shipment

$response = $carrier->cancelShipment([
    'integrationCode' => 'ORD-001',
])->send();

if ($response->isSuccessful()) {
    echo 'Shipment cancelled';
} else {
    echo $response->getMessage();
}

API Endpoints

SOAP Methods Used

Error Codes

Testing

vendor/bin/pest

License

MIT