KKTC E-Fatura Sıkça Sorulan Sorular (SSS)

Bu doküman, KKTC E-Fatura sistemi ve API'si hakkında sıkça sorulan sorulara yanıtlar içermektedir.

Sıkça Sorulan Sorular

1. KKTC E-Fatura sistemi nedir?

KKTC E-Fatura sistemi, Kuzey Kıbrıs Türk Cumhuriyeti'nde elektronik fatura düzenleme, gönderme ve alma süreçlerini dijitalleştiren bir uygulamadır. Hem web arayüzü hem de REST API aracılığıyla kullanılabilir.

2. E-Fatura sistemine nasıl kayıt olabilirim?

Sisteme kayıt süreçleri hakkında en güncel ve detaylı bilgi için lütfen KKTC Maliye Bakanlığı'nın resmi duyurularını veya ilgili kullanıcı kılavuzunu inceleyiniz.

3. KKTC E-Fatura sistemi için hazır bir kullanıcı arayüzü sunuluyor mu, yoksa tüm süreçler REST API üzerinden mi yürütülmelidir?

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.

[TEST] https://test-efatura.maliye.gov.ct.tr/[ANA] https://efatura.maliye.gov.ct.tr/

4. E-Fatura REST API'si ile entegrasyona nasıl başlarım?

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.

5. API için kimlik doğrulama yöntemi nedir?

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.

6. API token'ını nasıl alabilirim?

Token almak için belirtilen Keycloak Token URL'ine (https://keycloak.maliye.gov.ct.tr/realms/vergi/protocol/openid-connect/token veya test ortamı için https://keycloak.maliye.gov.ct.tr/realms/vergi-test/protocol/openid-connect/token) POST isteği göndermeniz gerekir. İstek gövdesinde aşağıdaki bilgileri sağlamalısınız:

grant_type:password
client_id:efatura-frontend
username:<vkn>
password:<password>

7. E-fatura oluşturmak ve göndermek için hangi endpoint'i kullanmalıyım?

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.

8. API'nin detaylı teknik dokümantasyonunu ve şemasını nerede bulabilirim?

Detaylı API spesifikasyonlarına ve şemalarına openapi.json dosyasından veya test ortamı için https://test-efatura.maliye.gov.ct.tr/api/public/swagger-ui adresinden ulaşabilirsiniz.

9. Fatura doğrulama kodu için UUID formatı ne olmalıdır?

E-fatura sisteminde yapılan güncellemeler kapsamında, fatura doğrulama koduna göndereceğiniz UUID’nin UUIDv7 formatında olması gerekmektedir.

10. Fatura numarası formatı nasıl olmalıdır?

Fatura numarası formatı VKN-YIL-SUBE-00000000001 şeklinde olmalıdır:

VKN: Şirketin Vergi Kimlik Numarası.
YIL: 4 haneli yıl.
SUBE: Şirketin kendi belirlediği bir ayraç (Örn: OTEL, KASA, SUBE1).
00000000001: 11 haneli artan fatura numarası.

Notlar:

Her şubenin kendi artan sıra numarası olabilir.
Artan sayı sırası her yılın başında sıfırlanır.

11. Faturalarda tedarikçi bilgilerini her seferinde göndermek zorunlu mu? (Değişmezlik Prensibi)

Evet. Faturalar, hukuki olarak değiştirilemez belgelerdir. Bu nedenle:

Bir fatura oluşturulurken tedarikçi bilgileri (unvan, adres, VKN vb.) sisteme tam olarak, ID referansı olmaksızın gönderilmelidir.
Bu prensip, tedarikçi bilgilerinde gelecekte bir güncelleme olması durumunda dahi, geçmiş faturaların hukuki geçerliliğini ve doğruluğunu korumasını sağlar.

12. Bir faturayı nasıl sorgulayabilir veya doğrulayabilirim?

Fatura sorgulama ve doğrulama işlemleri genellikle web arayüzü üzerinden yapabilirsiniz. https://test-efatura.maliye.gov.ct.tr/dogrula/<dogrulamakodu>

13. Fatura tarih formatı ne olmalıdır?

Sistemdeki tüm tarih ve zaman bilgileri ISO 8601 formatında ve zaman dilimi (timezone) bilgisini içerecek şekilde olmalıdır.

Tarih ve Zaman: YYYY-MM-DDTHH:mm:ss±HH:mm (Örn: 2025-01-20T14:30:00+03:00)

14. Her fatura için bir ücret alınmakta mıdır?

Evet, her fatura oluşturma işlemi için sistem tarafından belirlenen bir pul ücreti alınır. Bu ücret, faturayı düzenleyen mükellefin pul bakiyesinden otomatik olarak düşülür. Fatura oluşturabilmek için sistemde yeterli pul bakiyenizin bulunması gerekmektedir.