Başlarken

Dikkat Edilmesi Gereken Hususlar

Entegrasyon sırasında en sık hataya yol açan konular aşağıda toplanmıştır.

Kimlik doğrulama

Token'ın süresi dolduğunda istekler sessizce başarısız olmaz, 401 döner. Yanıt gövdesinde "code": "10004", "detail": "Full authentication is required" görürsünüz. Bu bir gövde hatası değildir; token'ı yenileyin.
SESSION_ID ve accessToken değerlerini kaynak kodunuza, örnek dosyalarınıza veya paylaştığınız isteklere gömmeyin. Bu değerler mükellef bilgilerinizi ve yetki listenizi taşır. Paylaşılması gereken durumlarda ortam değişkeni kullanın; sızdığından şüphelendiğinizde yeni oturum alarak eskisini geçersiz kılın.

Vergi alt bilgisi boş bırakılamaz. taxTotal.taxSubTotal dizisi boş gönderildiğinde schematron kontrolü belgeyi 10003 — TAX_SUB_TOTAL_CAN_NOT_BE_EMPTY hatasıyla reddeder. Aynı şekilde lines dizisi de en az bir kalem içermelidir.
Tutar alanları sayı tipinde gönderilmelidir. "lineExtensionAmount": "1000" gibi metin olarak gönderilen değerler doğrulamadan geçmeyebilir.
Toplamlar tutarlı olmalıdır. legalMonetaryTotal içindeki lineExtensionAmount, taxExclusiveAmount, taxInclusiveAmount ve payableAmount değerleri satır toplamları ve vergi tutarlarıyla uyuşmalıdır.
Belge numarası biçimi katıdır: 3 karakter seri öneki + 4 haneli yıl + 9 haneli sıra numarası (toplam 16 karakter). Seri önekinin hesabınızda tanımlı olması gerekir. Numarayı sistemin atamasını istiyorsanız seri özelliklerini kullanın.
Her belgenin UUID değeri tekil olmalıdır. Aynı UUID ile ikinci kez gönderim yapılamaz.

İade belgesinde cac:BillingReference zorunludur, satış belgesinde ise hiç bulunmaz. Belgesiz iadede schemeID="BELGESIZ" verilir ve cbc:ID boş bırakılır; cbc:IssueDate yine gönderilir.
Referans verilen e-Arşiv faturası gerçekten var olmalı ve daha önce iade edilmemiş olmalıdır. Aksi halde GİB tarafında hata alırsınız.
İade eden kişi alıcıdan farklıysa alıcı AccountingCustomerParty içinde kalır, iade eden kişi BuyerCustomerParty olarak eklenir. İki bloğu birbirine karıştırmak belgenin yanlış kişi adına düzenlenmesine yol açar.
Doğrulama yöntemi ile sağlayıcı bilgisi tutarlı olmalıdır. SMS kodu kullanılıyorsa ChannelCode/@name = SMS_PROVIDER ve cac:Contact/cbc:Name = SMS; iade kodu kullanılıyorsa sırasıyla IADE_PROVIDER ve IADEKODU olmalıdır.

Satış tipi gider pusulalarında gelir vergisi stopajı uygulanır. Stopaj, taxSubTotal içinde ikinci bir kalem olarak gönderilir: taxScheme.name = GV. STOPAJ, taxScheme.typeCode = 0003. KDV için tip kodu 0015'tir.
Stopaj oranı senaryoya göre değişir. Vergiden muaf esnaftan alım, ikinci el ticareti ve mükellef olmayan kişiden alım için GVK 94 kapsamındaki oranlar farklıdır. Portaldeki örneklerde tek bir varsayılan oran kullanılmıştır; kendi senaryonuza uygun oranı mevzuata göre belirleyin.

Operasyon elemanının adı ...Request ile biter. Gövdede <wsdl:SendDocumentRequest> beklenir. <wsdl:SendDocument> gönderilirse servis Cannot find dispatch method fault'u döner.
Namespace http://schemas.i2i.com/ei/wsdl şeklinde, http:// öneki ile yazılmalıdır. Önek unutulduğunda aynı dispatch hatası alınır.
CONTENT alanı base64 kodlanmış UBL XML içerir. İçeriği zip'leyerek gönderiyorsanız REQUEST_HEADER/COMPRESSED alanını Y yapmayı unutmayın.
CancelDocument metodunda DELETE_FLAG iki farklı davranış üretir. N belgeyi iptal eder ve kaydı iptal statüsüyle bırakır; Y kaydı siler ve yalnızca henüz raporlanmamış belgelerde kullanılabilir.
GetDocument çağrılarında geniş tarih aralığı verirken HEADER_ONLY = Y kullanın. Aksi halde her belgenin tam içeriği base64 olarak döner ve yanıt çok büyür.

Dizi içeren gövdelerde "Form" sekmesi yerine "JSON (manuel)" sekmesini kullanın. Form sekmesi şu an dizileri boş, sayıları metin olarak üretiyor; bu haliyle gönderilen istek schematron kontrolünden geçmez.