Geliştirici belgesi

e-Belge API: faturayı kendi yazılımınızdan kesin

Q: MultiPortal API anahtarını nasıl alırım?

Anahtarı yalnızca MultiPortal operasyon ekibi üretir; portalda kendi kendine anahtar oluşturma ekranı yoktur. Bu sayfadaki formu doldurduğunuzda firmanızın API erişimini açar, anahtarı üretir ve size bir kez iletiriz. Sunucuda anahtarın yalnızca SHA-256 özeti saklandığı için anahtar sonradan tekrar gösterilemez; kaybolursa iptal edilip yenisi üretilir.

Q: Bir anahtar kaç firmayı yönetir, birden fazla firmam varsa ne olur?

Her anahtar tek bir firmaya bağlıdır ve o firmanın bir portal kullanıcısı üzerinden çalışır. Birden çok firma için belge kesecekseniz her firma için ayrı anahtar istenir; istekte firma seçmeniz gerekmez, anahtar hangi firmaya aitse belge o firma adına düzenlenir. Anahtarın üç modu vardır: okuma (yalnız sorgulama), taslak (belge oluşturur, GİB'e göndermez) ve tam (gönderim ve iptal dahil).

Q: Aynı faturanın iki kez kesilmesini nasıl önlerim?

Belge oluşturan her istekte harici_id alanı zorunludur: bu, sizin sisteminizdeki benzersiz kayıt numarasıdır. Aynı harici_id ile aynı gövde ikinci kez gelirse yeni belge kesilmez, ilk belge tekrar: true işaretiyle geri döner. Aynı harici_id ile farklı bir gövde gelirse istek 409 HARICI_ID_CAKISMASI ile reddedilir. Bu sayede zaman aşımına düşen bir isteği güvenle tekrar deneyebilirsiniz.

Q: Yanlış tutarlı fatura kesilmesini API tarafında engelleyebilir miyim?

Evet. İsteğe beklenen_toplam alanını eklerseniz, sizin hesapladığınız ödenecek tutarla bizim hesabımız arasındaki fark 0,01'i geçerse belge oluşturulmaz ve istek 422 TOPLAM_UYUSMUYOR ile döner. Kalem bazında iskonto, tevkifat, KDV dahil fiyat veya döviz kuru hatalarının büyük bölümü bu kalkana takılır. Yapay zekâ üreten istekler için bu alanı doldurmanızı özellikle öneriyoruz.

Q: Belge gönderilmeden önce denetlenebilir mi?

Evet, her belge türü için bir kuru denetim ucu var: POST /faturalar/dogrula, /irsaliyeler/dogrula, /esmm/dogrula ve /emm/dogrula. Bu uçlar hiçbir kayıt oluşturmaz; alanları denetler, senaryoyu ve fatura tipini çıkarır, matrahı, vergi tutarını ve ödenecek tutarı hesaplar, uygulanan varsayılanları uyarılar listesinde döner. Ayrıca gonder: false ile çalışıp belgeyi yalnız taslak olarak bırakabilir, portalda gözle kontrol ettikten sonra gönderebilirsiniz.

Q: Gönderdiğim belgenin sonucunu nasıl öğrenirim?

İki yol var. İtme: firmanız için kaydedilen HTTPS adresine imzalı POST gönderiyoruz; imza MultiPortal-Imza başlığında t=zaman,v1=HMAC-SHA256 biçiminde gelir ve gövdeyle birlikte doğrulanır. Çekme: GET /olaylar?sonra= ile sıralı olay listesini okursunuz, olaylar 30 gün saklanır. API'den gönderilen belgeler 10 gün boyunca izlenir ve durum değişimi belge.durum_degisti olayıyla bildirilir; aynı belgeyi döngüde sorgulamanız gerekmez.

Q: Webhook bildirimi ulaşmazsa ne oluyor?

Teslim edilemeyen bildirim kuyruğa alınır ve 8 kez yeniden denenir: 1, 5, 15, 60, 180, 360, 720 ve 1.440 dakika sonra. Her denemede adres yeniden DNS'e sorulur, yalnız https kabul edilir, yönlendirme izlenmez ve zaman aşımı 10 saniyedir. Son 50 teslimin HTTP kodunu ve süresini GET /webhooklar/{id}/teslimler ile görebilir, POST /webhooklar/{id}/dene ile deneme bildirimi gönderebilirsiniz. Teslim hatası belgenizi hiçbir şekilde etkilemez.

Q: Hız sınırı nedir, aşarsam ne olur?

Anahtar başına saniyede 20, dakikada 600 istek. Sınır aşıldığında istek 429 HIZ_SINIRI ile döner ve yanıt gövdesindeki tekrar_dene_sn alanı kaç saniye sonra tekrar denemeniz gerektiğini söyler. Toplu işlerde belgeleri kuyruğa alıp bu sınırın altında akıtmanızı, hata durumunda artan bekleme süresiyle tekrar denemenizi öneriyoruz.

MultiPortal e-Belge REST API v1, 10 Ekim 2026'da yayına alındı. Kendi ERP'nizden, e-ticaret altyapınızdan ya da kendi yazdığınız servisten e-Fatura, e-Arşiv, e-İrsaliye, e-SMM ve e-Müstahsil Makbuzu düzenleyebilir, gelen belgeleri listeleyip yanıtlayabilir, PDF ve UBL XML kopyalarını indirebilirsiniz.

Yol ve alan adları Türkçe: alici.vkn, kalemler[].birim_fiyat, odenecek_tutar. Hata gövdeleri RFC 9457 application/problem+json ve sabit hata kodlarıyla döner. Aynı anahtar hem REST hem MCP için çalışır.

API Anahtarı İsteyin Teknik Belgeyi Açın

61REST uç noktası

38MCP aracı

9webhook olay türü

20/snhız sınırı (600/dk)

Neden API

Belgeyi üreten yer, belgeyi kesen yer olsun

Siparişi, hizmeti ya da sevkiyatı kaydeden sistem sizin sisteminiz. Faturanın oradan çıkması hem veri girişini hem de iki kayıt arasındaki tutarsızlığı ortadan kaldırır. API bunun için var; portal ekranı ise aynı belgeler üzerinde gözle kontrol ve müdahale yeri olarak durmaya devam eder.

Çift veri girişi biterFaturayı kendi yazılımınızda bir kez oluşturursunuz. Portala ikinci kez girilmez, iki sistemdeki tutar ve alıcı bilgisi ayrışmaz.
API ile kesilen belge portalda da görünürAyrı bir kanal değil, aynı belge havuzu. API'den oluşturduğunuz taslak portal listelerinde görünür; isterseniz oradan gözle kontrol edip gönderirsiniz.
Yanlış belge kesme riski kapıda durdurulurZorunlu harici_id mükerrer belgeyi, beklenen_toplam yanlış tutarı, dogrula ucu eksik alanı belge oluşmadan yakalar.
Alıcıyı kesmeden önce sorgulayınGET /mukellef/{vkn} alıcının e-Fatura ve e-İrsaliye kaydını, posta kutusu etiketlerini ve önerilen senaryoyu döner. Senaryoyu bize bırakabilirsiniz: "senaryo": "otomatik".
Yapay zekâ istemcileri için hazırUçların 38'i aynı anahtarla MCP aracı olarak sunulur. Geri alınamaz çağrılar ayrıca işaretlidir, böylece istemci onay almadan gönderim yapmaz.
API yazmak istemiyorsanızProgramınızdan belge almanın başka bir yolu da var: konnektör. Programınızın veritabanını okuyarak ya da klasör izleyerek çalışır, kod yazmanızı gerektirmez. Çözümler sayfasına bakın.

Kimlik doğrulama

Bearer anahtar: tek firma, tek mod

Her istek Authorization başlığında bir anahtar taşır. Anahtar mp_canli_ önekiyle başlar ve tek bir firmaya bağlıdır; istekte firma belirtmezsiniz, belge anahtarın firması adına düzenlenir.

Her istekte gönderilecek başlıklar — x-api-key başlığı da kabul edilir

POST /api/v1/faturalar HTTP/1.1
Host: app.multiportal.tr
Authorization: Bearer mp_canli_7hQ2…
Content-Type: application/json

Anahtarı yalnız biz üretiriz. Portalda kendi kendine anahtar oluşturma ekranı yok. Sunucuda anahtarın yalnızca SHA-256 özeti durur, ham değer bir kez gösterilir ve sonradan tekrar okunamaz. Kaybolan anahtar gösterilmez, iptal edilip yenisi üretilir. API erişimi firma bazında açılır ve kapatılır.

01Mod seçimi

Anahtar üç moddan biriyle açılır. okuma: yalnız sorgulama. taslak: belge oluşturur, GİB'e gönderemez. tam: gönderim ve iptal dahil her işlem.

02IP kısıtı

İstediğiniz IP adreslerini ya da IPv4 CIDR bloklarını anahtara bağlayabilirsiniz. Liste boşsa her adresten çalışır; doluysa dışındaki istek 403 IP_IZINSIZ alır.

03Kapılar

Her istek sırayla şu kapılardan geçer: anahtar geçerli mi, IP izinli mi, firmanın API erişimi açık mı, firma aktif mi, anahtarın kullanıcısı hâlâ firmaya üye mi, kontör/kilit durumu uygun mu.

Örnek istek ve yanıt

Bir e-Fatura isteği baştan sona

Aşağıdaki gövde gerçek şemadır: alanlar, varsayılanlar ve yanıt biçimi canlı API'de bire bir böyledir. gonder: false olduğu için belge yalnız taslak oluşur; gönderim ayrı bir çağrıyla, bilinçli olarak yapılır.

İstek — POST /api/v1/faturalar

{
  "harici_id": "ERP-2026-000123",
  "senaryo": "otomatik",
  "profil": "TICARIFATURA",
  "alici": {
    "vkn": "1234567890",
    "unvan": "Örnek Ticaret A.Ş.",
    "vergi_dairesi": "Çankaya",
    "il": "Ankara",
    "ilce": "Çankaya",
    "adres": "Atatürk Blv. No:1",
    "eposta": "muhasebe@ornek.com.tr"
  },
  "kalemler": [
    {
      "ad": "Danışmanlık hizmeti",
      "miktar": 10,
      "birim": "saat",
      "birim_fiyat": 1500,
      "kdv_orani": 20
    },
    {
      "ad": "Yazılım lisansı",
      "miktar": 1,
      "birim_fiyat": 5000,
      "kdv_orani": 20,
      "iskonto_orani": 10
    }
  ],
  "notlar": ["Sipariş no: 4821"],
  "beklenen_toplam": 23400,
  "gonder": false
}

Yanıt — 201 Created

{
  "ettn": "6f1c2a90-3b77-4d58-9a21-5c0e4f8b2d11",
  "belge_no": null,
  "harici_id": "ERP-2026-000123",
  "senaryo": "efatura",
  "profil": "TICARIFATURA",
  "fatura_tipi": "SATIS",
  "tarih": "2026-10-11",
  "alici": {
    "vkn": "1234567890",
    "unvan": "Örnek Ticaret A.Ş."
  },
  "para_birimi": "TRY",
  "odenecek_tutar": 23400,
  "vergi_tutari": 3900,
  "durum": "TASLAK",
  "durum_metni": null,
  "hata": null,
  "kaynak": "portal",
  "baglantilar": {
    "self": "/api/v1/faturalar/6f1c2a90-…",
    "pdf":  "/api/v1/faturalar/6f1c2a90-…/pdf",
    "xml":  "/api/v1/faturalar/6f1c2a90-…/xml",
    "html": "/api/v1/faturalar/6f1c2a90-…/html"
  },
  "tekrar": false,
  "uyarilar": [
    "senaryo otomatik → e-Fatura (alıcı GİB listesinde)."
  ]
}

Hesap nasıl çıkıyor? 10 × 1.500 = 15.000, 5.000 × 0,90 = 4.500 → matrah 19.500. %20 KDV 3.900. Ödenecek 23.400. Birim fiyatlar KDV hariçtir; KDV dahil fiyatla çalışıyorsanız "fiyatlar_kdv_dahil": true gönderin, çevirmeyi biz yaparız. Numara taslakta verilmez: belge_no gönderim anında atanır.

Taslağı gönderme — ayrı ve bilinçli çağrı

POST /api/v1/faturalar/{ettn}/gonder

→ 200 {
  "ettn": "6f1c2a90-…",
  "belge_no": "MPT2026000000871",
  "durum": "GONDERILDI",
  "durum_metni": "Gönderildi"
}

Hata gövdesi — application/problem+json

→ 422 {
  "type": "…/dokuman#hata-TOPLAM_UYUSMUYOR",
  "title": "Toplam uyuşmuyor",
  "status": 422,
  "detail": "Hesaplanan ödenecek tutar
     23.400,00 ₺; beklenen_toplam 23.000.",
  "kod": "TOPLAM_UYUSMUYOR",
  "ipucu": "Birim fiyatların KDV HARİÇ
     olduğunu, iskonto ve tevkifatı kontrol
     edin; belge oluşturulmadı.",
  "istek_id": "req_8sQb3LtWxA"
}

Kapsam

61 uç, beş belge türü, gelen ve giden

Uç listesinin tamamı ve her alanın açıklaması herkese açık: api/v1 kök adresi uçları JSON olarak sayar, dokuman insan için yazılmış teknik belgedir.

Grup	Uç	Neler var
Hesap	2	`/hesap` anahtar modu, firma, açık belge türleri ve kilit durumu · `/kontor` bakiye, paket geçerliliği, aylık kullanım
Mükellef	1	`/mukellef/{vkn}` e-Fatura ve e-İrsaliye kaydı, posta kutusu etiketleri, önerilen senaryo
Giden fatura	10	Kuru denetim, oluştur, listele, durum, gönder, e-Arşiv iptali, taslak silme, PDF / UBL XML / HTML
Gelen fatura	6	Listele (yanıt bekleyenler süzülebilir), detay, ticari faturaya KABUL / RED, PDF / UBL XML / HTML
Giden e-İrsaliye	9	Kuru denetim, oluştur, listele, durum, gönder, taslak silme, PDF / UBL XML / HTML
Gelen e-İrsaliye	7	Listele, detay, satırları okuma, alındı yanıtı (KABUL / RED / KISMI_KABUL), PDF / UBL XML / HTML
e-SMM	10	Kuru denetim, oluştur, listele, durum, gönder, iptal, taslak silme, PDF / UBL XML / HTML
e-Müstahsil Makbuzu	10	Kuru denetim, oluştur, listele, durum, gönder, iptal, taslak silme, PDF / UBL XML / HTML
Olaylar ve webhook	6	Olay akışı, webhook ekleme / listeleme / silme, deneme bildirimi, son 50 teslim kaydı

Hangi belge türlerinin firmanız için açık olduğu GET /hesap yanıtındaki firma.hizmetler alanında yazar (efatura, earsiv, eirsaliye, esmm, emm). Açık olmayan türe istek gönderirseniz 403 HIZMET_KAPALI döner. Entegrasyona her zaman /hesap çağrısıyla başlayın.

Güvenlik ve doğruluk

Yanlış belgeyi kesmeden durdurmak

e-belgede geri dönüş pahalıdır: gönderilmiş fatura tek taraflı silinmez, gönderilmiş e-İrsaliye hiç iptal edilemez. Bu yüzden API'nin kapıları gönderimden önce kuruldu.

01harici_id — mükerrer korumasıBelge oluşturan her istekte zorunlu. Aynı kimlikle aynı gövde ikinci kez gelirse yeni belge kesilmez, ilki tekrar: true ile döner. Aynı kimlikle farklı gövde gelirse 409. Zaman aşımına düşen isteği güvenle tekrar deneyebilirsiniz. Dört belge türü aynı kuralı kullanır.

02beklenen_toplam — tutar kalkanıSizin hesapladığınız ödenecek tutarı gönderirsiniz. Bizim hesabımızla fark 0,01'i geçerse belge oluşturulmaz ve 422 TOPLAM_UYUSMUYOR döner. İskonto, tevkifat, KDV dahil fiyat ve döviz kuru hatalarının çoğu buraya takılır.

03dogrula — kuru denetimHer belge türünün bir /dogrula ucu var. Hiçbir kayıt oluşmaz: alanlar denetlenir, senaryo ve fatura tipi çıkarılır, matrah ve vergi hesaplanır, uygulanan varsayılanlar uyarilar listesinde geri gelir.

04problem+json — makine okunur hata diliHer hata RFC 9457 gövdesiyle döner: sabit kod, Türkçe detail, hatalı alanların listesi, ne yapılacağını söyleyen ipucu ve destek için istek_id. Kod listesi sabittir; dallanmanızı metne değil koda bağlayın.

Sık karşılaşılan kod	HTTP	Ne demek
`DOGRULAMA_HATASI`	422	Alanlar hatalı. Yanıttaki `alanlar` listesindeki her maddeyi düzeltip tekrar gönderin.
`TOPLAM_UYUSMUYOR`	422	Hesaplanan tutar `beklenen_toplam` ile tutmuyor; belge oluşturulmadı.
`ALICI_EFATURA_DEGIL`	422	Alıcı e-Fatura mükellefi değil. `"senaryo": "earsiv"` ya da `"otomatik"` ile gönderin.
`HARICI_ID_CAKISMASI`	409	Aynı `harici_id` ile farklı içerik gönderildi. Yeni belge için yeni kimlik kullanın.
`DURUM_UYGUN_DEGIL`	409	Belgenin durumu bu işleme uygun değil (ör. gönderilmiş belgeyi silmek).
`HESAP_KILITLI`	402	Kontör bitti ya da firma kilitli. `/hesap` ve `/kontor` açık kalır.
`ANAHTAR_MODU`	403	Anahtar bu işleme izin vermiyor (ör. taslak modunda gönderim denemesi).
`HIZ_SINIRI`	429	Çok fazla istek. Yanıttaki `tekrar_dene_sn` kadar bekleyip tekrar deneyin.

Olaylar ve webhook

Sonucu sormak yerine haber alın

Gönderim eşzamanlı bitmez: zarf GİB'e gider, durum sonra oturur, ticari faturada alıcının yanıtı günler sonra gelebilir. Bu yüzden belgeyi döngüde sorgulamak yerine olay akışını dinlemenizi öneriyoruz. API'den gönderilen belgeler 10 gün boyunca izlenir.

Dokuz olay türü

belge.olusturulduAPI ile taslak oluşturuldu.
belge.gonderildiBelge GİB'e gönderildi; sonuç ayrıca durum değişimiyle gelir.
belge.gonderim_hatasiGönderim başarısız; belge taslak olarak duruyor.
belge.durum_degistiBASARILI, KABUL, RED, HATA, IPTAL… Beklediğiniz olay genellikle budur.
belge.iptal_edildi / belge.silindiİptal ya da taslak silme.
gelen.yeni / gelen.yanitlandiFirmaya yeni belge düştü ya da gelen belgeye yanıt verildi.
webhook.denemeAdresinizi sınamak için elle tetiklediğiniz bildirim.

İmza doğrulama — her teslimde gelen başlıklar

MultiPortal-Olay: belge.durum_degisti
MultiPortal-Olay-Id: 918734
MultiPortal-Imza: t=1793...,v1=9c4f...
User-Agent: MultiPortal-Webhook/1.0

# v1 = HMAC-SHA256(sir, "t" + "." + govde)
# gövdeyi ham hâliyle doğrulayın, yeniden
# serileştirmeyin; t'yi de kontrol edin.

8 denemeUlaşmayan bildirim 1, 5, 15, 60, 180, 360, 720 ve 1.440 dakika sonra tekrar denenir.
Yalnız httpsYönlendirme izlenmez, zaman aşımı 10 saniye, adres her teslimde yeniden DNS'e sorulur; özel ve yerel ağ adreslerine gönderilmez.
Teslim kaydıGET /webhooklar/{id}/teslimler son 50 teslimin HTTP kodunu, süresini ve hatasını verir.
Webhook kuramıyorsanız çekinGET /olaylar?sonra={son_id} sıralı olay listesi döner; olaylar 30 gün saklanır. Teslim hatası belgenizi asla etkilemez.

Makine okunur tanımlar

OpenAPI 3.1, llms.txt ve MCP

Uç tablosu tek kaynaktan üretiliyor: REST yönlendirici, OpenAPI belgesi, MCP araç listesi ve llms.txt aynı tanımdan çıkar. Yani belgedeki bir alan canlı davranıştan ayrışamaz. Üçü de anahtar gerektirmez, şimdi açıp bakabilirsiniz.

MCP sunucusu

POST https://app.multiportal.tr/api/v1/mcp
# Streamable HTTP, durumsuz
# aynı Bearer anahtarı, 38 araç

hesap_bilgisi      salt okuma
mukellef_sorgula   salt okuma
fatura_dogrula     salt okuma
fatura_olustur
fatura_gonder      geri alınamaz
earsiv_iptal       geri alınamaz
gelen_faturaya_yanit geri alınamaz
…

Hız sınırı

Saniyede 20, dakikada 600 istekSınır anahtar başınadır. Aşıldığında istek 429 HIZ_SINIRI döner.
Ne kadar bekleyeceğinizi söylerizHata gövdesindeki tekrar_dene_sn alanı saniye cinsinden bekleme süresini verir; kör tekrar denemeyin.
Toplu iş için öneriBelgeleri kuyruğa alıp sınırın altında akıtın, hatada artan bekleme süresiyle tekrar deneyin. Dönem sonunda binlerce belgeyi aynı dakikaya sıkıştırmayın.
Kontörü de izleyinAPI'den kesilen belge de kontör havuzundan düşer. GET /kontor bakiyeyi verir; bakiye biterse belge uçları 402 döner. Kontör paketleri

Kendi yazılımınızdan belge kesin

Türkçe alan adları, mükerrer gönderim kalkanı, tutar doğrulaması ve kuru deneme ucu.

Sıkça Sorulan Sorular

Geliştiricilerin ilk sorduğu sorular

Burada cevabını bulamadığınız teknik soruyu formda yazabilirsiniz; entegrasyonu yürütecek ekip yanıtlar.

Anahtar ve Bilgi Talebi

MultiPortal API anahtarını nasıl alırım?

Anahtarı yalnızca MultiPortal operasyon ekibi üretir; portalda kendi kendine anahtar oluşturma ekranı yoktur. Bu sayfadaki formu doldurduğunuzda firmanızın API erişimini açar, anahtarı üretir ve size bir kez iletiriz. Sunucuda anahtarın yalnızca SHA-256 özeti saklandığı için anahtar sonradan tekrar gösterilemez; kaybolursa iptal edilip yenisi üretilir.

Bir anahtar kaç firmayı yönetir, birden fazla firmam varsa ne olur?

Her anahtar tek bir firmaya bağlıdır ve o firmanın bir portal kullanıcısı üzerinden çalışır. Birden çok firma için belge kesecekseniz her firma için ayrı anahtar istenir; istekte firma seçmeniz gerekmez, anahtar hangi firmaya aitse belge o firma adına düzenlenir. Anahtarın üç modu vardır: okuma (yalnız sorgulama), taslak (belge oluşturur, GİB'e göndermez) ve tam (gönderim ve iptal dahil).

Aynı faturanın iki kez kesilmesini nasıl önlerim?

Belge oluşturan her istekte harici_id alanı zorunludur: bu, sizin sisteminizdeki benzersiz kayıt numarasıdır (sipariş no, ERP kayıt no…). Aynı harici_id ile aynı gövde ikinci kez gelirse yeni belge kesilmez, ilk belge tekrar: true işaretiyle geri döner. Aynı harici_id ile farklı bir gövde gelirse istek 409 HARICI_ID_CAKISMASI ile reddedilir. Bu sayede zaman aşımına düşen bir isteği güvenle tekrar deneyebilirsiniz.

Yanlış tutarlı fatura kesilmesini API tarafında engelleyebilir miyim?

Evet. İsteğe beklenen_toplam alanını eklerseniz, sizin hesapladığınız ödenecek tutarla bizim hesabımız arasındaki fark 0,01'i geçerse belge oluşturulmaz ve istek 422 TOPLAM_UYUSMUYOR ile döner. Kalem bazında iskonto, tevkifat, KDV dahil fiyat veya döviz kuru hatalarının büyük bölümü bu kalkana takılır. Yapay zekâ üreten istekler için bu alanı doldurmanızı özellikle öneriyoruz.

Belge gönderilmeden önce denetlenebilir mi?

Evet, her belge türü için bir kuru denetim ucu var: POST /faturalar/dogrula, /irsaliyeler/dogrula, /esmm/dogrula ve /emm/dogrula. Bu uçlar hiçbir kayıt oluşturmaz; alanları denetler, senaryoyu ve fatura tipini çıkarır, matrahı, vergi tutarını ve ödenecek tutarı hesaplar, uygulanan varsayılanları uyarilar listesinde döner. Ayrıca gonder: false ile çalışıp belgeyi yalnız taslak bırakabilir, portalda gözle kontrol ettikten sonra gönderebilirsiniz.

Gönderdiğim belgenin sonucunu nasıl öğrenirim?

İki yol var. İtme: firmanız için kaydedilen HTTPS adresine imzalı POST gönderiyoruz; imza MultiPortal-Imza başlığında t=zaman,v1=HMAC-SHA256 biçiminde gelir ve gövdeyle birlikte doğrulanır. Çekme: GET /olaylar?sonra={son_id} ile sıralı olay listesini okursunuz, olaylar 30 gün saklanır. API'den gönderilen belgeler 10 gün boyunca izlenir ve durum değişimi belge.durum_degisti olayıyla bildirilir; aynı belgeyi döngüde sorgulamanız gerekmez.

Webhook bildirimi ulaşmazsa ne oluyor?

Teslim edilemeyen bildirim kuyruğa alınır ve 8 kez yeniden denenir: 1, 5, 15, 60, 180, 360, 720 ve 1.440 dakika sonra. Her denemede adres yeniden DNS'e sorulur, yalnız https kabul edilir, yönlendirme izlenmez ve zaman aşımı 10 saniyedir. Son 50 teslimin HTTP kodunu ve süresini GET /webhooklar/{id}/teslimler ile görebilir, POST /webhooklar/{id}/dene ile deneme bildirimi gönderebilirsiniz. Teslim hatası belgenizi hiçbir şekilde etkilemez.

Hız sınırı nedir, aşarsam ne olur?

Anahtar başına saniyede 20, dakikada 600 istek. Sınır aşıldığında istek 429 HIZ_SINIRI ile döner ve yanıt gövdesindeki tekrar_dene_sn alanı kaç saniye sonra tekrar denemeniz gerektiğini söyler. Toplu işlerde belgeleri kuyruğa alıp bu sınırın altında akıtmanızı, hata durumunda artan bekleme süresiyle tekrar denemenizi öneriyoruz.

Ayrı bir test sunucunuz var mı?

Ayrı bir test alan adımız yok; geliştirme de canlı adres üzerinden yapılır. Riski ortadan kaldıran iki araç veriyoruz: anahtarınız taslak modunda açılabilir — bu modda belge oluşturulur ama GİB'e gönderilemez; ayrıca dogrula uçları hiçbir kayıt oluşturmadan alan denetimi ve tutar hesabı yapar. Entegrasyonu taslak modunda bitirip hazır olduğunuzda anahtarı tam moda aldırabilirsiniz.

MCP sunucusu ne işe yarar?

MCP (Model Context Protocol), yapay zekâ istemcilerinin bir sistemin yeteneklerini araç olarak görmesini sağlayan açık protokoldür. MultiPortal uçlarının 38'i aynı anahtarla MCP aracı olarak da sunulur; adres POST /api/v1/mcp (Streamable HTTP, durumsuz). Her araç salt okuma ve geri alınamaz işaretleriyle gelir, böylece istemci hangi çağrının geri dönüşü olmadığını bilir. Uçların makine okunur tanımı OpenAPI 3.1 belgesinde, yapay zekâ için özetlenmiş hâli llms.txt dosyasında durur.

API ile kesilen belge de kontör harcar mı?

Evet. Kontör belge trafiğinin ölçüsüdür; belgeyi portaldan mı API'den mi kestiğiniz fark etmez, gelen belgeler de aynı havuzdan düşer. Bakiyenizi GET /kontor ile okuyabilirsiniz. Kontör bittiğinde ya da firma kilitlendiğinde belge uçları 402 HESAP_KILITLI döner; yalnız /hesap ve /kontor uçları açık kalır, böylece bağlı yazılımınız durumu görüp sizi uyarabilir. Paketleri kontör paketleri sayfasından karşılaştırabilirsiniz.

API anahtarı

Anahtar talep formu

Anahtarı yalnız operasyon ekibimiz üretir. Formu doldurun; hacminizi ve bağlanacağınız yazılımı değerlendirip firmanızın API erişimini açar, anahtarı doğru modda üretip size iletiriz. Entegrasyona başlamadan önce teknik sorularınızı da bu form üzerinden sorabilirsiniz.