Uygulama
Platform Sorumlulukları
Platformun otomatik işlemleri, validasyon kuralları, hata yanıtları ve iptal ön koşulları.
Portal UI Geliştiricisi — Uçtan Uca Belge Akışı
- Portal kullanıcısı üreticinin telefon numarasını kontrol eder ve makbuzu kaydeder.
- SMS bilgisi boş olan imzasız Portal belgesi
WaitingForVerificationdurumunda tutulur; bu aşamada imza kuyruğu oluşturulmaz. - Kullanıcı belge ekranındaki SMS gönderme adımını başlatır. Portal,
SendCreditNoteSmsCodeçağrısını yapar; SMS'i VBT Platform gönderir ve belgeWaitingForSmsCodedurumuna geçer. - Kullanıcı üreticinin ilettiği kodu ekrana girer. Portal, gönderimden dönen doğrulama tokenı ve kodla
CompleteCreditNoteSmsVerificationçağrısını yapar. - Platform kodu doğrular, doğrulama bilgilerini belgeye ekler, UBL'i yeniden üretir ve belgeyi
CreditNoteAndXmlCreateddurumuyla imza kuyruğuna alır. - Belge detayı yeniden sorgulanır;
CreditNoteAndXmlCreatedveyaSigneddurumunda SMS ekranı kapatılır, hata oluşursa kullanıcıya yeniden gönderim veya kod düzeltme adımı gösterilir.
Otomatik İşlemler
Platform, entegratörün gönderdiği request'i doğruladıktan sonra e-Müstahsil Makbuzu'na özgü UBL XML üretimi, imza kuyruğu, GİB raporu ve belge görüntüleme adımlarını yönetir. Entegratör belge içeriğini sağlar; platform teknik yaşam döngüsünü işletir.
| # | İşlem | Açıklama |
|---|---|---|
| 1 | Validasyon | Alan zorunluluk, format, kombinasyon kontrolleri |
| 2 | Portal SMS doğrulaması | Kullanıcının başlattığı gönderimde SMS'i iletir; kod, süre ve tekrar kontrollerini yönetir; başarılı doğrulamadan sonra belgeyi imza akışına geçirir. |
| 3 | UBL XML Üretimi | UBL 2.1 CreditNote standardında XML |
| 4 | Numara/UUID Atama | Entegratör göndermezse otomatik |
| 5 | İmzalamaya Hazırlama | CreditNoteAndXmlCreated durumuna kaydedilir |
| 6 | e-İmzalama | Belge imzalama akışına alınır; işlem tamamlandığında durum Signed'e geçer. |
| 7 | Belge kaydı | Kalıcı saklama |
| 8 | GİB Rapor | Planlanan sürümde tam SMS paketi UBL ve rapora yazılır. SMS kullanılmadığında raporda kod, telefon ve operatör bölümü oluşturulmaz. |
| 9 | GİB Gönderim | Rapor iletimi + yanıt işleme |
| 10 | İptal Raporu | Sonraki döngüde bildirim |
| 11 | Yazdırılabilir çıktı | |
| 12 | E-posta | Bildirim (yapılandırıldıysa) |
Validasyon Kuralları
Validasyonlar, e-Müstahsil Makbuzu request'inin teknik olarak üretilebilir ve GİB raporuna taşınabilir olmasını kontrol eder; ana odak çiftçi/alıcı tarafları, ürün kalemleri ve stopaj hesaplarıdır.
| Kontrol | Kod | Açıklama |
|---|---|---|
| CreditNoteExternalId dolu | EMM0020 | Her belgede zorunlu |
| CreditNoteExternalId tekil | EMM0028 | Mükerrer engeli |
| UUId geçerli GUID | COM0017 | Gönderilirse format kontrolü |
| UUId tekil | EMM0035 | Mükerrer engeli |
| CreditNoteNumber formatı | — | 16 karakter, Seri+Sıra regex'i |
| IssueDate gelecek olamaz | — | UBL kardinalite kontrolü |
| IssueDate saat bileşeni dolu | — | Zaman damgası zorunlu |
| En az bir CreditNoteLine | — | Makbuz satırsız oluşturulamaz |
| Vergi/kesinti toplam uyumu | — | TaxTotal, WithholdingTaxTotal ve PayableAmount aynı ekonomik hesabı yansıtmalı |
AccountingSupplierParty, üretici/çiftçi ise AccountingCustomerParty olarak oluşturulur. SMS doğrulaması tamamlandığında üretici TCKN'si, SMS kodu ve telefon ile sağlayıcı bilgisi kayıtlı doğrulama bilgilerinden GİB raporuna otomatik aktarılır; kullanıcı ayrı bir rapor nesnesi hazırlamaz.Portal SMS Doğrulama Akışı
Portal, SMS gönderme ve kod doğrulama adımlarını belge ekranında hazır sunar; kullanıcı teknik endpoint, token veya sağlayıcı bilgisi yönetmez.
| Adım | Portal kullanıcısı | VBT Platform |
|---|---|---|
| Belge kaydı | Makbuz bilgilerini kaydeder. | Belgeyi WaitingForVerification durumunda tutar; imza kuyruğu oluşturmaz. |
| SMS gönderimi | Üreticinin telefonunu kontrol eder ve gönderimi başlatır. | SMS'i gönderir; başarılı gönderimde belgeyi WaitingForSmsCode durumuna geçirir. |
| Kod doğrulama | Üreticinin ilettiği kodu ekrana girer. | Kodu doğrular; başarılı sonuçta doğrulama bilgilerini belgeye ekler ve imza kuyruğunu oluşturur. |
| Hata veya süre aşımı | Ekrandaki yönlendirmeye göre yeniden dener. | Süre, yeniden gönderim ve deneme sınırlarını yönetir; başarısız sonucu doğrulanmış göstermez. |
Portal Durumları
| Teknik değer | Portal açıklaması | Kullanıcı aksiyonu |
|---|---|---|
WaitingForVerification | SMS gönderimi bekleniyor. | Üreticinin telefonu kontrol edilerek gönderim başlatılır. |
WaitingForSmsCode | SMS onayı bekleniyor. | Üreticinin ilettiği kod girilir; gerekirse telefon düzeltilerek yeniden gönderim yapılır. |
CreditNoteAndXmlCreated | Doğrulama tamamlandı; belge imzalama bekliyor. | Belge durumu takip edilir. |
Signed | Belge imzalandı ve GİB raporuna hazır. | Ek SMS işlemi yapılmaz. |
SMS Doğrulama Akışı
OutgoingCreditNoteStatusForUser, doğrudan entegrasyon ile Portalın etkileşimli SMS akışını ayırır. Doğrudan entegrasyon tam SMS verisini Add/Update requestinde gönderir ve bekleme durumlarına girmez. Portalda ise kullanıcı gönderimi başlatır; VBT Platform SMS'i gönderip kodu doğruladıktan sonra iki kanal aynı imza kuyruğunda birleşir.
Hata Yanıtı
Hata yanıtı, tüm Müstahsil endpointlerinde aynı temel şekli izler. MessageCode alanı, validasyon tablosundaki hata koduyla eşleştirilir.
{
"IsSuccess": false,
"Message": "Açıklama",
"MessageCode": "EMM0020",
"Data": null
}
| Alan | Anlamı |
|---|---|
IsSuccess | İşlemin başarılı olup olmadığını gösterir |
Message | Kullanıcıya veya log'a yazılabilecek açıklama |
MessageCode | Validasyon veya iş kuralı hata kodu |
Data | Başarılı işlemlerde response modeli; hatada çoğu durumda boş |
İptal Ön-Koşulları
İptal isteği, yalnızca belge durumu uygun olduğunda ilerler; bu koşullar çağrı öncesi beklenen teknik zemini belirler.
- Belge Signed durumunda olmalı (
CreditNoteAndXmlCreateddurumunda iptal edilemez —EMM0024) - İptal requestinde
EArchiveStatus=2(Cancelled) gönderilmeli - Daha önce iptal edilmiş bir belge tekrar iptal edilemez (
EMM0025)
WaitingForVerification ve WaitingForSmsCode dahil imzalanmamış makbuzlar iptal edilemez. Bkz. SMS Doğrulamalı Gönderim — Portal Kullanıcıları İçin.