Bu doküman, KKTC E-Fatura sistemi ve API'si hakkında sıkça sorulan sorulara yanıtlar içermektedir.
Sistem, son kullanıcıların doğrudan kullanımına uygun bir web arayüzüne sahiptir. Bununla birlikte, operasyonel verimlilik ve sistemler arası tam entegrasyon sağlamak adına süreçlerin sağlanan REST API üzerinden yürütülmesi ve mevcut yazılımlarınıza entegre edilmesi tavsiye edilmektedir. Geliştiriciler, kendilerine tahsis edilen kullanıcı adı ve şifre bilgilerini kullanarak hem arayüz üzerinden hem de API aracılığıyla erişim sağlayabilirler.
Entegrasyona başlamak için öncelikle hızlı başlangıç kılavuzunu incelemeniz önerilir. Bu kılavuz, API URL'leri ve kimlik doğrulama adımları gibi temel bilgileri içerir.
API, Bearer Token tabanlı kimlik doğrulama kullanır. Keycloak üzerinden bir access_token almanız ve bu token'ı tüm API isteklerinizde Authorization başlığı altında Bearer <ACCESS_TOKEN> formatında göndermeniz gerekmektedir.
Token almak için belirtilen Keycloak Token URL'ine POST isteği göndermeniz gerekir.
Token URL (Ana): https://keycloak.maliye.gov.ct.tr/realms/production/protocol/openid-connect/token
Token URL (Test): https://keycloak.maliye.gov.ct.tr/realms/test/protocol/openid-connect/token
İstek gövdesinde aşağıdaki bilgileri sağlamalısınız:
grant_type:password client_id:efatura-frontend username:<vkn> password:<password>
Fatura oluşturmak ve göndermek için POST /api/mukellefler/{VKN}/faturalar endpoint'ini kullanmanız gerekmektedir. {VKN} değeri, fatura kesilecek mükellefin vergi kimlik numarasıdır. İstek gövdesi, FaturaOlusturRequest şemasına uygun bir JSON objesi olmalıdır.
Detaylı API spesifikasyonlarına ve şemalarına https://test-efatura.maliye.gov.ct.tr/api/public/swagger-ui adresinden ulaşabilirsiniz.
Fatura numarası formatı VKN-YIL-SUBE-00000000001 şeklinde olmalıdır:
Notlar:
Evet. Faturalar, hukuki olarak değiştirilemez belgelerdir. Bu nedenle:
Fatura sorgulama ve doğrulama işlemleri genellikle web arayüzü üzerinden yapabilirsiniz. https://test-efatura.maliye.gov.ct.tr/dogrula/<dogrulamakodu>
Sistemdeki tüm tarih ve zaman bilgileri ISO 8601 formatında ve zaman dilimi (timezone) bilgisini içerecek şekilde olmalıdır.
YYYY-MM-DDTHH:mm:ss±HH:mm (Örn: 2025-01-20T14:30:00+03:00)Evet, gelen faturaların detaylarını almak için GET /api/mukellefler/{vkn}/gelen-faturalar endpoint'ini kullanabilirsiniz. Detaylı bilgiye Swagger dokümantasyonundan ulaşabilirsiniz.
Evet, /api/mukellefler/{vkn}/faturalar/{dogrulamaKodu}/ubl adresinden ilgili faturanın UBL/XML içeriğini alabilirsiniz.
Toplu işlemlerde veya doğrulama hatalarında dönen örnek hata yapısı şöyledir:
{
"ozet": {
"toplamKayit": 1,
"basariliKayit": 0,
"basarisizKayit": 1
},
"sonuclar": [
{
"faturaNo": "...",
"dogrulamaKodu": "...",
"basarili": false,
"hataMesaji": "Fatura tarihi 14 günden daha eski olamaz."
}
]
}Pul bakiyesi yetersiz olduğunda 422 Unprocessable Entity durum kodu ile aşağıdaki hata mesajı dönmektedir:
{
"zaman": "2026-06-04T09:01:43.434Z",
"mesaj": "Yetersiz pul bakiyesi. Gerekli: 5, Mevcut: 0.00",
"kaynak": "/mukellefler/.../faturalar"
}