Teknik Sipariş Yaşam Döngüsü: State Machine ve Status Mapping

Bir bayi panelinde siparişi yalnızca “aktif” veya “tamamlandı” şeklinde izlemek yetersizdir. Sağlam bir entegrasyon; siparişin yerel sistemde oluşturulması, RoketBayim API’ye gönderilmesi, order ID alınması, durum sorgulanması ve nihai sonucun müşteri kaydına yansıtılması için açık bir yaşam döngüsü kullanmalıdır. Bu rehber, sipariş süreçlerini teknik bir durum makinesiyle tasarlamak isteyen geliştiriciler içindir.

Buradaki durum makinesi RoketBayim’in döndürdüğü status değerlerinin yerine geçmez. Amaç, uzak API durumlarıyla kendi uygulamanızdaki gönderim ve hata aşamalarını birbirinden ayırmaktır. Böylece ağ zaman aşımı, geçersiz yanıt veya yerel kayıt hatası gibi teknik durumlar müşteri siparişinin gerçek durumuyla karıştırılmaz.

Neden yerel bir durum makinesi gerekir?

API çağrısı yapılmadan önce bile yerel siparişin doğrulanması, bakiye ve servis kontrolünden geçmesi gerekir. İstek gönderildiğinde yanıt beklenir; ancak zaman aşımı oluşursa uzak sistemde siparişin oluşup oluşmadığı hemen bilinmeyebilir. Başarılı yanıtta order ID alınır ve takip aşaması başlar.

Bu aşamaların tamamını doğrudan Pending alanına yazmak, operasyon ekibinin hangi siparişin gerçekten RoketBayim’e ulaştığını anlamasını zorlaştırır. Yerel teknik durumlar ile sağlayıcı durumlarını ayrı alanlarda tutmak daha güvenlidir.

Önerilen yerel teknik durumlar

RoketBayim durumlarını eşleme

RoketBayim sipariş durumu action=status ile tekli order veya virgülle ayrılmış orders değerleri üzerinden sorgulanabilir. Yanıtta charge, start_count, status, remains ve currency alanları bulunabilir. Uzak status değeri ayrı bir provider_status alanında saklanmalıdır.

• Pending: Yerel teknik durum tracking kalır; uzak sipariş başlangıç bekler.
• Processing veya In progress: tracking sürer; bağlantı ve sayaç izlenir.
• Completed: Terminal sonuçtur; son alanlar kaydedildikten sonra yerel durum closed yapılabilir.
• Partial: Terminal sonuçtur; remains ve nihai ücret ayrıca işlenir.
• Canceled: Terminal sonuçtur; iptal ve bakiye sonucu kaydedilir.

Sipariş oluşturma geçişleri

Başarılı sipariş yanıtı

{
  "order": 23501
}

Order ID alındığında yerel kayıt tek işlem içinde güncellenmelidir. provider_order_id, submitted_at, son API yanıtı ve tracking durumu birlikte yazılır. Aynı yerel siparişe ikinci order ID atanmasını engelleyen benzersiz kısıt kullanın.

Kesin hata ile belirsiz sonucu ayırın

Kesin hata

API açık bir error yanıtı döndürdüyse ve order alanı yoksa siparişin oluşturulmadığı kabul edilebilir. Service not found, minimum miktar veya yetersiz bakiye gibi hatalar veri düzeltilmeden otomatik tekrar edilmemelidir.

Belirsiz sonuç

İstek gönderildikten sonra bağlantı kesilmiş veya yanıt zaman aşımına uğramışsa uzak tarafta sipariş oluşmuş olabilir. Bu kaydı failed yapmak ve otomatik yeniden göndermek mükerrer sipariş riski yaratır. unknown durumuna alın, istek parmak izini ve zamanı kaydedin, operasyon incelemesine yönlendirin.

“Yanıt alamadım” ile “sipariş oluşturulmadı” aynı sonuç değildir.

Durum sorgulama planı

Tracking durumundaki siparişler makul aralıklarla status işlemi üzerinden sorgulanmalıdır. Çok sık sorgu göndermek yerine son sorgu zamanını ve bir sonraki uygun zamanı saklayın. Birden fazla aktif order ID, API’nin çoklu durum sorgusuyla gruplanabilir.

Pending siparişler için başlangıç döneminde daha kısa, uzun süren Processing siparişler için daha geniş aralık kullanılabilir. RoketBayim dokümantasyonu belirli bir rate limit vermiyorsa sabit bir yüksek frekans varsaymayın; operasyon ihtiyacına uygun ölçülü polling tasarlayın.

