MutabakatAIGeliştirici Belgeleriv1.0.0
Bağlayıcı Servis Sözleşmesi▾
Anlık Bağlantı

Bağlayıcı Servis Sözleşmesi

Bağlayıcı servisin dört ucu, HMAC imza kuralı, sınırlar ve biçimler.

Son güncelleme: 21 Eylül 2026 · Sözleşme sürümü 1.0.0

"Anlık bağlantı" yöntemi: BT ekibiniz kendi ağınızda (ya da bulutta) bizim çağırdığımız küçük bir HTTPS servis yayınlar. Firma sahibi Profil → Entegrasyon'da yöntemi "Anlık bağlantı" seçer, adresi ve paylaşılan sırrı "ERP bağlayıcısı" kartına girer, "Bağlantıyı test et" ile doğrular. Sonrasında sihirbazlardaki "ERP'den getir" düğmeleri cariyi ERP'de aratır, seçilen dönemin ekstresini ya da bakiyelerini anında çeker.

Yön
Bu yöntemde MutabakatAI sizin servisinizi çağırır. Servis herkese açık bir alan adında HTTPS ile erişilebilir olmalıdır (VPN arkasındaysa ters vekil ya da tünel). MutabakatAI'nın sabit çıkış IP adresi yoktur; kimlik paylaşılan sır ve imzayla doğrulanır. Sözleşme her ERP için aynıdır.

Uçlar

