API ile sipariş kontrolünde "işleniyor" durumunun yönetimi

API yanıtında processing ne anlama gelir

processing, in_progress veya eşdeğer başka bir durum, sağlayıcının siparişi işleme aldığını ancak sonucu kesinleştirmediğini gösterir. Promosyon hizmetleri için bu, bağlantı kontrolü, sıra bekleme, görevin başlatılması veya sipariş edilen hacmin kademeli olarak verilmesi olabilir.

Processing başarılı tamamlanmayı doğrulamaz ve hata anlamına da gelmez. Sonrasında sipariş completed, partial, canceled veya failed durumuna geçebilir. Sağlayıcı ara durum döndürdüğü sürece aynı bağlantı ve aynı hacim için yeni bir talep oluşturmayın.

processing durumuyla gelen HTTP 200, API yanıtının başarılı olduğunu gösterir, siparişin başarıyla tamamlandığını değil. Bu olaylar ayrı ayrı saklanmalı ve işlenmelidir.

Sipariş kontrolü için hangi veriler gerekli

Polling için sağlayıcının oluşturma sırasında döndürdüğü harici sipariş ID'si gereklidir. Bunu dahili ID, başlangıç hacmi, hizmet parametreleri, bağlantı, oluşturma zamanı ve ilk API yanıtıyla birlikte saklayın. Siparişi kanal adı, bağlantı veya hacimle aramak güvenilir değildir: bu değerler birden fazla talepte aynı olabilir.

Oluşturmadan sonra zaman aşımı geldiyse talebi otomatik olarak yeniden göndermeyin. Sağlayıcı isteği kabul etmiş, yanıt ise yolda kaybolmuş olabilir. Önce dokümantasyonda varsa sipariş arama yöntemini kullanın ya da durumu kontrole iletin.

Yalnızca güncel durumu saklamanın eksikliği şudur: bir anlaşmazlıkta siparişin ne zaman processing'e geçtiği, ilerleme olup olmadığı ve daha önce hangi yanıtların geldiği geri getirilemez.

curl ile durum sorgusu örneği

Tam adresi, yetkilendirme yöntemini ve alan adlarını sağlayıcının dokümantasyonundan alın. Aşağıda bir şablon gösterilmiştir: açılı parantez içindeki değerler ilgili API'nin verileriyle değiştirilmelidir.

Tek sipariş için GET isteği

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Örnek yanıt:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

completed_quantity ve remains alanları yalnızca yapı örneği olarak verilmiştir. Sağlayıcı progress, start_count, balance veya başka adlar kullanabilir. GET yaklaşımının eksikliği şudur: bazı API'ler durum kontrolünü yalnızca POST ile kabul eder.

POST isteği örneği ve toplu kontrol

Tek siparişin durumu için POST isteği

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

API anahtarını URL satırında iletmeyin. İstek adresleri proxy günlüklerine, analiz sistemlerine, tarayıcı geçmişine ve teknik loglara düşer. POST'un eksikliği şudur: adres çubuğu üzerinden manuel olarak kontrol edilmesi daha zordur, ancak bu, sırrı URL'ye taşımak için bir neden değildir.

Aktif siparişler için toplu istek

API toplu kontrolü destekliyorsa birden fazla ID'yi tek istekte gönderin:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Yanıtı, dizideki öğe konumuna göre değil, harici ID'ye göre dahili siparişle eşleştirin. Toplu kontrolün eksikliği: sağlayıcı tüm siparişleri döndürmeyebilir, liste boyutunu sınırlayabilir veya yalnızca tek bir ID için hata bildirebilir.

processing için polling nasıl planlanır

İlk processing yanıtından sonra bir sonraki kontrolü kuyruğa alın. Aralığı API dokümantasyonuna, hız sınırlarına ve hizmetin niteliğine göre seçin. Durumun hızlı değiştiği görevlerde başlangıçta daha sık kontrol kabul edilebilir. Kademeli promosyonda sürekli kısa istekler genellikle yeni bilgi vermez.