Terminal durum işleme

Completed

charge, start_count, remains, currency ve son status alanlarını kaydedin. Müşteriye gösterilecek tamamlanma zamanını yerel sistem saatinden ve son başarılı sorgudan üretin.

Partial

remains değeri ve nihai ücret kritik alanlardır. Yerel siparişin tamamını “başarısız” saymak yerine teslim edilen ve kalan miktarı ayrı gösterin. Otomatik yeni sipariş üretmeyin.

Canceled

İptal talebinin sonucu ile sağlayıcının Canceled durumu ayrılmalıdır. İptal talebi gönderildi fakat status hâlâ Processing ise yerel kaydı kapatmayın.

Veri modeli önerisi

{
  "local_order_id": "ORD-2026-1042",
  "technical_status": "tracking",
  "provider_order_id": 23501,
  "provider_status": "Processing",
  "service_id": 1,
  "target_url": "https://example.com/post",
  "quantity": 1000,
  "start_count": 3572,
  "remains": 1000,
  "charge": "0.27819",
  "currency": "TRY",
  "submitted_at": "2026-08-13T10:00:00Z",
  "last_polled_at": "2026-08-13T10:05:00Z"
}

Gerçek API anahtarını veya müşteri parolasını sipariş kaydına eklemeyin. API anahtarı güvenli sır yönetiminde tutulmalıdır.

Geçiş kuralları nasıl korunur?

Durum güncellemelerini koşulsuz yazmayın. closed durumundaki siparişin eski bir gecikmiş sorgu sonucu nedeniyle tekrar tracking yapılmasını engelleyin. Her güncellemede mevcut teknik durum, yeni provider status ve sorgu zamanı kontrol edilmelidir.

Dağıtık çalışan birden fazla worker varsa aynı siparişi eş zamanlı sorgulama veya kapatma riskine karşı kayıt kilidi ya da sürüm numarası kullanın. Güncelleme sırasında beklenen sürüm değişmişse işlem yeniden okunmalıdır.

Olay geçmişi ve denetim izi

Yalnız son durumu saklamak sorun giderme için yeterli değildir. Her geçişi zaman, eski durum, yeni durum, kaynak ve yanıt özetiyle olay tablosuna yazın.

2026-08-13T10:00:00Z validated → submitting
2026-08-13T10:00:01Z submitting → tracking order=23501
2026-08-13T10:05:00Z provider Pending → Processing
2026-08-13T10:45:00Z provider Processing → Completed
2026-08-13T10:45:00Z tracking → closed

Bu geçmiş, müşteri “siparişim ne zaman başladı?” diye sorduğunda tahmin yerine doğrulanmış zaman çizelgesi sunmanızı sağlar.

Alarm verilmesi gereken durumlar

• submitting durumunda normalden uzun kalan kayıtlar
• unknown durumuna geçen yeni siparişler
• provider_order_id olmadan tracking yapılan kayıtlar
• Terminal durumdan aktif duruma geri dönen kayıtlar
• Uzun süre status sorgusu yapılmayan aktif siparişler
• Aynı yerel siparişe bağlı birden fazla provider order ID

Test edilmesi gereken senaryolar

• Başarılı add yanıtı ve order ID kaydı
• Açık error yanıtı ve failed geçişi
• Zaman aşımı ve unknown geçişi
• Pending → Processing → Completed akışı
• Processing → Partial ve remains kaydı
• İptal talebi sürerken durumun değişmemesi
• İki worker’ın aynı siparişi aynı anda güncellemesi
• Gecikmiş eski yanıtın terminal kaydı bozmaması

Canlıya geçiş kontrolü

Durum makinesini canlıya almadan önce mevcut siparişlerin yeni modele nasıl taşınacağını belirleyin. provider_order_id bulunan aktif kayıtları tracking, terminal durumdakileri closed olarak eşleyin. Kimliği veya sonucu belirsiz kayıtları otomatik karar vermek yerine inceleme kuyruğuna alın.

Güncel action ve yanıt alanları için RoketBayim API dokümantasyonunu esas alın.

İşlem sahipliği ve recovery

Her aktif sipariş, belirli bir worker tarafından sonsuza kadar sahiplenilmemelidir. Worker submitting durumuna geçerken kısa bir lease süresi ve worker kimliği yazabilir. İşlem başarıyla tamamlandığında lease temizlenir. Worker kapanırsa süresi dolan kayıt recovery taramasıyla bulunur.

