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. Normal endpointler doğrudan JSON request modelini alır. ByXml varyantları aynı modelin XML serileştirmesini XmlRequestModel.XmlModel içinde alır; hazır UBL dosyası kullanan ByUbl akışı ise ayrı bir sözleşmedir.
AddOutgoingDespatchAdvice, platform model XML'i için AddOutgoingDespatchAdviceByXml, hazır UBL-TR DespatchAdvice dosyası için AddOutgoingDespatchAdviceByUbl kullanılır. Platform XML modeli cac:/cbc: UBL elemanlarını değil, OutgoingDespatchAdviceRequestModel alan adlarını taşır.| Amaç | Method ve endpoint | Request | Response / ana çıktı |
|---|---|---|---|
| Önizleme | POST /api/VbtApi/OutgoingDespatchAdvicePreview | OutgoingDespatchAdviceRequestModel | Doğrulama ve görsel önizleme sonucu |
| XML model ile önizleme | POST /api/VbtApi/OutgoingDespatchAdvicePreviewByXml | XmlRequestModel; içeride OutgoingDespatchAdviceRequestModel XML'i | XML serileştirilmiş ö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 |
| XML model ile oluşturma | POST /api/VbtApi/AddOutgoingDespatchAdviceByXml | XmlRequestModel; içeride OutgoingDespatchAdviceRequestModel XML'i | XML serileştirilmiş ETTN, belge numarası ve hata listesi |
| UBL ile oluşturma | POST /api/VbtApi/AddOutgoingDespatchAdviceByUbl | DespatchAdviceUblRequestModel | ETTN, belge numarası, hata listesi |
| Güncelleme | POST /api/VbtApi/UpdateOutgoingDespatchAdvice / UpdateOutgoingDespatchAdviceByXml | JSON model veya XmlRequestModel | 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 |
JSON ve XML karşılıklarını yan yana kopyalamak için Giden İrsaliye Request Örnekleri sayfasını kullanın. XML panelindeki içerik doğrudan XmlModel değeridir; SOAP istemcisi bunu Request<XmlRequestModel> içindeki alana, REST istemcisi ise XmlRequestModel gövdesine yerleştirir.
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 | Oluşturmada imza doğrulanır. Güncelleme ve önizleme aynı imza kabul sözleşmesini sağlamaz; işlem bazındaki sınırları uygulayın. |
MailTo, FirmBranchCode | Bildirim ve şube ihtiyacına göre | Şubeli firmada geçerli şube kodu gönderilmelidir. |
Hazır UBL için OutgoingDespatchAdviceUblPreview içeriğin modele dönüştürülüp yeniden üretildiği bir önizlemedir; başarılı sonuç, özgün dosyanın imzasının doğrulandığını göstermez. Oluşturma, güncelleme ve önizleme için JSON / platform XML / UBL örnekleri ve imza davranışı tablosu birlikte kullanılmalıdır.
DespatchSupplierParty altında SEVKIYATNO kimliğiyle taşınır. Hedef ortamda İDİS UBL giriş desteği teyit edilmediyse JSON veya ByXml kullanın. Veri kaynağı ve gönderim koşulları.Kritik İşlem Önkoşulları
| İşlem | Önkoşul | Başarılı sonuç | Sonraki kontrol / gözlenebilir hata |
|---|---|---|---|
AddOutgoingDespatchAdvice / ByXml / 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.