Gönderi İptali

Bu API, mevcut bir gönderiyi iptal etmek için kullanılır. İptal edilen gönderiler kargo firmasına bildirilir ve etiket geçersiz hale gelir.

Endpoint Bilgileri

Özellik	Değer
URL	`{{BASE_URL}}/api/v1/consignments/{idBarcodeOrReference}/cancel`
HTTP Metodu	`POST`
İçerik Türü	`application/json`
Kimlik Doğrulama	`APIKEY` header

İptal Edilebilir Durumlar

Tüm gönderiler iptal edilemez. Aşağıdaki durumlardaki gönderiler iptal edilebilir:

Durum	İptal Edilebilir
Etiket oluşturuldu, henüz teslim alınmadı	✅ Evet
Kargoya verildi (transit)	⚠️ Provider'a bağlı
Teslim edildi	❌ Hayır
Zaten iptal edilmiş	❌ Hayır

Önemli: Kargo firmasına teslim edildikten sonra iptal işlemi provider'ın kurallarına bağlıdır. Bazı provider'lar transit gönderilerin iptalini desteklemez.

İstek Parametreleri

URL Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
`idBarcodeOrReference`	String/Integer	ZORUNLU	Gönderi ID'si, barkodu veya referans numarası

Esnek Arama: Gönderiyi ID, ComToHome barkodu (C2H...) veya kendi referans numaranız (reference_no) ile iptal edebilirsiniz.

Örnek Kullanım

ID ile İptal

curl -X POST "{{BASE_URL}}/api/v1/consignments/632236/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

<?php
$client = new \GuzzleHttp\Client();

$consignmentId = 632236;

$response = $client->request('POST', "{{BASE_URL}}/api/v1/consignments/{$consignmentId}/cancel", [
    'headers' => [
        'Content-Type' => 'application/json',
        'APIKEY' => '{{APIKEY}}'
    ]
]);

$body = json_decode($response->getBody(), true);

if ($body['status']) {
    echo "Gönderi başarıyla iptal edildi: " . $body['data']['consignment'];
}

<?php
$consignmentId = 632236;

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "{{BASE_URL}}/api/v1/consignments/{$consignmentId}/cancel",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'APIKEY: {{APIKEY}}'
    ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['status']) {
    echo "Gönderi başarıyla iptal edildi";
} else {
    echo "Hata: " . $result['errors'][0]['message'];
}

curl_close($ch);

Barkod ile İptal

curl -X POST "{{BASE_URL}}/api/v1/consignments/C2H07238640094/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

Referans Numarası ile İptal

curl -X POST "{{BASE_URL}}/api/v1/consignments/ORDER-2024-001/cancel" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}"

API Cevabı

Başarılı Yanıt

{
    "status": true,
    "message": "Cancelled by customer",
    "data": {
        "consignment": 632236
    }
}

Response Alanları

Alan	Tip	Açıklama
`status`	Boolean	İşlem başarı durumu
`message`	String	İptal sonuç mesajı
`data.consignment`	Integer	İptal edilen gönderi ID'si

Hata Yanıtları

Gönderi Bulunamadı

{
    "status": false,
    "errors": [
        {
            "message": "Consignment not found"
        }
    ]
}

İptal Başarısız

{
    "status": false,
    "errors": [
        {
            "message": "Consignment cancel failed: Shipment already in transit"
        }
    ]
}

Yaygın Hata Senaryoları

Hata	Açıklama	Çözüm
`Consignment not found`	Gönderi bulunamadı	ID, barkod veya referans numarasını kontrol edin
`Consignment cancel failed`	İptal işlemi başarısız	Gönderi durumunu kontrol edin
`Shipment already delivered`	Gönderi teslim edilmiş	Teslim edilen gönderiler iptal edilemez
`Shipment already cancelled`	Gönderi zaten iptal edilmiş	-

Gönderi Silme (DELETE)

İptal işleminden farklı olarak, gönderiyi tamamen silmek için DELETE metodu kullanılabilir:

Özellik	Değer
URL	`{{BASE_URL}}/api/v1/consignments/{idBarcodeOrReference}`
HTTP Metodu	`DELETE`

curl -X DELETE "{{BASE_URL}}/api/v1/consignments/632236" \
  -H "APIKEY: {{APIKEY}}"

Fark: cancel endpoint'i gönderiyi iptal eder ve kayıtlarda tutar. DELETE endpoint'i ise gönderiyi önce iptal eder, sonra sistemden siler.

Sonraki Adımlar

Gönderi iptal edildikten sonra:

Webhook: İptal durumu webhook ile bildirilir (yapılandırılmışsa)
Yeni Gönderi: Gerekirse aynı bilgilerle yeni gönderi oluşturabilirsiniz
Raporlama: İptal edilen gönderiler raporlarda görüntülenebilir