Recovery işi, kaydı doğrudan yeniden göndermemelidir. İstek API’ye gönderilmeden önce worker kapandıysa validated durumuna dönmek güvenli olabilir. Gönderim başlangıç zamanı yazılmış veya ağ çağrısı başlamışsa sonuç belirsiz kabul edilir ve unknown durumuna alınır. Bu ayrım için “request_started_at” ve “response_received_at” alanları yararlıdır.

Manuel müdahale kuralları

Operasyon ekranında teknik durumun serbest metinle değiştirilmesine izin vermeyin. “Yeniden doğrula”, “takibe al”, “belirsiz olarak işaretle” veya “incelemeyi kapat” gibi kontrollü komutlar kullanın. Her komut yetkili kullanıcı, gerekçe ve zaman damgasıyla olay geçmişine yazılmalıdır.

provider_order_id bulunan bir kaydı yeniden gönderme komutu sunmak yüksek risklidir. Böyle bir işlem gerekiyorsa yeni ve bağımsız yerel sipariş oluşturulmalı, eski kayıtla ilişkisi açıkça belirtilmelidir.

Durum makinesinde değişmez kurallar

• provider_order_id bir kez yazıldıktan sonra normal akışta değiştirilemez.
• closed durumdan tracking durumuna otomatik geri dönüş yapılamaz.
• failed kaydı veri düzeltilmeden submitting yapılamaz.
• unknown kaydı otomatik retry worker’ı tarafından alınamaz.
• Her geçiş eski durum ve sürüm koşuluyla atomik uygulanır.
• Terminal provider status tam zaman ve yanıt özetiyle saklanır.

Şema değişikliği ve geriye uyumluluk

Yeni bir provider status değeri geldiğinde entegrasyonun çökmesini önleyin. Tanınmayan değerleri “unknown_provider_status” olarak işaretleyip ham değeri saklayın ve alarm üretin. Bilinmeyen durumu otomatik Completed veya Canceled’a eşlemeyin.

Durum isimlerini kodun farklı yerlerinde sabit string olarak çoğaltmak yerine tek bir sürümlü eşleme modülünde tutun. Yeni sürüm canlıya alındığında eski olay kayıtlarının anlamı korunmalıdır.

Müşteri görünümü ile teknik görünüm

Müşteriye internal durumların tamamını göstermek kafa karıştırabilir. validated ve submitting aşamaları “Sipariş hazırlanıyor”, tracking içindeki Pending “Sırada”, Processing “İşleniyor” olarak sunulabilir. unknown gibi belirsiz durumda yanlış bir başarı mesajı yerine “İnceleniyor” gösterin.

Destek ve teknik ekip ekranında ise local status, provider status, order ID, son sorgu zamanı ve olay geçmişi ayrı ayrı görünmelidir. Aynı veri farklı kullanıcı gruplarına uygun ayrıntı düzeyiyle sunulur.

Raporlama

Durum makinesi, siparişlerin hangi aşamada ne kadar beklediğini ölçmeyi sağlar. validated-to-submitting, submitting-to-tracking ve tracking-to-closed sürelerini ayrı metrikler olarak izleyin. Böylece yerel kuyruk gecikmesi ile sağlayıcı teslimat süresi birbirine karışmaz.

Unknown ve failed oranları entegrasyon kalitesini, Pending ve Partial oranları ise servis davranışını anlamaya yardımcı olur. Bu ayrım teknik ekiple operasyon ekibinin doğru soruna odaklanmasını sağlar.

Örnek kabul kriterleri

Bir sipariş özelliği tamamlandı sayılmadan önce durum geçişleri otomatik testle doğrulanmalıdır. Başarılı add yanıtında order ID aynı veritabanı işlemiyle yazılmalı, takip mesajı yalnız bu kayıt sonrasında üretilmelidir. Kesin error müşteri ekranında düzeltilebilir neden göstermeli; zaman aşımı ise yeni sipariş oluşturmadan inceleme durumuna geçmelidir.

Terminal status alındığında aktif polling durmalı, son charge, currency, start count ve remains değerleri korunmalıdır. Aynı yanıt tekrar işlendiğinde ikinci olay veya müşteri bildirimi üretmemelidir. Bu kabul kriterleri kod incelemesi, entegrasyon testi ve canlı gözlem panelinde birlikte kontrol edilmelidir.

Sonuçlar düzenli mutabakat işiyle ayrıca doğrulanmalıdır.

Her sapma sorumlu ekibe otomatik bildirilmelidir.