Giden İrsaliye
Giden İrsaliye Entegratör API
Giden irsaliye oluşturma, güncelleme, gönderme, sorgulama, çıktı ve durum endpointleri.
Çağrı Haritası
Entegratör yüzeyi /api/VbtApi altında çalışır. JSON endpointleri ana akıştır; ByXml varyantları aynı işlemin XML sözleşmesini kullanır ve burada tekrarlanmaz.
| Amaç | Method ve endpoint | Request | Response / ana çıktı |
|---|---|---|---|
| Önizleme | POST /api/VbtApi/OutgoingDespatchAdvicePreview | OutgoingDespatchAdviceRequestModel | Doğrulama ve görsel önizleme sonucu |
| Hazır UBL önizleme | POST /api/VbtApi/OutgoingDespatchAdviceUblPreview | DespatchAdviceUblRequestModel | UBL doğrulama ve önizleme |
| JSON ile oluşturma | POST /api/VbtApi/AddOutgoingDespatchAdvice | OutgoingDespatchAdviceRequestModel | ETTN, belge numarası, hata listesi |
| UBL ile oluşturma | POST /api/VbtApi/AddOutgoingDespatchAdviceByUbl | DespatchAdviceUblRequestModel | ETTN, belge numarası, hata listesi |
| Güncelleme | POST /api/VbtApi/UpdateOutgoingDespatchAdvice | OutgoingDespatchAdviceRequestModel | Güncelleme sonucu |
| Silme | POST /api/VbtApi/DeleteOutgoingDespatchAdvice | OutgoingDespatchAdviceDeleteRequestModel | Silme sonucu |
| GİB'e gönderme | POST /api/VbtApi/SendOutgoingDespatchAdviceToGib | OutgoingDespatchAdviceSendToGibRequestModel | Gönderim kabul sonucu |
| Fiili sevk tarihi | POST /api/VbtApi/UpdateOutgoingActualDespatchDate | OutgoingActualDespatchDateUpdateRequestModel | Güncelleme sonucu |
| Durum özeti | POST /api/VbtApi/GetOutgoingDespatchAdvicesStatus | EttnList[] | ETTN bazlı durumlar |
| Listeleme | POST /api/VbtApi/GetOutgoingDespatchAdviceList | SearchRequestModel<OutgoingDespatchAdviceGetRequestModel> | Sayfalı belge listesi |
| Detay | GET /api/VbtApi/GetOutgoingDespatchAdvice?id={id} | Query: id | Giden irsaliye modeli |
Hazır UBL Sözleşmesi
| Alan | Zorunluluk / biçim | Kontrol |
|---|---|---|
DespatchAdviceExternalId | Boş olmayan, ERP'de tekil dış referans | Timeout sonrası aynı belgeyi bulmak için saklayın. |
ReceiverIdentifier | Alıcının GİB posta kutusu etiketi | UBL içindeki alıcı kimliğiyle aynı mükellefe ait olmalıdır. |
FileBytes | XML veya ZIP dosyasının JSON Base64 değeri | Dosya UBLVersionID=2.1 ve CustomizationID=TR1.2.1 taşımalıdır. |
IsZipped | true: ZIP, false: doğrudan XML | İşaret gerçek byte biçimiyle aynı olmalıdır. |
IsSigned | Yalnız dosya gerçekten imzalıysa true | İmzalı içerikte imza doğrulaması yapılır. |
MailTo, FirmBranchCode | Bildirim ve şube ihtiyacına göre | Şubeli firmada geçerli şube kodu gönderilmelidir. |
Hazır UBL için önce OutgoingDespatchAdviceUblPreview çağrısıyla parse, içerik ve şematron sonucunu kontrol edin; aynı model başarılıysa AddOutgoingDespatchAdviceByUbl ile kaydedin. Tam JSON gövdesi için Hazır UBL Request'i bölümüne bakın.
Kritik İşlem Önkoşulları
| İşlem | Önkoşul | Başarılı sonuç | Sonraki kontrol / gözlenebilir hata |
|---|---|---|---|
AddOutgoingDespatchAdvice / ByUbl | Dış referans tekil; içerik, şema ve şematron geçerli olmalıdır. | ETTN ve belge numarası döner. | ETTN'yi saklayın; durum sorgusuna geçin. |
UpdateOutgoingDespatchAdvice | Belge GİB'e tamamlanmış biçimde iletilmemiş ve terminal alıcı sonucuna ulaşmamış olmalıdır. | Mevcut ETTN, belge numarası ve dış referans korunarak içerik güncellenir. | Uygun olmayan durumda DSP0087; ardından önizleme ve durum kontrolü yapın. |
DeleteOutgoingDespatchAdvice | ETTN, dış referans veya belge numarasından biriyle kayıt seçilir. Silme yalnız GİB teslimi tamamlanmadan önce mümkündür. | Kayıt silme sonucu true olur. | Uygun olmayan durumda DSP0024; aktif gönderim sürerken COM0017 alınabilir. |
SendOutgoingDespatchAdviceToGib | Belge imzalanmış ve gönderime uygun durumda olmalıdır. | Gönderim isteği kabul edilir; kullanıcı durumu Sending olur. | İmzasız belgede DSP0101; sonuç için toplu durum endpointini izleyin. |
UpdateOutgoingActualDespatchDate | ETTN ve geçerli tarih bulunmalı; belge henüz GİB teslimi/terminal yanıt aşamasına geçmemiş olmalıdır. | UBL içindeki fiili sevk tarihi güncellenir. | Uygun olmayan durumda DSP0087; güncel belgeyi yeniden okuyun. |
GetOutgoingDespatchAdvicesStatus | En az bir ETTN gönderilmelidir. | Her ETTN için teknik ve kullanıcı durumu döner. | Terminal olmayan kayıtları kontrollü aralıkla yeniden sorgulayın. |
Belge Çıktıları
| Çıktı | Endpoint | Request alanı |
|---|---|---|
| Görsel | POST GetOutgoingDespatchAdviceView | Ettn, isteğe bağlı IsRead |
POST GetOutgoingDespatchAdvicePdf | DespatchAdviceEttns[] | |
| Özel PDF | POST GetOutgoingDespatchAdviceCustomPdf | DespatchAdviceEttns[] |
| UBL XML | POST GetOutgoingDespatchAdviceXmlList | DespatchAdviceEttns[] |
| İndirme bağlantısı | POST GetOutgoingDespatchAdviceDownloadUrl | Belge seçim modeli |
| Karekod | POST GetQrCode | Belge karekod modeli |
Liste Filtreleri
Query içinde düzenleme ve zarf tarihi aralıkları, zarf kimliği, dış referans, ETTN, belge numarası, taraf adı, VKN/TCKN ve kullanıcı durumu gönderilebilir. Dış sarmalda Skip, Take, OrderByName ve OrderByType bulunur; Take en fazla 100'dür.
Durum İzleme Kuralı
Oluşturma ve gönderim cevapları ara sonuçtur. ETTN'yi saklayın, GetOutgoingDespatchAdvicesStatus ile toplu sorgulayın ve yalnız Approved, PartiallyApproved veya Rejected gibi terminal kullanıcı durumlarında ERP iş akışını kapatın. Hata durumlarında aynı belgeyi yeni kimlikle oluşturmadan önce güncel durumu alın.
Tam Endpoint Envanteri
XML sözleşmesini kullanan işlemler, aynı adın ByXml son ekli varyantıdır. Aşağıdaki envanter giden irsaliye yüzeyindeki tüm çağrıları işlem ailesine göre gösterir.
| İşlem ailesi | JSON / UBL endpointleri | XML varyantları |
|---|---|---|
| Oluşturma | AddOutgoingDespatchAdvice, AddOutgoingDespatchAdviceByUbl, AddOutgoingDespatchAdviceByExcel | AddOutgoingDespatchAdviceByXml |
| Güncelleme | UpdateOutgoingDespatchAdvice, UpdateOutgoingDespatchAdviceByUbl | UpdateOutgoingDespatchAdviceByXml |
| Detay ve silme | GetOutgoingDespatchAdvice, DeleteOutgoingDespatchAdvice | GetOutgoingDespatchAdviceByXml, DeleteOutgoingDespatchAdviceByXml |
| Listeleme | GetOutgoingDespatchAdviceList, GetOutgoingDespatchAdviceNotErpProccessList | GetOutgoingDespatchAdviceListByXml, GetOutgoingDespatchAdviceNotErpProccessListByXml |
| Görsel/PDF | GetOutgoingDespatchAdviceView, GetOutgoingDespatchAdvicePdf, GetOutgoingDespatchAdviceCustomPdf | GetOutgoingDespatchAdviceViewByXml, GetOutgoingDespatchAdvicePdfByXml, GetOutgoingDespatchAdviceCustomPdfByXml |
| UBL XML | GetOutgoingDespatchAdviceXmlList | GetOutgoingDespatchAdviceXmlListByXml |
| Kalemler | GetOutgoingDespatchAdviceLines, GetOutgoingDespatchAdviceLinesList, GetListOutgoingDespatchAdviceLines | GetListOutgoingDespatchAdviceLinesByXml |
| Gönderim | SendOutgoingDespatchAdviceToGib | SendOutgoingDespatchAdviceToGibByXml |
| Fiili sevk | UpdateOutgoingActualDespatchDate | UpdateOutgoingActualDespatchDateByXml |
| Önizleme | OutgoingDespatchAdvicePreview, OutgoingDespatchAdviceUblPreview | OutgoingDespatchAdvicePreviewByXml |
| Durum/ERP | GetOutgoingDespatchAdviceStatusList, GetOutgoingDespatchAdvicesStatus, UpdateOutgoingDespatchAdviceErpProcessStatus | UpdateOutgoingDespatchAdviceErpProcessStatusByXml |
| İndirme/karekod | GetOutgoingDespatchAdviceDownloadUrl, GetQrCode | — |
| Mükellef sorgusu | GetGibDespatchAdviceUser, GetGibDespatchAdviceAllUserListZip | GetGibDespatchAdviceUserByXml, GetGibDespatchAdviceAllUserListZipByXml |
Giden İrsaliyeye Gelen Yanıt
Alıcının gönderdiği irsaliye yanıtını görsel, PDF, UBL ve indirme bağlantısı olarak almak için GetIncomingReceiptAdviceView, GetIncomingReceiptAdvicePdf, GetIncomingReceiptAdviceXmlList ve GetIncomingReceiptAdviceDownloadUrl kullanılır. İlk üç işlemin ByXml varyantları da bulunur.