Referans
Sıkça Sorulan Sorular
Belge kullanımı, iptal, çıktı, API ve hata yönetimi hakkında sık sorulan sorular.
| Konu | Kaynak bölüm |
|---|---|
| Belge kapsamı | İlgili sayfayı açın |
| Senaryolar | İlgili sayfayı açın |
| API işlemleri | İlgili sayfayı açın |
| Alan eşleştirmeleri | İlgili sayfayı açın |
Kullanım ve Operasyon
e-Adisyon ne zaman düzenlenir?
Restoran, kafe ve benzeri işletmeler müşteriye sunulan adisyonu GİB e-Arşiv standardında elektronik olarak düzenlediğinde kullanılır. Belge tipi her zaman ADISYON'dur.
Bir adisyonda birden fazla kalem olabilir mi?
Evet. Kalem listesi bir listedir; aynı adisyonda birden fazla ürün/hizmet ayrı satırlar olarak gönderilebilir.
Bir adisyonu ne zaman iptal edebilirim?
Yalnızca Signed (imzalanmış) durumdaki adisyonlar iptal edilebilir. İmzalama bekleyen bir adisyon iptal edilmeye çalışılırsa BLL0024 hatası döner; zaten iptal edilmiş bir adisyon tekrar iptal edilemez (BLL0025). İptal işlemi bildirim e-postası göndermez.
NACE/KDV mükellef doğrulaması zorunlu mu?
Hayır. GİB bu kontrolü henüz zorunlu kılmamıştır; şu an için entegratörün bu konuda ek bir işlem yapması gerekmez. Ortamda opsiyonel olarak açılabilen bu kontrol, açık olduğunda satıcı ve tüzel kişi (VKN'li) alıcılar için GİB üzerinden mükellef aktiflik ve KDV oranı kontrolü yapar; gerçek kişi (TCKN'li) alıcılar bu kontrolden muaftır. GİB ileride bu kontrolü zorunlu hale getirirse platform tarafımızca otomatik olarak devreye alınacak ve entegratöre ayrıca duyurulacaktır.
Adisyon oluşturulduktan sonra neden hemen nihai sayılmamalıdır?
Oluşturma cevabı kaydın alındığını gösterir. İmza ve GİB raporlama sonucu belge kimliğiyle ayrıca izlenmelidir.
Belgenin PDF veya görüntü çıktısını nereden alabilirim?
Çıktı ve tekil belge işlemleri API sorgulama bölümünde listelenir.
Teknik Entegrasyon
API'ye nasıl bağlanırım, kimlik doğrulama nasıl çalışır?
POST /api/Account/Token ile oturum token'ı alınır; sonraki tüm istekler bu token'ı VbtAuthorization header'ında taşır. Detay için Entegratör API Endpoint Referansı sayfasına bakın.
Düzenleyen taraf (AccountingSupplierParty) bilgisini göndermem gerekiyor mu?
Hayır. Bu alan VBT tarafından firma profilinden otomatik doldurulur; entegratör yalnızca AccountingCustomerParty (alıcı) bilgisini gönderir.
Bir istek başarısız olursa nasıl anlarım?
Oluşturma/güncelleme yanıtları HasError ve Errors[] alanlarını taşır; HasError = true ise Errors dizisindeki her öğe bir hata kodu ve açıklaması içerir (örn. BLL0020, BLL0028). Hata kodlarının tam listesi için Teknik Referans sayfasına bakın.
Aynı isteği zaman aşımından sonra tekrar gönderebilir miyim?
Doğrudan tekrar göndermeyin. Önce GetOutgoingBillList ile DocumentExternalId üzerinden kayıt sorgulanmalı; bulunamadan yeni dış referansla tekrar göndermek mükerrer belge riski oluşturur.
PDF nasıl alınır?
POST /api/BillApi/GetOutgoingBillPdf çağrısında BillEttns[] gönderilir. Yanıttaki Data.BillPdfFileBytes base64 çözülerek PDF olarak saklanır veya gösterilir.
Hazır UBL XML gönderirsem platform belgeyi değiştirir mi?
AddOutgoingBillByUbl/UpdateOutgoingBillByUbl ile gönderilen BillUblRequestModel, platformun beklediği UBL CreditNote şemasına uygun olmalıdır; JSON model ile oluşturmadaki alan zorunlulukları (ör. dış referans, alıcı kimliği) burada da geçerlidir.
Test ortamı var mı?
Test/Swagger adresi ve GİB kaynak bağlantıları için GİB Referansı sayfasına bakın.
Timeout sonrasında oluşturma isteği yeniden gönderilebilir mi?
Önce DocumentExternalId ve varsa UUID ile mevcut kayıt sorgulanmalıdır. Kayıt yokluğu doğrulanmadan yeni kimlikle tekrar gönderim yapılmamalıdır.
Hangi kimlikleri ERP’de saklamalıyım?
Dış referans, UUID, belge numarası ve son gözlenen durum birlikte saklanmalıdır.
Kalem toplamlarıyla belge toplamları farklıysa ne olur?
Her BillLine miktar ve tutarı; vergi toplamları ve LegalMonetaryTotal ile aritmetik olarak uyumlu gönderilmelidir.
İptal isteğini ne zaman tekrar etmemeliyim?
Belge zaten iptal edilmişse veya ilk istek işleme alınmışsa güncel durum okunmadan ikinci istek gönderilmemelidir.
Canlıya geçmeden önce hangi kontroller yapılmalı?
Tek ve çok kalemli oluşturma, KDV hesapları, önizleme, çıktı alma, timeout mutabakatı, durum sorgusu ve iptal akışı birlikte doğrulanmalıdır.