Dört uç; hepsi GET. {taban} panelde girilen bağlayıcı adresidir (ör. https://erp.firmaniz.com.tr/mutabakatai).

GET{taban}/ping— Bağlantı testi
Sorgu
—
Yanıt
{ "ok": true, "erp": "SAP S/4HANA", "company": "1000 OneWorks Digital", "version": "1.0" }

Panelde "Bağlantıyı test et" bunu çağırır; erp/company/version isteğe bağlıdır ve kartta gösterilir.

GET{taban}/counterparties— Cari arama (canlı)
Sorgu
q (ad / ERP kodu / vergi no parçası, boş olabilir) · limit (≤500)
Yanıt
{ "data": [ { "external_id": "0001000045", "name": "Örnek Ticaret A.Ş.", "tax_number": "1234567890", "email": "muhasebe@ornek-ticaret.com.tr", "contact_name": "…" } ] }

external_id ERP'deki cari kodudur (SAP: LIFNR/KUNNR, Logo: cari kodu); seçilen cari rehbere bu kodla yazılır.

GET{taban}/statements— Cari ekstresi (muavin) — sayfalı
Sorgu
counterparty_external_id · period_start · period_end (YYYY-MM-DD, dâhil) · currency (personelin seçtiği ISO kodu, ör. TRY) · page_size (her istekte gelir; 20000) · cursor (devam isteklerinde; sizin verdiğiniz next_cursor)
Yanıt
{ "data": { "currency": "TRY", "rows": [ { "reference_no": "FTR2026000123", "date": "2026-01-15", "description": "Satış faturası", "amount": "12500.00" }, { "date": "2026-01-20", "description": "Havale", "debit": "0.00", "credit": "5000.00" } ], "next_cursor": "eyJvZmZzZXQiOjIwMDAwfQ" } }

Satır biçimi: amount işaretli (borç +, alacak −) YA DA debit/credit çifti. Sayfalama (isteğe bağlı ama büyük ekstre için şart): satırları page_size kadar döndürüp next_cursor verin (ERP sorgunuzun kaldığı yeri kodlayan opak bir metin — ör. son belge numarası ya da satır konumu; en çok 512 karakter). Biz aynı metni bir sonraki isteğe cursor olarak geri veririz; son sayfada next_cursor boş/null olsun. Aynı imleci ya da aynı satırları yeniden döndürürseniz çekim durdurulur (mükerrer satır girmez). Sayfalamıyorsanız next_cursor göndermeyin ve tüm satırları tek yanıtta verin (≤20.000). currency sorgusu muhasebe personelinin sihirbazda seçtiği para birimidir: çok para birimli cari için o birimin ekstresini döndürün (tek para birimliyseniz yok sayabilirsiniz). Yanıttaki üst düzey currency seçilenden farklıysa (herhangi bir sayfada) çekim reddedilir; boşsa seçilen sayılır. Sonuç sihirbazın "Şirketiniz ekstresi" kartına dosya olarak oturur; muhasebe personeli karşı tarafın Excel'ini ekleyip karşılaştırmayı başlatır (iş o anda, personelin girdiği ad/taraflar/para birimiyle açılır).

GET{taban}/balances— Dönem bakiyeleri
Sorgu
period_date (YYYY-MM-DD) · currency (personelin seçtiği ISO kodu)
Yanıt
{ "data": { "currency": "TRY", "items": [ { "counterparty": { "external_id": "0001000045", "name": "Örnek Ticaret A.Ş.", "tax_number": "1234567890", "email": "…" }, "amount": "184250.00", "direction": "debit" } ] } }

direction: debit = firma bize borçlu, credit = biz firmaya borçluyuz (kampanya kaydındaki Borç/Alacak). Cari başına tek bakiye: aynı external_id birden fazla kez dönerse yanıtın tamamı reddedilir (şube/alt hesap bakiyeleri ERP tarafında toplanmalı; sunucu toplama yapmaz). Cariler rehbere upsert edilir, kayıtlar taslak kampanyaya yazılır; e-postası eksik firmalar Firmalar adımında tamamlanır. Para birimini muhasebe personeli getirirken seçer ve currency sorgusuyla iletilir; yanıttaki currency seçilenden farklıysa yanıt reddedilir (currency boşsa seçilen sayılır). Aynı dönem yeniden getirilirse taslak ERP'nin güncel fotoğrafına gelir: bakiye/yön yenilenir, artık dönmeyen firma listeden çıkar, e-posta ve iletişim bilgisi korunur. ERP'nin döndürdüğü ama rehbere yazılamayan firma (ör. geçersiz tax_number) listeden ÇIKARILMAZ — eski bakiyesiyle kalır ve personel uyarıda adını/nedenini görür.

İmza

  • Her istek GET; başlıklar: X-MutabakatAI-Timestamp (Unix saniye), X-MutabakatAI-Signature (hex HMAC-SHA256), X-MutabakatAI-Org (firma kimliği), User-Agent: MutabakatAI-Connector/1.0.
  • İmzalanan metin: {timestamp}\n{METHOD}\n{yol+sorgu} — yol, taban adresin yol önekini de içerir (ör. /mutabakatai/statements?counterparty_external_id=…&period_start=…&period_end=…). Anahtar: panelde girilen paylaşılan sır.
  • Bağlayıcı imzayı kendi sırrıyla üretip sabit zamanlı karşılaştırır; |şimdi − timestamp| > 300 sn ise reddeder (tekrar oynatma koruması). Reddederken 401.
  • X-MutabakatAI-Org başlığı imzalanan metne DÂHİL DEĞİLDİR (imza sürümü 1): sır firma başınadır ve TLS altında başlık değiştirilemez; bu yüzden aynı servisi birden fazla firma için yayınlıyorsanız isteği başlıktaki firma kimliğine göre değil, o firmanın sırrıyla doğruladığınız imzaya göre ayırın. İleride imza sürümü 2 org kimliğini ve host'u da imzaya alacak; sürüm başlıkla bildirilecek ve 1 çalışmaya devam edecek.
  • Yalnız https:// alan adı (IP değil); yönlendirme izlenmez; yanıt Content-Type: application/json.

Sınırlar ve biçimler

  • Zaman aşımı: ping 10 sn, counterparties 20 sn, statements sayfa başına 60 sn, balances 60 sn (mutlak). Yanıt gövdesi: ping 64 KB, counterparties 1 MB, statements sayfa başına 16 MB, balances 16 MB.
  • Bağlayıcı yalnız API/ERP entegrasyonu açık paketlerde tanımlanabilir ve kullanılabilir; entegrasyon geçici kapatıldıysa çağrılar durur.
  • İmzalanacak yol+sorgu, isteğin satırındaki ham hâliyle (request-target) alınmalıdır; çerçeveler yolu yeniden kodlayabilir (Türkçe karakterli q ve cursor için önemli).
  • Ekstre (/statements) sayfalıdır: her istekte page_size (20.000) gelir, devam isteklerinde cursor; siz yanıta next_cursor koydukça (opak metin, en çok 512 karakter) sonraki sayfa istenir, son sayfada next_cursor boş/null bırakılır. Sayfalama uygulamayan servis tüm satırları tek yanıtta döner (en çok 20.000 satır / 16 MB) — daha büyük ekstre için sayfalama şart. Sayfa başına en çok 20.000 satır; toplam en çok 250.000 satır, 64 sayfa, 128 MB satır verisi ve 15 dakika (tüm sayfalar). Bakiye listesi en çok 5.000 firma; cari arama en çok 500 sonuç.
  • Ekstre çekimi arka planda çalışır: muhasebe personeli "Ekstreyi getir" dediğinde sihirbaz kartı "hazırlanıyor" gösterir, sayfalar toplandıkça satırlar doğrudan işlenir (Excel üretilmez); bitince kart dosyaya döner, hata olursa nedenle birlikte "Tekrar dene" çıkar. Firma başına aynı anda tek ekstre çekimi.
  • Firma başına dakikada 30 çağrı (arama + çekme + test birlikte).
  • Tutarlar string ya da sayı olabilir; en fazla 14 tam + 2 ondalık hane. Kabul edilen yazımlar: "12500.00" · 12500 · "12.500,50" (Türkçe binlik nokta + ondalık virgül) · "1234,50". Dikkat: noktalı string "1.239" Türkçe binlik olarak 1239 okunur; sayı 1.239 ise 1,24'e yuvarlanır — ondalığı "1239.00" gibi 2 haneyle ve noktayla gönderin. Tarihler YYYY-MM-DD. Bilinmeyen alanlar yok sayılır.

Hata yanıtları

Servis hata durumunda JSON { "error": "…", "message": "…" } döndürebilir. Panelde ve günlükte yalnız error / message alanı, sır desenleri maskelenmiş ve en çok 160 karakter olarak gösterilir; JSON olmayan gövde (HTML sayfası vb.) hiç alıntılanmaz.