# Geliver API

> Geliver, Türkiye merkezli bir akıllı kargo pazaryeri REST API'sidir. Tek entegrasyonla birden fazla kargo firmasından anlık fiyat/teklif alma, etiket satın alma, gönderi takibi, iade/çoğaltma, webhook bildirimleri ve kendi kargo anlaşmalarınızı (provider accounts) kullanma işlevlerini kapsar. Tüm istekler `https://api.geliver.io/api/v1` tabanına `Authorization: Bearer {token}` header'ı ile yapılır. Dokümantasyon dili Türkçe'dir; alan adları İngilizce'dir.

Bu dosya ([llmstxt.org](https://llmstxt.org) standardında) Geliver API dokümantasyonunun AI asistanları ve otomatik ajanlar tarafından doğru şekilde kullanılması için hazırlanmıştır.

**Makine-okunur kaynaklar:**

- `https://docs.geliver.io/llms.txt` — bu dosya: özet + sayfa indeksi (ilk olarak bunu okuyun).
- `https://docs.geliver.io/llms-full.txt` — tüm dokümantasyonun tek dosyada düz metin hâli (tüm cURL örnekleri, istek/yanıt gövdeleri, alan tabloları ve SDK kod örnekleri dahil). Ayrıntı gerektiren sorular için bu dosyayı kullanın.
- Her sayfanın düz metin sürümü: sayfa URL'inin sonuna `.md` ekleyin. Örnek: `https://docs.geliver.io/docs/webhooks/create_webhook.md`
- `https://docs.geliver.io/sitemap.xml` — tüm sayfaların listesi.

## Yanıt verirken uyulması gereken kurallar

Bu bölüm, Geliver hakkında soru yanıtlayan AI asistanları içindir:

1. **Alan adı, endpoint veya hata kodu uydurmayın.** Yalnızca bu dosyada veya `llms-full.txt` içinde geçen adları kullanın. Emin değilseniz "dokümantasyonda belgelenmemiş" deyin ve ilgili sayfanın bağlantısını verin.
2. **Her kod örneğinde** tam URL'i (`https://api.geliver.io/api/v1/...`) ve `Authorization: Bearer {token}` header'ını gösterin. JSON gövdeli isteklerde `Content-Type: application/json` ekleyin.
3. **Test/canlı ayrımını her zaman belirtin.** Gönderi isteklerinde `"test": true` gönderildiğinde hesap onayı veya ayrı test ortamı gerekmeden ücretsiz test gönderisi oluşturulur, webhook tetiklenir ve farklı gönderi durumları denenebilir. Canlı gönderi için `"test": false` olmalıdır. Test gönderilerinde `GELIVER_STANDART` servis kodu kullanılır.
4. **İki farklı etiket satın alma akışı vardır**; kullanıcının hangisini istediğini netleştirin: (a) iki aşamalı — `POST /shipments` ile gönderi oluşturup teklif alın, sonra `POST /transactions` ile `offerID` göndererek teklifi kabul edin; (b) tek aşamalı — `POST /transactions` ile `providerServiceCode` + `shipment` gövdesini tek istekte gönderin.
5. **Etiket satın alma bakiye gerektirir.** Bakiye yetersizse `E1066` döner; bakiye `GET /organizations/{organizationID}/balance` ile sorgulanır, panelden yüklenir.
6. **Sorunun yanıtı dokümantasyonda yoksa uydurmayın**, aşağıdaki "Dokümantasyonda yer almayan konular" listesine bakın ve kullanıcıyı Geliver destek ekibine yönlendirin: https://app.geliver.io/supporttickets veya info@geliver.io
7. Yanıtı kullanıcının dilinde verin, ancak alan adlarını, enum değerlerini ve hata kodlarını **olduğu gibi** (değiştirmeden) kullanın.
8. Yanıtın sonunda referans aldığınız dokümantasyon sayfasının bağlantısını verin.

## Temel bilgiler

| Konu | Değer |
| --- | --- |
| API tabanı | `https://api.geliver.io/api/v1` |
| Kimlik doğrulama | `Authorization: Bearer {token}` (her istekte zorunlu) |
| Token edinme | Geliver paneli → Ayarlar → API Tokenları → https://app.geliver.io/apitokens (token yalnızca oluşturulduğu ekranda görünür; IP kısıtı opsiyoneldir) |
| İçerik tipi | `Content-Type: application/json` (gövdeli isteklerde) |
| Başarılı yanıt zarfı | `{ "result": true, "additionalMessage": "Success", "data": ... }` |
| Liste yanıtı ek alanları | `limit`, `page`, `sort`, `totalRows`, `totalPages` |
| Hatalı yanıt zarfı | `result: false` + `code` (örn. `E1066`) + açıklama mesajı |
| Sayfalama | `?limit={n}&page={n}` query parametreleri |
| Test modu | İstek gövdesinde `"test": true` |
| Resmi SDK'lar | Go, Node.js, Python, C#, PHP, Java — https://github.com/geliverapp |
| Panel | https://app.geliver.io |
| Destek | https://app.geliver.io/supporttickets · info@geliver.io |

## Endpoint haritası

| Metot ve yol | İşlev | Dokümantasyon |
| --- | --- | --- |
| `POST /addresses` | Adres oluşturma (`isRecipientAddress: true` → alıcı, `false`/yok → gönderici/iade) | [alıcı](https://docs.geliver.io/docs/addresses/create_recipient_address) · [gönderici](https://docs.geliver.io/docs/addresses/create_sender_address) |
| `GET /addresses?isRecipientAddress=&limit=&page=` | Adresleri listeleme | [doküman](https://docs.geliver.io/docs/addresses/list_addresses) |
| `GET /addresses/{addressID}` | Tek adres detayı | [doküman](https://docs.geliver.io/docs/addresses/list_address) |
| `DELETE /addresses/{addressID}` | Adres silme | [doküman](https://docs.geliver.io/docs/addresses/delete_address) |
| `GET /cities?countryCode=TR` | Şehir listesi (`cityCode` = plaka kodu) | [doküman](https://docs.geliver.io/docs/addresses/list_cities) |
| `GET /districts?countryCode=TR&cityCode=34` | İlçe listesi (`districtID`, `districtName`) | [doküman](https://docs.geliver.io/docs/addresses/list_districts) |
| `GET /organizations/{organizationID}/balance` | Bakiye ve borç sorgulama | [doküman](https://docs.geliver.io/docs/prices/get_balance) |
| `GET /priceList?paramType=parcel&length=&width=&height=&weight=` | Paket ölçülerine göre tüm kargo firmalarından anlık fiyat | [doküman](https://docs.geliver.io/docs/prices/list_prices) |
| `POST /shipments` | Gönderi oluşturma ve kargo firmalarından teklif alma (iki aşamalı akışın 1. adımı) | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_two_step) |
| `POST /transactions` (`offerID`) | Teklifi kabul edip etiket satın alma (iki aşamalı akışın 2. adımı) | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/accept_offer) |
| `POST /transactions` (`providerServiceCode` + `shipment`) | Tek istekte gönderi oluşturup etiket satın alma | [standart](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/) · [kapıda ödeme](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_payment_on_delivery) · [kendi anlaşmanız](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_provider) |
| `GET /shipments` | Gönderileri filtreleyerek listeleme | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/get_all_shipments) |
| `GET /shipments/{shipmentID}` | Tek gönderi detayı, takip numarası/URL'i ve takip durumu | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/get_shipment) |
| `PATCH /shipments/{shipmentID}` | Etiketi henüz satın alınmamış gönderinin paket ölçülerini güncelleme | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/update_package_shipment) |
| `DELETE /shipments/{shipmentID}` | Gönderiyi iptal etme | [doküman](https://docs.geliver.io/docs/shipments_and_transaction/cancel_shipment) |
| `POST /shipments/{shipmentID}` | Aynı yol iki işi yapar: gövdede `isReturn: true` → **iade** gönderisi; `isReturn` yok/`false` → gönderiyi **çoğaltma**. Gövde alanlarının tümü opsiyoneldir. | [çoğaltma](https://docs.geliver.io/docs/shipments_and_transaction/clone_shipment) · [iade](https://docs.geliver.io/docs/shipments_and_transaction/return_shipment) |
| `POST /parceltemplates` | Tekrar kullanılabilir paket ölçüsü şablonu oluşturma | [doküman](https://docs.geliver.io/docs/parcel_templates/create_parcel_templates) |
| `GET /parceltemplates` | Şablonları listeleme | [doküman](https://docs.geliver.io/docs/parcel_templates/list_parcel_templates) |
| `DELETE /parceltemplates/{templateID}` | Şablon silme | [doküman](https://docs.geliver.io/docs/parcel_templates/delete_parcel_templates) |
| `POST /provideraccounts` | Kendi kargo anlaşmanızı bağlama (`providerCode` + firma kullanıcı bilgileri) | [doküman](https://docs.geliver.io/docs/providers/create_provider_account) |
| `GET /provideraccounts` | Bağlı anlaşmaları listeleme (`providerAccountID` buradan alınır) | [doküman](https://docs.geliver.io/docs/providers/list_provider_accounts) |
| `DELETE /provideraccounts/{providerAccountID}?isDeleteAccountConnection=true` | Anlaşma bağlantısını silme | [doküman](https://docs.geliver.io/docs/providers/delete_provider_account) |
| `POST /webhook` | Webhook kaydı oluşturma (`type`, `url`) | [doküman](https://docs.geliver.io/docs/webhooks/create_webhook) |
| `GET /webhook` | Webhookları listeleme | [doküman](https://docs.geliver.io/docs/webhooks/list_webhooks) |
| `PUT /webhook` | Kayıtlı webhook'u örnek veriyle tetikleyip test etme | [doküman](https://docs.geliver.io/docs/webhooks/test_webhook) |
| `DELETE /webhook/{webhookID}` | Webhook silme | [doküman](https://docs.geliver.io/docs/webhooks/delete_webhook) |

## Sabit değerler (enum)

- **`statusFilter` — gönderi durumları:** `CREATED`, `GOT_OFFERS`, `OFFER_ACCEPTED`, `TRACKING_CODE_CREATED`, `LABEL_PRINTED`, `SHIPPED`, `DELIVERED`, `CANCELED`, `RETURNED`, `RETURN_SHIPPED`, `FAILED` → [gönderileri listeleme](https://docs.geliver.io/docs/shipments_and_transaction/get_all_shipments)
- **`trackingStatusCode` — takip durumları:** `PRE_TRANSIT`, `TRANSIT`, `DELIVERED`, `FAILURE`, `RETURNED`, `CANCELED`, `UNKNOWN`. Her birinin alt durumları (`trackingSubStatusCode`, örn. `out_for_delivery`, `pickup_failed`, `package_lost`) için → [takip durum kodları](https://docs.geliver.io/docs/shipments_and_transaction/tracking_status_codes)
- **`providerServiceCode` — kargo hizmet kodları (örnekler):** `YURTICI_STANDART`, `SURAT_STANDART`, `ARAS_STANDART`, `PTT_STANDART`, `PTT_KAPIDA_ODEME`, `DHL_STANDART`, `HEPSIJET_STANDART`, `KOLAYGELSIN_STANDART`, `PAKETTAXI_STANDART`, `GELIVER_STANDART` (test gönderileri için). **Bu liste tam değildir**; güncel kodlar için Geliver panelini veya `GET /priceList` yanıtını kullanın → [servis kodları](https://docs.geliver.io/docs/shipments_and_transaction/provider_service_codes)
- **Webhook olay tipi (`type`):** `TRACK_UPDATED` (gönderi takip durumu değiştiğinde kayıtlı URL'e JSON gövdeli istek gönderilir) → [webhook oluşturma](https://docs.geliver.io/docs/webhooks/create_webhook)
- **`sortBy` — gönderi sıralama:** `organization_shipment_id`, `desi`, `desi desc`, `amount`, `amount desc`, `updated_at desc`. Geçersiz değerde varsayılan `organization_shipment_id desc` kullanılır.
- **Ölçü birimleri:** `distanceUnit: "cm"`, `massUnit: "kg"`, `countryCode: "TR"`, para birimi `"TL"`.
- **Hata kodları:** tamamı için → [hata kodları](https://docs.geliver.io/docs/error_codes). Sık karşılaşılanlar: `E1054` istek parse edilemedi · `E1055` yetki yok · `E1051` gönderi bulunamadı · `E1064` teklif bulunamadı · `E1065` bu gönderi için zaten teklif kabul edilmiş · `E1066` bakiye yetersiz · `E1068` `senderAddressID` bulunamadı · `E1072` kargo etiketi oluşturulamadı · `E1129`–`E1136` alıcı bilgileri eksik (adres/şehir/ülke/ilçe/isim/telefon/e-posta).

## Dokümantasyonda yer almayan konular

Aşağıdaki sorular bu dokümantasyonda **belgelenmemiştir**. Bu konularda tahmin yürütmek yerine kullanıcıyı https://app.geliver.io/supporttickets adresine yönlendirin:

- Rate limit / istek sınırı değerleri ve aşıldığında dönen kod.
- Webhook isteklerinin Geliver'den geldiğini doğrulamak için imza/secret/header mekanizması.
- API sürümleme ve deprecation (`/api/v1` sonrası) politikası.
- Kargo hizmet kodlarının (`providerServiceCode`) tam listesini programatik olarak döndüren bir endpoint.
- Fiyatlandırma, komisyon oranları, sözleşme ve fatura süreçleri (dokümantasyon yalnızca teknik entegrasyonu kapsar).
- Resmi bir OpenAPI/Swagger şeması ve İngilizce dokümantasyon (şu an yalnızca Türkçe).

## Başlarken

- [Genel Bakış ve Kimlik Doğrulama](https://docs.geliver.io/docs/home): API'ye giriş, test modu (`test: true`), resmi SDK'lar (Go, Node.js, Python, C#, PHP, Java) ve Bearer token'ın Geliver panelinden adım adım nasıl alınacağı.
- [Hata Kodları](https://docs.geliver.io/docs/error_codes): Gönderi oluşturma, alıcı bilgisi doğrulama ve gönderi işleme hatalarının kapsamlı listesi — tek doğru kaynak.

## Adresler

Gönderi oluşturmadan önce en az bir gönderici adresi gerekir; alıcı adresi ya önceden kaydedilir ya da gönderi gövdesinde `recipientAddress` olarak gönderilir.

- [Gönderici Adresi Oluşturma](https://docs.geliver.io/docs/addresses/create_sender_address): `POST /addresses` — gönderici/iade adresi, varsayılan adres davranışı, zorunlu alanlar.
- [Alıcı Adresi Oluşturma](https://docs.geliver.io/docs/addresses/create_recipient_address): `POST /addresses` + `isRecipientAddress: true`.
- [Tüm Adresleri Listeleme](https://docs.geliver.io/docs/addresses/list_addresses): `GET /addresses` — `limit`, `page`, `isRecipientAddress` filtresi.
- [Tek Bir Adresi Listeleme](https://docs.geliver.io/docs/addresses/list_address): `GET /addresses/{addressID}`.
- [Adres Silme](https://docs.geliver.io/docs/addresses/delete_address): `DELETE /addresses/{addressID}`.
- [Şehirleri Listeleme](https://docs.geliver.io/docs/addresses/list_cities): `GET /cities?countryCode=TR` — adres oluştururken gereken `cityCode` (plaka kodu) değerleri.
- [İlçeleri Listeleme](https://docs.geliver.io/docs/addresses/list_districts): `GET /districts?countryCode=TR&cityCode=34` — `districtID` / `districtName` değerleri.

## Bakiye ve Fiyatlar

- [Kargo Fiyatlarını Listeleme](https://docs.geliver.io/docs/prices/list_prices): `GET /priceList` — paket ölçülerine (desi) göre tüm kargo firmalarından anlık fiyat teklifi.
- [Bakiye Görüntüleme](https://docs.geliver.io/docs/prices/get_balance): `GET /organizations/{organizationID}/balance` — bakiye ve borç bilgisi.

## Gönderi Oluşturma ve Etiket Satın Alma

- [Gönderi Oluşturup Teklifleri Alma](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_two_step): `POST /shipments` — iki aşamalı akışın 1. adımı; tam istek gövdesi (`senderAddressID`, ölçüler, `items`, `recipientAddress`, `order`) ve SDK örnekleri.
- [Teklifleri Kabul Etme](https://docs.geliver.io/docs/shipments_and_transaction/accept_offer): `POST /transactions` — `offerID` ile teklifi kabul edip etiketi (`labelURL`) ve barkodu alma.
- [Tek Aşamada Etiket Satın Alma](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/): `POST /transactions` — `providerServiceCode` + `shipment` gövdesi ile tek istekte etiket satın alma.
- [Kapıda Ödeme ile Etiket Satın Alma](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_payment_on_delivery): `POST /transactions` — `productPaymentOnDelivery: true` ve kapıda ödeme destekli servis kodu (örn. `PTT_KAPIDA_ODEME`).
- [Kendi Anlaşmanız ile Etiket Satın Alma](https://docs.geliver.io/docs/shipments_and_transaction/create_shipment/create_shipment_provider): `POST /transactions` — `providerAccountID` ile kendi kargo anlaşmanız üzerinden etiket satın alma.

## Gönderiler ve Takip

- [Gönderileri Listeleme](https://docs.geliver.io/docs/shipments_and_transaction/get_all_shipments): `GET /shipments` — `statusFilter`, `startDate`/`endDate`, `orderNumber`, `merchantCode`, `invoiceID`, `providerServiceCode`, `storeIdentifier`, `isReturned`, `tags`, `filter`, `sortBy` ve sayfalama.
- [Belirli Bir Gönderinin Detayları](https://docs.geliver.io/docs/shipments_and_transaction/get_shipment): `GET /shipments/{shipmentID}` — takip numarası, takip URL'i, `trackingStatus` detayları.
- [Gönderi Paketlerini Güncelleme](https://docs.geliver.io/docs/shipments_and_transaction/update_package_shipment): `PATCH /shipments/{shipmentID}`.
- [Gönderiyi İptal Etme](https://docs.geliver.io/docs/shipments_and_transaction/cancel_shipment): `DELETE /shipments/{shipmentID}`.
- [Gönderiyi Çoğaltma](https://docs.geliver.io/docs/shipments_and_transaction/clone_shipment): `POST /shipments/{shipmentID}` — `isReturn` gönderilmediğinde/`false` olduğunda çoğaltma davranışı.
- [Gönderiyi İade Etme](https://docs.geliver.io/docs/shipments_and_transaction/return_shipment): `POST /shipments/{shipmentID}` + `isReturn: true` — iade gönderisinde `senderAddress`, iade paketinin teslim edileceği adresi belirtir.
- [Kargo Takip Durum Kodları](https://docs.geliver.io/docs/shipments_and_transaction/tracking_status_codes): `trackingStatusCode` / `trackingSubStatusCode` tam listesi ve Türkçe açıklamaları.
- [Sağlayıcı Servis Kodları](https://docs.geliver.io/docs/shipments_and_transaction/provider_service_codes): `providerServiceCode` örnekleri.

## Kargo Şablonları

- [Kargo Şablonu Oluşturma](https://docs.geliver.io/docs/parcel_templates/create_parcel_templates): `POST /parceltemplates`.
- [Kargo Şablonlarını Listeleme](https://docs.geliver.io/docs/parcel_templates/list_parcel_templates): `GET /parceltemplates`.
- [Kargo Şablonu Silme](https://docs.geliver.io/docs/parcel_templates/delete_parcel_templates): `DELETE /parceltemplates/{templateID}`.

## Webhooklar

- [Webhook Oluşturma](https://docs.geliver.io/docs/webhooks/create_webhook): `POST /webhook` — `TRACK_UPDATED` olayında çağrılacak URL kaydı; geliştirme sırasında webhook.site ile test önerisi.
- [Webhookları Listeleme](https://docs.geliver.io/docs/webhooks/list_webhooks): `GET /webhook`.
- [Webhookları Test Etme](https://docs.geliver.io/docs/webhooks/test_webhook): `PUT /webhook` — kayıtlı webhook'u örnek veriyle tetikleme.
- [Webhookları Silme](https://docs.geliver.io/docs/webhooks/delete_webhook): `DELETE /webhook/{webhookID}`.

## Özel Kargo Anlaşmaları (Provider Accounts)

- [Kendi Anlaşmanızı Ekleme](https://docs.geliver.io/docs/providers/create_provider_account): `POST /provideraccounts`.
- [Kendi Anlaşmalarınızı Listeleme](https://docs.geliver.io/docs/providers/list_provider_accounts): `GET /provideraccounts`.
- [Kendi Anlaşmanızı Silme](https://docs.geliver.io/docs/providers/delete_provider_account): `DELETE /provideraccounts/{providerAccountID}`.

## Optional

- [Tam metin dokümantasyon (llms-full.txt)](https://docs.geliver.io/llms-full.txt): Tüm sayfaların derlenmiş düz metin hâli — istek/yanıt gövdeleri, alan tabloları ve SDK kod örnekleri dahil.
- [Geliver SDK'ları (GitHub)](https://github.com/geliverapp): Go, Node.js, Python, C#, PHP ve Java için resmi istemci kütüphaneleri.
- [Geliver Paneli](https://app.geliver.io): API token oluşturma, bakiye yükleme, gönderi yönetimi.
- [Destek Merkezi](https://app.geliver.io/supporttickets): Dokümantasyonda cevap bulunamayan sorular için insan destek ekibi.
- Kategori sayfaları: [Adresler](https://docs.geliver.io/docs/category/adresler) · [Kargo Şablonları](https://docs.geliver.io/docs/category/kargo-şablonları) · [Bakiye ve Fiyatlar](https://docs.geliver.io/docs/category/bakiye-ve-fiyatlar) · [Gönderiler](https://docs.geliver.io/docs/category/gönderiler) · [Gönderi Oluşturma](https://docs.geliver.io/docs/category/gönderi-oluşturma) · [Webhooklar](https://docs.geliver.io/docs/category/webhooklar) · [Özel Kargo Anlaşmaları](https://docs.geliver.io/docs/category/özel-kargo-anlaşmaları)