Pratik bir şema, aynı processing yanıtlarından sonra bekleme süresini artırmaktır. İlk kontrol başlangıç gecikmesinden sonra yapılır, ardından aralık belirlenen üst sınıra kadar büyür. API ilerleme veya yeni bir güncelleme zamanı döndürüyorsa sayım bu değişiklikten başlatılabilir.

• Sipariş oluşturulduktan sonra durumu hemen art arda birçok kez kontrol etmeyin: hizmetin kuyruğa alma için zamana ihtiyacı olabilir.
• Tekrarlayan processing durumunda istekler arasındaki aralığı artırın, sabit bir sıklıkta tutmayın.
• Siparişlerin API'yi aynı anda sorgulamaması için görev başlatma zamanına küçük bir rastgele sapma ekleyin.
• Sağlayıcı Retry-After veya benzeri bir öneri iletiyorsa bunu öncelikli olarak kullanın.
• Webhook'lu siparişler için kontrol amaçlı polling'i bırakın: bildirim ulaşmayabilir.

Seyrek polling'in eksikliği şudur: arayüz, fiili tamamlanmadan sonra eski durumu gösterebilir. Çok sık polling'in eksikliği ise API limitlerine takılma, 429 alma ve gereksiz yük oluşturma riskidir.

processing kontrolü için hangi zamanlar saklanmalı

Normal yürütmeyi takılmadan ayırt etmek için tek bir güncel durum yeterli değildir. Her aktif sipariş için oluşturma zamanını, ilk processing alınışını, son başarılı API yanıtını, harici durumun son değişimini ve ilerlemenin son değişimini saklayın.

Ayrıca başlangıç hacmini, doğrulanmış tamamlanan hacmi, kalanı ve sağlayıcının orijinal durumunu saklamak da faydalıdır. API ilerleme vermiyorsa bu, siparişin takıldığını düşünmek için bir neden değildir: son yanıt zamanına ve hizmet koşullarında belirtilmişse beklenen işlem süresine göre hareket edin.

Maksimum bekleme süresi tüm hizmetler için tek bir sayı olarak belirlenemez. Sağlayıcının belirli hizmet için belirttiği süreyi, kuyruk ve veri güncellemesi için dahili bir payla birlikte kullanın. Süre belirtilmemişse her hizmet kategorisi için ayrı bir kural tanımlayın ve fiili işlem geçmişine göre bunu gözden geçirin.

processing değişmiyorsa ne yapmalı

Uzun süren processing bir hatayı kanıtlamaz. Önce başarılı API yanıtlarının gelip gelmediğini, completed_quantity veya remains değerlerinin değişip değişmediğini, webhook olup olmadığını ve hizmet kurallarının değişip değişmediğini kontrol edin. Görünür büyümenin olmaması, platform istatistiklerinin gecikmesinden veya sağlayıcının ilerlemeyi yalnızca sonuçta güncellemesinden kaynaklanabilir.

Dahili bekleme süresi aşıldığında siparişi otomatik olarak iptal etmeyin. Sıra dışı bir durum kontrolü yapın, varsa ayrı bir yöntemle veri isteyin ve bildirim geçmişini kontrol edin. Sağlayıcı hâlâ processing'i doğruluyorsa siparişi dahili olarak "kontrol gerekli" durumuna alın, ancak harici durumu değiştirmeden saklayın.

• Son doğrulanmış yanıtın zamanını ve API yanıtının tamamını kaydedin.
• Önceki sorgudan bu yana ilerlemenin değişip değişmediğini kontrol edin.
• Dahili eşik aşıldıktan sonra otomatik isteklerin sıklığını azaltın.
• Desteğe harici ID, bağlantı, hizmet parametreleri, durum geçmişi ve teknik hataları iletin.
• Sağlayıcıdan yanıt veya açık bir nihai durum gelene kadar kalanı yeniden başlatmayın.

