Test ortamı: test kargo hesabı

Ayrı bir test hesabı ya da API adresi gerekmez: aynı hesapta açılan test kargo hesabı kargo firmasına istek göndermez, kredi düşmez, faturaya girmez.

Güncelleme: 30 Eki 2026

Ayrı bir test hesabı, API adresi ya da API anahtarı yoktur. Aynı hesabınızda bir test kargo hesabı açarsınız; bu hesaba gönderilen gönderiler kargo firmasına hiçbir işlemde gitmez: oluşturma, takip ve iptal simüle edilir.

Test hesabı

Panelde Test hesabı aç ile firmayı seçersiniz. O firmada açık bir test hesabınız varsa yenisi açılmaz, mevcut hesap kullanılır. Test hesabı GET /api/v3/carrier-accounts yanıtında environment: "simulated" ile görünür.

Kargo hesabının environment alanı üç değer alır: production (gerçek gönderi), carrier_test (kargo firmasının kendi test ortamı; istek firmaya gider, gönderi gerçek değildir) ve simulated (test hesabı; istek firmaya gitmez).

Test hesabı varsayılan değildir (is_default: false), o firmada gerçek hesabınız olmasa da. carrier_account_id göndermeyen istek test hesabına gitmez; test gönderisi için hesabın kimliğini carrier_account_id ile verin. Tek istisna, yalnız test için açılmış ve gerçek kargo hesabı olmayan deneme hesaplarıdır: orada test hesabı varsayılan olabilir.
Aynı API istemcisi ve aynı token'la çalışırsınız.
Firmanın sipariş numarası kuralları ve gönderi formu (options) test hesabında da aynen uygulanır (Firma notları); canlıya geçişte sürpriz olmaz.

Test gönderisi

Gönderi yanıtında sandbox: true döner; gerçek hesabın gönderisinde false. Değeri sunucu hesaptan türetir.
Test gönderileri gönderi listenizde görünür. Listeyi sandbox ile süzebilirsiniz: GET /api/v3/shipments?sandbox=true yalnız test gönderilerini, sandbox=false yalnız gerçek gönderileri döner; verilmezse hepsi. Panelde test gönderileri "Test" olarak işaretlenir.
Kredi ve paket sınırınızdan düşmez, faturaya girmez.
Alıcıya hiçbir bildirim (SMS, e-posta) gönderilmez.
Test gönderileri 30 gün sonra otomatik silinir. Gerçek hesabın gönderisi bu silmeye hiçbir koşulda girmez.

Günlük sınır

Test hesaplarından günde en çok 1.000 gönderi kabul edilir. Sınır her gün 00:00'da (Türkiye saati) sıfırlanır. Aşılınca 429 sandbox_limit_exceeded döner; Retry-After, sınırın sıfırlanmasına kalan süreyi saniye olarak verir. Yeniden gönderimler (aynı numarayla oluşturma, yeniden deneme, düzeltme) sınıra sayılmaz.

Test ortamı geçici olarak kapatılabilir. Kapalıyken test hesabı açma ve test hesabına yeni gönderi 403 sandbox_disabled döner; var olan test gönderileri ve gerçek gönderiler etkilenmez.

Senaryolar

Sipariş numarasının soneki gönderinin nasıl sonuçlanacağını belirler (büyük/küçük harf fark etmez):

Sipariş numarası örneği	Sonuç
`TEST-1001`	Gönderi oluşur (`created`), takip hareketleri dakikalar içinde gelir.
`TEST-1002-REJECT`	Kargo firması reddetmiş gibi: `failed`, `last_error.code: "address"` (firma reddi sebebi).
`TEST-1003-REVIEW`	Kabulde adres incelemesi: `address_review`, sebep `unmatched` (adres doğru olsa da); ilçe seçimiyle çıkar.
`TEST-1004-UNAVAILABLE`	Kargo firmasına ulaşılamamış gibi: ilk iki deneme geçici hata (`retry_scheduled`), üçüncü denemede `created`. Tek başına (toplu gönderi dışında) gönderin.
`TEST-1005-NOCANCEL`	Gönderi oluşur; iptal istenirse kargo firması reddetmiş gibi: `created` kalır, `last_error.code: "not_cancelable"`.
`TEST-1006-REUSED`	Numara kargo firmasında önceden kullanılmış gibi (iptal edilmiş eski kayıt): birkaç saniye içinde `failed`, `last_error.code: "reference_used_at_carrier"`, `last_error.retryable: false` ve `capabilities.retry: false` (Aynı sipariş numarası).

-UNAVAILABLE gönderisi toplu gönderide başka test gönderileriyle birlikte gelirse aynı topluluktaki diğer gönderiler de bir kez yeniden denenir; bu senaryoyu tekil istekle sınayın.

Gönderi oluştuktan sonra takip, firmaya gönderildiği andan (submitted_at) itibaren şu adımlarla ilerler:

Süre	`tracking_status`
Hemen	`info_received`
+2 dakika	`picked_up`
+4 dakika	`in_transit`
+6 dakika	`out_for_delivery`
+8 dakika	`delivered`

Böylece listeleme döngünüzü (Gönderileri izleme) gerçek bir kargo beklemeden sınayabilirsiniz. Test gönderileri gece de aynı hızla ilerler.

Canlıya geçiş

Canlıya geçerken yalnız carrier_account_id değişir: test hesabının kimliği yerine gerçek kargo hesabınızınkini gönderin (ya da alanı göndermeyip firmadaki varsayılan hesabınızı kullanın). İstemci, token ve istek gövdesi aynı kalır.

Var olan bir gönderi test hesabından gerçek hesaba ya da tersine taşınamaz: düzeltmede (PATCH /shipments/{id}) carrier_account_id'yi bu yönde değiştirmek 422 döner. Test gönderisi gerçek firmaya, gerçek gönderi teste gitmez; canlıda gönderiyi gerçek hesapla yeniden oluşturun.

Önerilen test listesi

Token alma ve süresi dolunca yenileme.
Tekil gönderi ve aynı Idempotency-Key ile tekrar (Idempotent-Replayed: true).
Aynı sipariş numarasıyla ikinci gönderi (409 reference_in_use).
Toplu gönderide bir kalemin reddi (diğerleri kabul edilir).
-REJECT gönderisini düzeltip yeniden gönderme (PATCH ya da aynı numarayla yeni istek).
-REVIEW gönderisinde ilçe seçimi (PATCH …/address).
-UNAVAILABLE gönderisinin retry_scheduled üzerinden created olması.
Listeleme döngüsü: updated_since, ardından cursor.
İptal; -NOCANCEL gönderisinde iptal reddi (not_cancelable).
-REUSED gönderisinin reference_used_at_carrier ile failed olması; siparişi yeni numarayla gönderme.