Sorumluluklar
Platform Sorumlulukları
Portal doğrulama akışları, kullanıcı durumları, gerçek kişi cari seçimi, validasyon ve iptal davranışları.
Portal UI Geliştiricisi — Uçtan Uca Belge Akışı
- Alıcı ve varsa vekil PersonParty endpointleriyle aranır. Kayıt bulunursa response içindeki cari
IdileUpdate, bulunamazsaAddçağrılır. - Kullanıcının seçtiği tek TCKN veya PASAPORTNO belge request'ine yazılır. Alıcı cari Id'si
AccountingCustomerParty.Party.Id, vekil cari Id'siDelegateReceiver.PartyIdalanında taşınır. - Belge,
AddOutgoingExpenseVoucherveyaUpdateOutgoingExpenseVoucherile kaydedilir. Portal yalnız SMS senaryosunda iki doğrulama modelini tamamen boş bırakabilir; İADEKODU seçildiyseVerificationProviderveVerificationInfoaynı requestte eksiksiz gönderilir. - Boş SMS verisiyle kabul edilen unsigned belgede
WaitingForVerificationdöner ve SMS ekranı açılır. Geçerli İADEKODU verisi bekleme state'ine girmeden belgeyi imza kuyruğuna taşır. - SMS için Send ve Complete çağrılır. İADEKODU için ayrı Submit endpointi yoktur. Başarılı yanıttan sonra belge detayı yeniden sorgulanır.
ExpenseVoucherAndXmlCreatedveyaSigneddurumunda doğrulama ekranı kapatılır; hata kodu varsa kullanıcıya düzeltilebilir alan gösterilir.
Otomatik İşlemler
Request kabul edildiğinde platform; cari yönetimi, içerik kontrolü, doğrulama, belge üretimi, imza, saklama, GİB bildirimi ve kullanıcı çıktısını bu sırayla yönetir. Aşağıdaki bölümler bu tablonun sırasını izler.
| # | İşlem | Açıklama |
|---|---|---|
| 1 | Cari Yönetimi | Alıcı/vekil gerçek kişi cari arama, oluşturma veya güncelleme |
| 2 | Validasyon | Alan zorunluluk, format, kombinasyon kontrolleri |
| 3 | Doğrulama | SMS, Portal Send/Complete adımlarıyla; İADEKODU, Add/Update içindeki tam modelle doğrulanır |
| 4 | UBL XML Üretimi | UBL 2.1 CreditNote standardında XML |
| 5 | e-İmzalama | Belge kesinleştirme |
| 6 | Numara/UUID Atama | Entegratör göndermezse otomatik |
| 7 | Belge Kaydı | Kalıcı saklama |
| 8 | GİB Raporu | Dönemsel toplu bildirim |
| 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) |
Gerçek Kişi Cari Seçimi
Alıcı ve yalnız IADE senaryosunda kullanılabilen vekil, aynı gerçek kişi cari kaynağından aranır. Cari bulunursa arama response'undaki Id korunur; yalnız bulunamazsa yeni cari oluşturulur. Birden fazla kimliği varsa belgede kullanılacak TCKN veya PASAPORTNO açıkça seçilir.
Belgeye aktarılan kişi bilgileri oluşturma veya güncelleme anında kaydedilir. Cari kartında daha sonra yapılan değişiklikler mevcut belgeyi değiştirmez. Endpoint sözleşmeleri için API Endpoint Referansı kullanılmalıdır.
Validasyon Kuralları
Validasyon katmanı, belge üretimine geçmeden önce senaryo, doğrulama, kimlik ve kargo bilgilerinin tutarlı bir bütün oluşturmasını bekler.
| Kontrol | Kod | Açıklama |
|---|---|---|
| VerificationMethod ve sağlayıcı bilgisi | EGP0037 / EGP0078 | SMS veya IADEKODU; sağlayıcı adı ve 10 haneli VKN |
| VerificationInfo biçimi | EGP0039 / EGP0072 | Geçerli kod ve telefon |
| IADE → ReturnedDocumentReference | EGP0038 / EGP0047 / EGP0048 / EGP0051 | İade edilen belgenin türü ve tarihi; belge varsa numarası |
| BELGESIZ → gerçek kişi kimliği | EGP0050 / EGP0085 | T.C. vatandaşı için TCKN, yabancı uyruklu kişi için PASAPORTNO |
| Kargo → iade kodu ve kargo eşleşmesi | EGP0049 / EGP0087 | IADEKODU ve aktif kargo şirketi kaydı |
| SATIS → VerificationMethod=SMS | EGP0046 | Satışta yalnız SMS doğrulaması kullanılabilir |
| SATIS → DelegateReceiver yok | EGP0053 | Vekalet kullanılamaz |
| DelegateReceiver → kimlik tipi, kimlik değeri ve ad | EGP0054 / EGP0084 | Doluysa üç iş alanı zorunlu ve geçerli olmalıdır |
| Alıcı tam olarak bir TCKN/PASAPORTNO taşır | EGP0080 / EGP0081 / EGP0085 | VKN ve tüzel kişi reddedilir |
| ExternalId mevcut ve tekil | EGP0020 / EGP0028 | Boş veya aynı firmada daha önce kullanılmış değer reddedilir |
Hata Yanıtı
Hata yanıtı, entegrasyon tarafının problemi kod üzerinden ayırt edebilmesi için aynı response iskeletini korur.
{
"IsSuccess": false,
"Message": "Açıklama",
"MessageCode": "EGP0055",
"Data": null
}
Portal Doğrulama Akışı
Portal, SMS senaryosunda gönderim ve kod doğrulama adımlarını hazır sunar. İADEKODU seçildiğinde kod, telefon ve sağlayıcı alanları belge Add/Update isteğinin parçasıdır.
| Senaryo | Portal davranışı | Sonuç |
|---|---|---|
SATIS | SMS gönderme ve kod giriş ekranı gösterilir. | Kod doğrulandığında belge imza akışına alınır. |
Yüz yüze IADE | SMS veya iade kodu yöntemi seçilir. SMS seçilirse belge boş doğrulama verisiyle kaydedilir; İADEKODU seçilirse tam model aynı Add/Update isteğine eklenir. | SMS Complete veya başarılı direct Add/Update sonrasında belge imza akışına alınır. |
Kargolu IADE | İade kodu, telefon ve sağlayıcı bilgileri belge kaydedilmeden önce istenir. | Kargo ve tam İADEKODU verisi aynı Add/Update isteğinde doğrulanır; SMS bekleme akışına girilmez. |
Vekaletli IADE | Asıl alıcı korunur; vekil aynı gerçek kişi cari kaynağından seçilir. | Doğrulama bilgisi vekille ilişkilendirilir. |
Portal Durumları
| Teknik değer | Portal açıklaması | Kullanıcı aksiyonu |
|---|---|---|
WaitingForVerification | SMS gönderimi bekleniyor. | Telefon kontrol edilerek SMS gönderilir. |
WaitingForSmsCode | SMS onayı bekleniyor. | Telefona gelen kod girilir; gerekirse telefon düzeltilerek yeniden gönderim yapılır. |
ExpenseVoucherAndXmlCreated | e-Gider Pusulası oluşturuldu. | Belge durumu takip edilir. |
Signed | GİB'e gönderime hazır. | Ek doğrulama işlemi yapılmaz. |
WaitingForVerification durumunda kalır ve önceki kod geçersizleştirilir. Tam SMS veya İADEKODU modeliyle başarılı Update belgeyi ExpenseVoucherAndXmlCreated durumuna ilerletir.SMS Doğrulama Akışı
OutgoingExpenseVoucherStatusForUser, SMS akışının bekleme ve imza durumlarını gösterir. Tam SMS verisi Add/Update isteğinde gönderilirse belge doğrudan ExpenseVoucherAndXmlCreated durumuna ilerler. Boş SMS verisiyle başlayan unsigned Portal akışında belge önce WaitingForVerification, kod gönderildikten sonra WaitingForSmsCode durumunda izlenir; kod başarıyla tamamlandığında aynı imza kuyruğunda birleşir.
IADE ve kargolu vekâletli IADE SMS ile doğrulanamaz; bu senaryolar SMS akışına girmez ve İADEKODU kullanır.İADEKODU Doğrulama Akışı
İADEKODU yalnız IADE belgelerinde kullanılır. VerificationProvider ve VerificationInfo aynı Add/Update isteğinde eksiksiz gönderilir; ayrı bir bekleme durumu, SMS Send/Complete çağrısı veya Submit endpointi bulunmaz.
SATIS için geçersizdir.Doğrulama Yöntemi Senaryo Matrisi
| Senaryo | SMS | İADEKODU |
|---|---|---|
SATIS | Kullanılabilir | Geçersiz |
Yüz yüze IADE | Kullanılabilir | Kullanılabilir |
Kargolu IADE | Kullanılamaz | Zorunlu |
Kargosuz vekâletli IADE | Kullanılabilir | Kullanılabilir |
Kargolu vekâletli IADE | Kullanılamaz | Zorunlu |
SMS ve İADEKODU validasyonları birbirinden ayrıdır. SMS'in boş başlayabilmesi yalnız imzasız Portal akışına aittir. İADEKODU seçildiğinde doğrulama bilgilerinin tamamı gönderilmelidir; imzalı UBL ise sonradan SMS tamamlanamayacağı için boş doğrulama verisiyle kabul edilmez.
GİB Kullanıcı Hesabı
Portal kullanıcıları hesap zarfı veya UserOptionCode girmez. Platform, e-Gider Pusulası hesabının hem açma hem kapama zarfında erreceipt etiketiyle UserOptionCode=172 üretir ve AuthorizedWorkScope eklemez. İşlem yönü açılışta ProcessUserAccount, kapanışta CancelUserAccount zarfıyla belirlenir; teknik sonuç kullanıcı durumuna yansıtılır.
Excel ve İptal Davranışı
Excel ile oluşturulan belgelerde doğrulama her belge için ayrı tamamlanır; tek kodla toplu doğrulama yapılmaz. SMS doğrulamasını bekleyen belgeler henüz imzalanmadığı için iptal edilemez. İptal işlemi yalnızca ana belge durumu Signed olduktan sonra kullanılabilir.
İptal Ön Koşulları
İptal edilebilirlik ana belge durumu ve diğer e-Arşiv belgeleriyle ortak iptal request sözleşmesi üzerinden değerlendirilir.
WaitingForVerification,WaitingForSmsCodeveExpenseVoucherAndXmlCreateddurumları imzalanmamıştır; iptal edilemez.Signedbelge için request içindeEArchiveStatus=2(Cancelled) gönderilir.- İmzalanmış ve raporlanmamış belge doğrudan; raporlanmış belge ise iptal raporuyla iptal edilir.