Manuel kontrolün eksikliği şudur: sipariş destek ekibinin dikkatini gerektirir. Ancak otomatik iptal veya mükerrer kayıt daha tehlikelidir: yürütme sağlayıcıda devam ediyor olabilir.

İstek hatasını sipariş durumundan nasıl ayırt etmeli

Ağ hatası, zaman aşımı, HTTP 429 ve 5xx yanıtı siparişin kendi durumunu bildirmez. Bunlar yalnızca yeni ve güvenilir bir durumun alınamadığını gösterir. Böyle bir durumda son doğrulanmış durumu bırakın, teknik hatayı kaydedin ve yeni bir kontrol planlayın.

429 durumunda başlık iletilmişse Retry-After'ı dikkate alın. Geçici ağ hatalarında ve 5xx'te denemeler arasındaki beklemeyi artırın. Yetkilendirme, imza veya erişim hakkı hatasında sık yeniden deneme yapmayın: anahtarı, token geçerlilik süresini, IP kısıtlamalarını ve erişim ayarlarını kontrol etmek gerekir.

API HTTP 200 döndürdüyse ancak JSON ayrıştırılamıyorsa veya yanıtta order_id ve status yoksa yanıt gövdesini olduğu gibi saklayın ve kontrolü geçersiz olarak işaretleyin. Durumun eksikliğini completed, canceled veya processing ile değiştirmeyin.

Otomatik tekrar istekleri ne zaman durdurulmalı

Polling sonsuz olmamalıdır. Geçici hatalar için teknik tekrar sayısını sınırlayın ve siparişin processing'de kalma toplam süresini ayrıca kontrol edin. Tekrar limiti tüketildikten sonra kontrol görevini inceleme kuyruğuna aktarın, her dakika sonuçsuz yeni istekler oluşturmayın.

Yöntem yalnızca veri okuyorsa durum isteğini tekrarlamak genellikle güvenlidir. Oluşturma, iptal, bakiye yükleme, yeniden başlatma ve iade yöntemleri zaman aşımından sonra mekanik olarak tekrarlanamaz. İdempotent anahtar veya sağlayıcıdan açık bir onay olmadan böyle bir tekrar siparişi iki kez değiştirebilir.

Tekrar sınırlamasının eksikliği şudur: güncellemelerin bir kısmı manuel bir görev haline gelir. Sonsuz tekrarlar daha kötüdür: hatayı gizler, limitleri tüketir ve günlük incelemesini zorlaştırır.

processing sonrası nihai durum nasıl kabul edilir

Geç gelen bir polling yanıtı veya eski bir webhook nedeniyle completed durumundan processing'e geri geçişe izin vermeyin. Her güncellemede sağlayıcıdan gelen olay zamanını, varsa sıra numarası sürümünü ve mevcut dahili durumu karşılaştırın.

• new ve pending, processing, canceled veya failed durumuna geçebilir.
• processing, completed, partial, canceled veya failed durumuna geçebilir.
• partial otomatik olarak completed sayılmamalıdır.
• completed, canceled ve failed genellikle nihai kabul edilir ve otomatik geri dönüşü engeller.
• Bilinmeyen durum veya geçersiz geçiş ayrı bir kontrol gerektirir.

Katı geçiş tablosunun da bir eksikliği vardır: sağlayıcı geçerli yeni bir durum ekleyebilir. Bu nedenle orijinal durumu saklayın ve dahili sınıflandırmayla üzerine yazmayın.

partial ve sipariş kalanı nasıl işlenir

Partial, başlangıç hacminin yalnızca bir kısmının doğrulandığı anlamına gelir. API yanıtında fiilen gerçekleştirilen miktar, kalan, neden ve telafi verileri bulunabilir. Bu değerleri ayrı ayrı saklayın: siparişin başlangıç hacmi, tamamlanan miktarla değiştirilmemelidir.

