Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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 SDKMevzuat 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 doldurmaSırasız olaylar, yoklama aralığı ve tek seferlik geri doldurma
Ödeme modelleriMüşteri öder (A), firma öder (B), koltuk faturası ve tahsilat
SAP S/4HANAABAP başlangıç taslağı; SAP’ye yazma işlemi içermez
Logo TigerC# 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.

KonuDavranış
Ham gövdeHMAC doğrulaması, JSON ayrıştırılmadan önce gelen gövdenin özgün baytları üzerinde yapılır
V2 imzaX-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 imzaX-Webhook-Signature, yalnız gövdenin HMAC değerini sha256= önekiyle taşır; V2 ile birlikte gönderilir
OlayX-Webhook-Event, olay türünü; X-Webhook-Event-Version, sözleşme sürümünü taşır
Teslimat kimliğiX-Webhook-Delivery-Id, teslimat kaydını tanımlar
TekilleştirmeX-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
Hata4xx, 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/changesregulations:readMevzuat değişiklikleri
GET /api/v1/deadlinesactions:readVadesi olan açık işlemler
GET /api/v1/actionsactions:readKurumun işlemleri
GET /api/v1/board-reportsreports:readYönetim kurulu raporları
GET /api/v1/evidence-packs/{id}evidence-packs:readKanı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:

  1. 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.
  2. 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.
  3. 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.
  4. İş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.
  5. Kalıcı kabulden sonra alıcı 2xx dö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.

DosyaMevcut içerik
apps/docs/examples/webhook-receiver.jsNode.js standart kitaplığıyla V2 imzalı alıcı ve --self-test girişi
apps/docs/examples/webhook-receiver.pyPython standart kitaplığıyla V2 imzalı alıcı ve --self-test girişi
apps/docs/examples/sap-webhook-handler.abapHMAC, kalıcı tekilleştirme ve SAP’ye yazma adımları yorum olarak bırakılmış ABAP taslağı
apps/docs/examples/logo-webhook-handler.csEski imzayı denetleyen, bellekte tekilleştirme yapan ASP.NET Core alıcı taslağı
apps/docs/examples/webhook-verify.jsEski gövde imzasını denetleyen Node.js örneği
apps/docs/examples/webhook-verify-v2.jsHam gövde ve 300 saniyelik toleransla V2 imzasını denetleyen Node.js yardımcısı
apps/docs/examples/webhook_verify_v2.pyHam gövde ve 300 saniyelik toleransla V2 imzasını denetleyen Python yardımcısı
apps/docs/examples/connection.js, connection.pyPKCE 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.pyUygulama 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.pyevent_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.pyTest 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.