Entegrasyon brifini rapor siparişi örneğiyle hazırlamak
Proje portalı ile belge hizmeti arasındaki bağlantı için kapsamı, örnek verileri, yanıtları ve kabul durumlarını somutlaştırın.
Teklifleri karşılaştırmadan önce entegrasyon ihtiyacını baştan sona bir akışla anlatın. “Portala API bağlantısı gerekiyor” ifadesi hangi verilerin aktarılacağını, işin ne zaman tamamlanacağını ve hatayla kimin ilgileneceğini açık bırakır. Somut bilgilerle hazırlanmış bir brif bu kararları birlikte değerlendirmeyi sağlar.
İlk teslim için tek akış belirlemek
Aşağıdaki kurgusal projede portal, bir belge hizmetinden aylık PDF raporu ister. Bütün adlar, alanlar ve yanıtlar bize ait örneklerdir; bir sağlayıcının API’si değildir.
Brif alanı | Örnek karar |
|---|---|
Amaç | Yetkili proje çalışanı, istediği aylık raporu portaldan indirebilir. |
Kaynak | Proje portalı projeyi, onaylanmış rapor ayını ve kullanımı onaylanmış şablon kimliğini gönderir. Bu seçimlerden portal ekibi sorumludur. |
Hedef sistem | Belge hizmeti PDF dosyasını oluşturur. Platform ekibi işleme ve hata durumlarından sorumludur. |
Tetikleyici | Portalda açık bir rapor talebi; her sayfa açılışında yeni iş oluşturulmaz. |
Teslim kapsamı | İş oluşturma, durum sorgulama ve hazır dosyayı alma. |
Kapsam dışı | E-posta gönderimi ve bütün geçmiş raporların taşınması. |
Bu ayrım ek istekleri de görünür kılar: Sonradan istenen e-posta özelliği, kendi hata yönetimi olan ayrı bir adımdır. “Bağlantı” kelimesinin içinde kaybolmaz.
Girdileri değerleri ve anlamlarıyla yazmak
POST /report-jobs için şu örnek içerik kararlaştırılır:
{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}İstek kimliği bu oluşturma talebini tanımlar. Proje ve şablon sabit kayıt kimlikleriyle belirtilir; dönem burada yıl–ay biçimindeki bir takvim ayıdır. Görünen adlar veya serbest metinle yazılan bir dönem bu değerlerin yerine geçmez. Portal, hangi şablonların kullanımının onaylandığını belge hizmetiyle netleştirmelidir.
İşe, duruma ve dosyaya erişim, kullanıcının yetkili olduğu projeyle sınırlandırılır. Bağlantıyı bilmek tek başına indirme izni vermez. Brife roller ve erişim yöntemi yazılır; gerçek token ve parolalar belgeye konmaz.
Kabul ile sonucu ayrı tanımlamak
Örnek hizmet, işi kalıcı olarak kaydettikten sonra HTTP 202 ve Location: /report-jobs/J-52 ile yanıt verir:
{"jobId":"J-52","status":"queued"}MDN, 202’yi henüz tamamlanmamış bir işlemin kabulü olarak açıklar. Bu nedenle kendi sözleşmemizde queued (sırada), running (işleniyor), succeeded (başarılı) ve failed (başarısız) durumları vardır. İş ancak dosya oluşturulup tamamlanma anında yetkili kullanıcı tarafından alınabildiğinde başarılıdır. Microsoft, asenkron işler için ayrı durum sorgulaması tarif eder; buradaki durum adları bizim seçimimizdir.
Aynı yetki kapsamında, aynı istek kimliği ve aynı içerik mevcut işe yönlenir. Farklı içerik için örnekte HTTP 409 kararlaştırılır. Bu tekrar kuralı uygulanmalı ve sınanmalıdır; alanın adı tek başına idempotans sağlamaz.
Uygulamadan önce dört kabul durumunu doldurmak
Durum | Beklenen sonuç |
|---|---|
Geçerli talep | İş kabul edilir, ilerleyiş görünür ve sonunda kararlaştırılan proje ile aya ait rapor alınabilir. |
Şablon kimliği eksik | Kabulden önce HTTP |
Kabul edilen talebin yanıtı kaybolur | Aynı içerik ve istek kimliğiyle tekrar, mevcut işi bulur; ikinci rapor üretimi başlamaz. |
Şablon kabulden sonra kaldırılır | İşleme |
Son durumda platform ekibi şablonu kontrol eder. Düzeltilmiş yeni talep yeni bir istek kimliği alır; başarısız iş izlenebilir kalır. Yalnız durum sorgusu aksıyorsa portal güncel durumun bilinmediğini gösterir, başarı veya başarısızlık iddia etmez.
Söz vermeden önce açık işletim sorularını çözmek
Beklenen iş adedini, tipik dosya boyutunu, kabul edilebilir bekleme süresini, sorgulama aralığını ve dosya/durum verilerinin saklama süresini gerçek kullanıma göre ekleyin. Örnekte bu değerler henüz belirlenmedi; güvenilir bir taahhütten önce netleştirilmeleri gerekir. Tahmini süre, ölçülmüş bir özellik gibi alınmaz.
OpenAPI tanımı işlemleri, girdileri ve beklenen yanıtları kesinleştirebilir. İşin sonuç tanımı ve ekip sorumlulukları da ayrıca belirlenmelidir. Portal ve platform ekipleri, somut durumlar üzerinden aynı teslimi değerlendirebilir.
Kaynaklar
Devamını okuyun
Tüm yazılar
ASES ile API ve entegrasyon
ERP, CRM ve mağaza sorunsuz bağlantılı