Entegrasyonlar
MevzuatRadar, webhook teslimatı ve API ile veri okuma sağlar. Kurumun alıcısı olayı kabul eder; kurumun işleyicisi gerekli veriyi API’den okur ve hedef sisteme aktarır. Hedef sisteme aktarım müşteri tarafından geliştirilir.
| Bağlantı | Mevcut kapsam |
|---|---|
| Webhook | İmzalı JSON teslimatı, teslimat kayıtları ve sınırlı yeniden deneme |
| API ve SDK | Mevzuat değişiklikleri, vadeler, işlemler ve raporların okunması |
| Kurum bağlantısı | Kapalı beta izin akışı, kod takası ve uygulama sırrı |
| Sandbox ve canlıya geçiş | Test kurumu, livemode ve canlıya geçiş listesi |
| Eşitleme ve geri doldurma | Sırasız olaylar, yoklama aralığı ve tek seferlik geri doldurma |
| Ödeme modelleri | Müşteri öder (A), firma öder (B), koltuk faturası ve tahsilat |
| SAP S/4HANA | ABAP başlangıç taslağı; SAP’ye yazma işlemi içermez |
| Logo Tiger | C# alıcı taslağı; Logo’ya yazma işlemi içermez |
Alıcı Sözleşmesi
Üretim alıcısı HTTPS kullanır ve webhook URL güvenlik kontrolünden geçer. Teslimat sırasında yönlendirme izlenmez; doğrudan alıcı adresi kaydedilir.
| Konu | Davranış |
|---|---|
| Ham gövde | HMAC doğrulaması, JSON ayrıştırılmadan önce gelen gövdenin özgün baytları üzerinde yapılır |
| V2 imza | X-Webhook-Signature-V2: t=<unix>,v1=<hex>; HMAC SHA-256 girdisi "<t>.<ham gövde>" biçimindedir |
| Zaman kontrolü | V2 doğrulayıcısının varsayılan toleransı 300 saniyedir; alıcının da bu kontrolü uygulaması gerekir |
| Eski imza | X-Webhook-Signature, yalnız gövdenin HMAC değerini sha256= önekiyle taşır; V2 ile birlikte gönderilir |
| Olay | X-Webhook-Event, olay türünü; X-Webhook-Event-Version, sözleşme sürümünü taşır |
| Teslimat kimliği | X-Webhook-Delivery-Id, teslimat kaydını tanımlar |
| Tekilleştirme | X-Webhook-Idempotency-Key, tekrar teslimatlarda aynı işin yeniden oluşturulmasını önlemek için kullanılır |
| Başarı | Her 2xx yanıtı başarılı teslimat sayılır; alıcı kalıcı kabulden sonra örneğin 202 veya 204 döner |
| Hata | 4xx, 5xx, yönlendirme yanıtları ve ağ hataları deneme sınırına kadar yeniden denenebilir; 4xx tekrar denemeyi durdurmaz |
| Zaman aşımı | Gönderim isteğinin zaman aşımı 10 saniyedir; uzun ERP işlemi alıcının iş kuyruğunda yürütülür |
Genel Webhook kuyruğunun normal hata akışında toplam deneme sınırı 7’dir. Yeniden deneme gecikmeleri sırasıyla 30 saniye, 2 dakika, 10 dakika, 1 saat, 6 saat ve 12 saattir. Kuyruk gecikmesi nedeniyle bunlar kesin teslim zamanı değildir. Silinmiş veya etkin olmayan alıcıya teslimat sürdürülmez. Teslimat kayıtları Webhook Abonelikleri üzerinden izlenir.
REGULATION_CLASSIFICATION_COMPLETED ayrı sektör teslimat akışını kullanır:
HTTP hatalarında yalnız 408, 429 ve 5xx yeniden denenir; diğer HTTP
hataları terminaldir. Dört denemelik bütçede aralıklar 1, 2 ve 4 saniyedir.
Bu politika genel kuyruk tablosuyla karıştırılmaz; ayrıntılar
Webhook Akışı sayfasındadır.
API ile Veri Okuma
Temel URL https://api.mevzuatradar.com adresidir. Aşağıdaki yollar
kimlik doğrulaması gerektirir; API anahtarı x-api-key başlığında gönderilir.
API anahtarı izin kapsamları şöyledir:
| Yol | İzin kapsamı | Kullanım |
|---|---|---|
GET /api/v1/changes | regulations:read | Mevzuat değişiklikleri |
GET /api/v1/deadlines | actions:read | Vadesi olan açık işlemler |
GET /api/v1/actions | actions:read | Kurumun işlemleri |
GET /api/v1/board-reports | reports:read | Yönetim kurulu raporları |
GET /api/v1/evidence-packs/{id} | evidence-packs:read | Kanıt paketi ayrıntısı |
Bu yollar JSON döndürür; ERP’ye özgü dosya veya kayıt biçimi üretmez.
Kanıt paketi ayrıntısındaki downloadUrl, dosya mevcutsa süreli indirme
bağlantısı sağlar; dosya yoksa veya bağlantı üretilemezse null olabilir.
Aktarım, paketin durumunu ve bu alanı denetler.
Webhook abonelik yönetimi ayrı bir yetki sınırıdır: /api/v1/webhooks
işlemleri yönetici JWT’si ve ilgili ayar sayfası iznini gerektirir.
Veri okuma API anahtarı bu yönetim işlemlerinin yerine geçmez.
Tekrarlara Dayanıklı Aktarım
Aşağıdaki adımlar kurumun alıcısı için uygulama önerisidir:
- Alıcı ham gövdeyi, V2 imzasını ve zaman damgasını doğrular; olay türünü, sürümünü ve gövde biçimini denetler.
- Tekilleştirme anahtarı kalıcı depoda benzersiz tutulur. Anahtar ile işin kuyruğa kaydı atomik yapılır; başarısız bir kayıt işlenmiş sayılmaz.
- Daha önce kalıcı olarak kabul edilen teslimat tekrar geldiğinde başarılı yanıt döner; ERP’de ikinci kayıt oluşturulmaz.
- İşleyici gerekli ayrıntıyı API’den veya Node.js Örnek İstemcisi üzerinden okur ve müşteri tarafından tanımlanan alan eşlemesiyle hedef sisteme yazar.
- Kalıcı kabulden sonra alıcı
2xxdöndürür. Bundan sonraki ERP hataları kurumun iş kuyruğunda yeniden denenir; MevzuatRadar başarılı teslimatı ERP sonucu için tekrar göndermez.
Örnek Dosyalar ve Sınırları
Bu yollar kaynak depo içindeki örneklerdir; doküman sitesinden indirilen hazır bağlayıcı paketleri değildir.
| Dosya | Mevcut içerik |
|---|---|
apps/docs/examples/webhook-receiver.js | Node.js standart kitaplığıyla V2 imzalı alıcı ve --self-test girişi |
apps/docs/examples/webhook-receiver.py | Python standart kitaplığıyla V2 imzalı alıcı ve --self-test girişi |
apps/docs/examples/sap-webhook-handler.abap | HMAC, kalıcı tekilleştirme ve SAP’ye yazma adımları yorum olarak bırakılmış ABAP taslağı |
apps/docs/examples/logo-webhook-handler.cs | Eski imzayı denetleyen, bellekte tekilleştirme yapan ASP.NET Core alıcı taslağı |
apps/docs/examples/webhook-verify.js | Eski gövde imzasını denetleyen Node.js örneği |
apps/docs/examples/webhook-verify-v2.js | Ham gövde ve 300 saniyelik toleransla V2 imzasını denetleyen Node.js yardımcısı |
apps/docs/examples/webhook_verify_v2.py | Ham gövde ve 300 saniyelik toleransla V2 imzasını denetleyen Python yardımcısı |
apps/docs/examples/connection.js, connection.py | PKCE S256 çifti, state, /baglan adresi, dönüş adresi denetimi ve POST /api/v1/integration/token kod takası; --self-test ağ isteği yapmaz |
apps/docs/examples/event-receiver.js, event_receiver.py | Uygulama ucu alıcısı: V2 imzası, 300 saniyelik pencere ve gövdedeki event_id ile bellekte tekilleştirme |
apps/docs/examples/webhook-event-dedup.js, webhook_event_dedup.py | event_id tekilleştirme yardımcısı; işleyici hatasında ve eksik/bozuk event_id’de kayıt yazmaz |
apps/docs/examples/sandbox-flow.js, sandbox_flow.py | Test sırrı, bağlantı, kod takası, test olayı ve livemode: false alıcısı adımları; öz sınama yerel taklit sunucuyla koşar |
Node.js ve Python alıcılarının kendi kendine sınama girişleri test sırrı ve
bellekte tekilleştirme kullanır. Geçerli teslimat, tekrar teslimat ve geçersiz
imza senaryolarını içerir; kalıcı kuyruk veya ERP bağlantısı sağlamaz.
Normal çalıştırmada MEVZUATRADAR_WEBHOOK_SECRET gereklidir. Bu örnekler
üretim alıcısı olarak doğrudan kullanılmaz. Üretim alıcısı V2 doğrulamasını,
güvenli sır yönetimini ve kalıcı kabulü birlikte uygular;
ayrıntılı imza sözleşmesi Webhook Akışı sayfasındadır.
Uygulama ucu alıcısı işi teslim kimliğine veya X-Webhook-Idempotency-Key
başlığına göre değil, gövdedeki event_id değerine göre bir kez yapar: aynı
olay farklı uçlara veya yeniden denemeyle farklı başlıkla gelebilir. Örnek
event_id değerini yeniden hesaplamaz; eksik ya da bozuk event_id taşıyan
teslim 400 alır ve işlenmez. İşleyici hata verirse olay işlenmiş sayılmaz
ve platformun yeniden denemesi beklenir. Tekilleştirme kaydı bellektedir ve
yeniden başlatmada kaybolur; üretimde kalıcı ve atomik kabul kaydı gerekir.
sandbox-flow öz sınaması yerel taklit sunucularla koşar ve çıktısında bunu
yazar; gerçek sandbox koşusunun kanıtı değildir.