Örnek bir nihai yanıt şöyle görünebilir:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Önce API'nin tam olarak neyi doğruladığını belirleyin: iade zaten gerçekleşti mi, iade yalnızca planlandı mı, kalan iptal edildi mi yoksa desteğe başvuru mu gerekiyor. İadeyle ilgili alan yoksa kalanı otomatik olarak telafi edilmiş saymayın.

Gerçekleştirilmeyen kısmı ayrı bir karar olmadan yeniden başlatmayın. Sağlayıcı hâlâ hesaplamayı tamamlıyor olabilir, platform istatistikleri gecikmeyle güncellenebilir ve yeni bir talep mükerrer promosyon oluşturabilir. Onay beklemenin eksikliği şudur: kalan hemen kapatılmaz, ancak fazladan sipariş oluşmaz.

Webhook'lar kontrol amaçlı sorgunun yerini tutmaz

Webhook, bir sonraki polling'i beklemeden sipariş kartını olaydan hemen sonra güncellemeye olanak tanır. İşleyicide siparişi harici ID'ye göre bulun, imzayı veya sırrı doğrulayın, olay ID'sini saklayın ve geçişi yalnızca geçerliliği kontrol ettikten sonra uygulayın.

Webhook'un tekrar teslimi güvenli olmalıdır: aynı olay yeni bir değişiklik olarak sayılmamalıdır. Olaylar sıra dışı da gelebilir, bu nedenle nihai bir siparişi yalnızca geç gelen processing nedeniyle geriye almayın.

Webhook'lar istikrarlı olsa bile kontrol amaçlı polling gereklidir. Webhook'ların eksikliği daha karmaşık kurulumdur: erişilebilir bir işleyici, sahte isteklere karşı koruma, tekilleştirme ve olay günlüğü gerekir.

processing ve takılma durumunda müşteriye ne gösterilmeli

Arayüzde tüm teknik JSON'un gösterilmesi gerekmez. processing için "sipariş işlemde" durumu yeterlidir. API güvenilir bir ilerleme ilettiyse doğrulanmış hacmi başlangıç hacminden ayrı gösterin ve bunu nihai sonuç olarak sunmayın.

Dahili kontrol süresini aşan sipariş için "yürütmeyi kontrol ediyoruz" gibi anlaşılır bir durum kullanın. Sağlayıcı yanıtıyla doğrulanana kadar iptal, iade veya tamamlanma bildirmeyin.

Bildirimler siparişin kabulünde, nihai tamamlanmada, partial durumunda, iptalde, hatada ve kontrol gerektiğinde faydalıdır. Her polling sonrası mesajlar gürültü yaratır ve müşterinin talebin gerçek durumunu anlamasına yardımcı olmaz.

İşlem günlüğünde hangi kayıtlar gerekli

Yanıt geçmişi takılı bir processing'i, kaybolan bir webhook'u, kısmi yürütmeyle ilgili anlaşmazlığı ve arayüz ile API arasındaki farkı çözmeye yardımcı olur. Her çağrı için harici ID'yi, güncelleme kaynağını, istek ve yanıt zamanını, HTTP kodunu, orijinal durumu, normalize edilmiş durumu, ilerlemeyi, kalanı ve teknik hata metnini saklayın.

Normal günlüklere API anahtarlarını, token'ları, imzaları ve diğer sırları yazmayın. Ham yanıtlara erişimi sınırlayın: bunlarda destek arayüzünde bulunmaması gereken veriler yer alabilir.

Başlatmadan önce tekrarlayan processing, ilerleme olmaması, zaman aşımı, 429, 5xx hatası, geçersiz JSON, geç webhook, yinelenen webhook, partial, canceled ve bilinmeyen durum senaryolarını test edin. Test modu entegrasyon yapısı için faydalıdır, ancak eksikliği şudur: gerçek kuyrukları ve çalışan API'nin gecikmelerini tekrarlamayabilir.