PHPackages                             geliver/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. geliver/sdk

ActiveLibrary[API Development](/categories/api)

geliver/sdk
===========

Geliver API SDK (PHP)

1.2.2(2mo ago)2168↓42.9%MITPHPPHP >=8.1CI failing

Since Nov 27Pushed 2mo agoCompare

[ Source](https://github.com/GeliverApp/geliver-php)[ Packagist](https://packagist.org/packages/geliver/sdk)[ RSS](/packages/geliver-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (6)Used By (0)

Geliver PHP SDK
===============

[](#geliver-php-sdk)

[![Packagist](https://camo.githubusercontent.com/14785a9b89457975fb8ecdafd220ff0c0649f29127d29ccf5177943e96a3427c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67656c697665722f73646b2e737667)](https://packagist.org/packages/geliver/sdk)

Geliver PHP SDK — official PHP client for Geliver Kargo Pazaryeri (Shipping Marketplace) API. Türkiye’nin e‑ticaret gönderim altyapısı için kolay kargo entegrasyonu sağlar.

• Dokümantasyon (TR/EN):

---

İçindekiler
-----------

[](#i̇çindekiler)

- Kurulum
- Hızlı Başlangıç
- Adım Adım
- Webhooklar
- Testler
- Modeller
- Enum Kullanımı
- Notlar ve İpuçları

---

Kurulum
-------

[](#kurulum)

- Packagist: `composer require geliver/sdk:^1.0`
- Bu repodaki örnekleri çalıştırmak için: `composer install`

---

Akış (TR)
---------

[](#akış-tr)

1. Geliver Kargo API tokenı alın ( adresinden)
2. Gönderici adresi oluşturun (addresses()->createSender)
3. Gönderiyi alıcıyı ID'si ile ya da adres nesnesi ile vererek oluşturun (shipments()->create)
4. Teklifleri bekleyin ve kabul edin (transactions()->acceptOffer)
5. Barkod, takip numarası, etiket URL’leri Transaction içindeki Shipment’te bulunur
6. Test gönderilerinde her GET /shipments isteği kargo durumunu bir adım ilerletir; prod'da webhook kurun
7. Etiketleri indirin (downloadLabel, downloadResponsiveLabel)
8. İade gönderisi gerekiyorsa shipments()->createReturn kullanın

---

Hızlı Başlangıç
---------------

[](#hızlı-başlangıç)

```
use Geliver\Client;

$client = new Client('YOUR_TOKEN');
$sender = $client->addresses()->createSender([
  'name' => 'ACME Inc.', 'email' => 'ops@acme.test', 'phone' => '+905051234567', 'address1' => 'Hasan Mahallesi',
  'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34',
  'districtName' => 'Esenyurt', 'zip' => '34020',
]);
$shipment = $client->shipments()->createTest([
  'senderAddressID' => $sender['id'],
  'recipientAddress' => ['name' => 'John Doe', 'email' => 'john@example.com', 'phone' => '+905051234568', 'address1' => 'Atatürk Mahallesi', 'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34', 'districtName' => 'Kadıköy', 'zip' => '34000'],
  // İstek alanları string olmalıdır
  'length' => '10.0', 'width' => '10.0', 'height' => '10.0', 'distanceUnit' => 'cm', 'weight' => '1.0', 'massUnit' => 'kg',
  'order' => [
    'orderNumber' => 'WEB-12345',
    // sourceIdentifier alanına mağazanızın tam adresini yazın (ör. https://magazam.com).
    'sourceIdentifier' => 'https://magazam.com',
    'totalAmount' => '150',
    'totalAmountCurrency' => 'TRY',
  ],
]);
```

Canlı ortamda `$client->shipments()->createTest(...)` yerine `$client->shipments()->create(...)` çağırın.

---

Türkçe Akış (TR)
----------------

[](#türkçe-akış-tr)

```
use Geliver\Client;

$client = new Client('YOUR_TOKEN');

// 1) Gönderici adresi oluşturma. Her gönderici adresi için tek seferlik yapılır. Oluşan gönderici adres ID'sini saklayıp tekrar kullanılır.
$sender = $client->addresses()->createSender([
  'name' => 'ACME Inc.', 'email' => 'ops@acme.test', 'phone' => '+905051234567',
  'address1' => 'Hasan Mahallesi', 'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34',
  'districtName' => 'Esenyurt', 'zip' => '34020',
]);

// 2) Gönderi oluşturma (iki adım) — Seçenek A: alıcıyı inline verin (kayıt oluşturmadan)
// Canlı ortamda createTest yerine create fonksiyonunu kullanın.
$shipment = $client->shipments()->createTest([
  'senderAddressID' => $sender['id'],
  'recipientAddress' => [
    'name' => 'John Doe', 'email' => 'john@example.com', 'phone' => '+905051234568',
    'address1' => 'Atatürk Mahallesi', 'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34',
    'districtName' => 'Esenyurt', 'zip' => '34020',
  ],
  'length' => '10.0', 'width' => '10.0', 'height' => '10.0', 'distanceUnit' => 'cm', 'weight' => '1.0', 'massUnit' => 'kg',
  'order' => [
    'orderNumber' => 'WEB-12345',
    // sourceIdentifier alanına mağazanızın tam adresini yazın (ör. https://magazam.com).
    'sourceIdentifier' => 'https://magazam.com',
    'totalAmount' => '150',
    'totalAmountCurrency' => 'TRY',
  ],
]);

// Etiket indirme: Teklif kabulünden sonra (Transaction) gelen URL'leri kullanabilirsiniz de; URL'lere her shipment nesnesinin içinden ulaşılır.

// 3) Alıcı adresi oluşturma (örnek)
$recipient = $client->addresses()->createRecipient([
  'name' => 'John Doe', 'email' => 'john@example.com',
  'address1' => 'Atatürk Mahallesi', 'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34',
  'districtName' => 'Kadıköy', 'zip' => '34000',
]);

// 4) Teklifleri kontrol et: create yanıtındaki offers alanını kullanın
$offers = $shipment['offers'] ?? null;
if (empty($offers['cheapest'])) {
  throw new RuntimeException('Teklifler henüz hazır değil; GET /shipments ile tekrar kontrol edin.');
}

$tx = $client->transactions()->acceptOffer($offers['cheapest']['id']);
echo 'Transaction: ' . $tx['id'] . PHP_EOL;
echo 'Barcode: ' . ($tx['shipment']['barcode'] ?? '') . PHP_EOL;
echo 'Tracking number: ' . ($tx['shipment']['trackingNumber'] ?? '') . PHP_EOL;
echo 'Label URL: ' . ($tx['shipment']['labelURL'] ?? '') . PHP_EOL;
echo 'Tracking URL: ' . ($tx['shipment']['trackingUrl'] ?? '') . PHP_EOL;

// Test gönderilerinde her GET /shipments isteği kargo durumunu bir adım ilerletir (prod'da webhook önerilir)
for ($i=0; $ishipments()->get($shipment['id']); }
$latest = $client->shipments()->get($shipment['id']);
$ts = $latest['trackingStatus'] ?? [];
echo 'Final tracking status: ' . ($ts['trackingStatusCode'] ?? '') . ' ' . ($ts['trackingSubStatusCode'] ?? '') . PHP_EOL;

// Download labels
// Teklif kabulünden sonra Transaction içindeki Shipment alanındaki URL'leri kullanın (ek GET yok)
file_put_contents('label.pdf', $client->shipments()->downloadLabelByUrl($tx['shipment']['labelURL']));
file_put_contents('label.html', $client->shipments()->downloadResponsiveLabelByUrl($tx['shipment']['responsiveLabelURL']));
```

Alıcı ID'si ile oluşturma (recipientAddressID)
----------------------------------------------

[](#alıcı-idsi-ile-oluşturma-recipientaddressid)

```
// Önce alıcı adresini kaydedin ve ID alın
$recipient = $client->addresses()->createRecipient([
  'name' => 'John Doe', 'email' => 'john@example.com', 'address1' => 'Atatürk Mahallesi',
  'countryCode' => 'TR', 'cityName' => 'Istanbul', 'cityCode' => '34',
  'districtName' => 'Kadıköy', 'zip' => '34000',
]);

// Ardından recipientAddressID ile gönderi oluşturun
$client->shipments()->create([
  'senderAddressID' => $sender['id'],
  'recipientAddressID' => $recipient['id'],
  'providerServiceCode' => 'MNG_STANDART',
  'length' => '10.0', 'width' => '10.0', 'height' => '10.0', 'distanceUnit' => 'cm', 'weight' => '1.0', 'massUnit' => 'kg',
]);
```

---

---

İade Gönderisi Oluşturun
------------------------

[](#i̇ade-gönderisi-oluşturun)

```
$returned = $client->shipments()->createReturn($shipment['id'], [
  'willAccept' => true,
  'providerServiceCode' => 'SURAT_STANDART',
]);
```

Not:

- `willAccept` alanı opsiyoneldir (varsayılan `false`). `true` ise backend iade için uygun teklifi otomatik kabul eder (etiket satın alma). `false` ise sadece iade shipment’i oluşturur; daha sonra teklif kabul ederek etiket alabilirsiniz.
- `providerServiceCode` alanı opsiyoneldir. Varsayılan olarak orijinal gönderinin sağlayıcısı kullanılır; dilerseniz bu alanı vererek değiştirebilirsiniz.
- `senderAddress` alanı opsiyoneldir. Varsayılan olarak orijinal gönderinin alıcı adresi kullanılır; dilerseniz bu alanı vererek değiştirebilirsiniz.
- `count` alanı opsiyoneldir (varsayılan `1`). Bu fonksiyon “tek shipment için tek iade” akışı içindir; genelde `1` kullanılmalıdır.

---

Webhooklar
----------

[](#webhooklar)

- `/webhooks/geliver` gibi bir endpoint yayınlayın ve JSON içeriğini `WebhookUpdateTrackingRequest` modeli ile ayrıştırın. Doğrulama için `Geliver\Webhooks::verify($rawBody, $headers, false)` kullanabilirsiniz (şimdilik devre dışı).

```
use Geliver\Webhooks;
use Geliver\Models\WebhookUpdateTrackingRequest;
use Geliver\Models\Shipment;

$raw = file_get_contents('php://input');
if (!Webhooks::verify($raw, getallheaders(), false)) {
  http_response_code(400);
  exit('invalid');
}
$payload = json_decode($raw, true) ?: [];
$evt = new WebhookUpdateTrackingRequest();
$evt->event = $payload['event'] ?? '';
$evt->metadata = $payload['metadata'] ?? null;
$evt->data = new Shipment();
foreach (($payload['data'] ?? []) as $key => $value) {
  if (property_exists($evt->data, $key)) {
    $evt->data->{$key} = $value;
  }
}
if ($evt->event === 'TRACK_UPDATED') {
  echo 'Tracking update: ' . ($evt->data->trackingUrl ?? '') . ' ' . ($evt->data->trackingNumber ?? '') . PHP_EOL;
}
```

- Webhook yönetimi: `$client->webhooks()->create('https://yourapp.test/webhooks/geliver');`

---

Testler
-------

[](#testler)

- Testlerde Guzzle MockHandler kullanabilirsiniz.
- Üretilmiş model sınıfları `Geliver\Models` altında bulunur (OpenAPI’den otomatik üretilir).

Manuel takip kontrolü (isteğe bağlı)

```
$s = $client->shipments()->get($shipment['id']);
$ts = $s['trackingStatus'] ?? null;
echo 'Status: ' . ($ts['trackingStatusCode'] ?? '') . ' ' . ($ts['trackingSubStatusCode'] ?? '') . PHP_EOL;
```

### Gönderi Listeleme, Getir, Güncelle, İptal, Klonla

[](#gönderi-listeleme-getir-güncelle-i̇ptal-klonla)

- Listeleme (docs): [https://docs.geliver.io/docs/shipments\_and\_transaction/list\_shipments](https://docs.geliver.io/docs/shipments_and_transaction/list_shipments)
- Gönderi getir (docs): [https://docs.geliver.io/docs/shipments\_and\_transaction/list\_shipments](https://docs.geliver.io/docs/shipments_and_transaction/list_shipments)
- Paket güncelle (docs): [https://docs.geliver.io/docs/shipments\_and\_transaction/update\_package\_shipment](https://docs.geliver.io/docs/shipments_and_transaction/update_package_shipment)
- Gönderi iptal (docs): [https://docs.geliver.io/docs/shipments\_and\_transaction/cancel\_shipment](https://docs.geliver.io/docs/shipments_and_transaction/cancel_shipment)
- Gönderi klonla (docs): [https://docs.geliver.io/docs/shipments\_and\_transaction/clone\_shipment](https://docs.geliver.io/docs/shipments_and_transaction/clone_shipment)

```
// Listeleme (sayfalandırma)
$list = $client->shipments()->list(['page' => 1, 'limit' => 20]);
foreach ($list['data'] ?? [] as $shipment) {
  echo $shipment['id'] ?? '' . PHP_EOL;
}

// Getir
$fetched = $client->shipments()->get('SHIPMENT_ID');
$ts = $fetched['trackingStatus'] ?? [];
echo 'Tracking: ' . ($ts['trackingStatusCode'] ?? '') . ' ' . ($ts['trackingSubStatusCode'] ?? '') . PHP_EOL;

// Paket güncelle (eni, boyu, yüksekliği ve ağırlığı string gönderin)
$client->shipments()->updatePackage($fetched['id'], [
  'length' => '12.0',
  'width' => '12.0',
  'height' => '10.0',
  'distanceUnit' => 'cm',
  'weight' => '1.2',
  'massUnit' => 'kg',
]);

// İptal
$client->shipments()->cancel($fetched['id']);

// Klonla
$cloned = $client->shipments()->clone($fetched['id']);
echo 'Cloned shipment: ' . ($cloned['id'] ?? '') . PHP_EOL;
```

---

Modeller
--------

[](#modeller)

- Shipment, Transaction, TrackingStatus, Address, ParcelTemplate, ProviderAccount, Webhook, Offer, PriceQuote ve daha fazlası.
- Tam liste: `src/Models/Models.php`.

Enum Kullanımı (TR)
-------------------

[](#enum-kullanımı-tr)

```
use Geliver\Models\ShipmentLabelFileType;

$s = $client->shipments()->get($shipment['id']);
if (($s['labelFileType'] ?? null) === ShipmentLabelFileType::PDF->value) {
  echo "PDF etiket hazır" . PHP_EOL;
}
```

---

Notlar ve İpuçları (TR)
-----------------------

[](#notlar-ve-i̇puçları-tr)

- İstek tarafında `length`, `width`, `height`, `weight` değerleri string gönderilmelidir; örn. `'10.0'`.
- Ondalıklı sayılar response tarafında genelde string olarak gelir; hesaplama için BCMath veya GMP kullanın.
- Teklif beklerken 1 sn aralıkla tekrar sorgulayın; gereksiz yükten kaçının.
- Test gönderisi: `$client->shipments()->create(['test' => true, ...])` veya `createTest([...])`; canlı ortamda `createTest` yerine `$client->shipments()->create(...)` kullanın.
- Takip numarası ile takip URL'si bazı kargo firmalarında teklif kabulünün hemen ardından oluşmayabilir. Paketi kargo şubesine teslim ettiğinizde veya kargo sizden teslim aldığında bu alanlar tamamlanır. Webhooklar ile değerleri otomatik çekebilir ya da teslimden sonra `shipment` GET isteği yaparak güncel bilgileri alabilirsiniz.
- Şehir/İlçe seçimi: cityCode ve cityName birlikte/ayrı kullanılabilir; cityCode daha güvenlidir. Listeler için API'yi kullanın:

```
$cities = $client->geo()->listCities('TR');
$districts = $client->geo()->listDistricts('TR', '34');
```

- Adres kuralları: phone alanı hem gönderici hem alıcı adresleri için zorunludur. Zip alanı gönderici adresi için zorunludur; alıcı adresi için opsiyoneldir. `$client->addresses()->createSender([...])` phone/zip eksikse, `$client->addresses()->createRecipient([...])` phone eksikse hata verir.

Örnekler
--------

[](#örnekler)

- Tam akış: `examples/full_flow.php` (composer install sonrası)
- Tek aşamada gönderi (Create Transaction): `examples/onestep.php`
- Kapıda ödeme: `examples/pod.php`
- Kendi anlaşmanızla etiket satın alma: `examples/ownagreement.php`

---

Hatalar ve İstisnalar
---------------------

[](#hatalar-ve-i̇stisnalar)

- İstemci şu durumlarda `ApiException` fırlatır: (1) HTTP 4xx/5xx; (2) JSON envelope `result === false`.
- Hata alanları: `$e->codeStr`, `$e->additionalMessage`, `$e->status`, `$e->getMessage()`, `$e->body`.

```
try {
  $client->shipments()->create([/* ... */]);
} catch (\Geliver\ApiException $e) {
  error_log('code: ' . $e->codeStr);
  error_log('message: ' . $e->getMessage());
  error_log('additional: ' . $e->additionalMessage);
  error_log('status: ' . $e->status);
}
```

Diğer Örnekler (PHP)

- Kendi Kargo Anlaşmanız (Provider Accounts)

```
$acc = $client->providers()->createAccount([
  'username' => 'user', 'password' => 'pass', 'name' => 'My Account', 'providerCode' => 'SURAT',
  'version' => 1, 'isActive' => true, 'isPublic' => false, 'sharable' => false, 'isDynamicPrice' => false,
]);
$list = $client->providers()->listAccounts();
$client->providers()->deleteAccount($acc['id'], true);
```

- Kargo Şablonları (Parcel Templates)

```
$tpl = $client->parcelTemplates()->create([
  'name'=>'Small Box','distanceUnit'=>'cm','massUnit'=>'kg','height'=>4,'length'=>4,'weight'=>1,'width'=>4,
]);
$tpls = $client->parcelTemplates()->list();
$client->parcelTemplates()->delete($tpl['id']);
```

[![Geliver Kargo Pazaryeri](https://camo.githubusercontent.com/eeb53e581ea3913ddb5c831888f621f49469c2fbece5019c03ae17f0c7d9e10f/68747470733a2f2f67656c697665722e696f2f67656c697665726c6f676f2e706e67)](https://geliver.io/)Geliver Kargo Pazaryeri:

Etiketler (Tags): php, composer, sdk, api-client, geliver, kargo, kargo-pazaryeri, shipping, e-commerce, turkey

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance86

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~24 days

Total

5

Last Release

74d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/895553?v=4)[Ercument ESER](/maintainers/ercu)[@ercu](https://github.com/ercu)

---

Top Contributors

[![ercu](https://avatars.githubusercontent.com/u/895553?v=4)](https://github.com/ercu "ercu (30 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/geliver-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/geliver-sdk/health.svg)](https://phpackages.com/packages/geliver-sdk)
```

###  Alternatives

[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[convertkit/convertkitapi

Kit PHP SDK for the Kit API

2167.1k1](/packages/convertkit-convertkitapi)[mapado/rest-client-sdk

Rest Client SDK for hydra API

1125.9k2](/packages/mapado-rest-client-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)