E-DEFTER API
Bu sayfada E-Defter oluşturma, imzalama ve GİB'e gönderme işlemleri detaylı olarak ele alınmaktadır.
Last updated
Bu sayfada E-Defter oluşturma, imzalama ve GİB'e gönderme işlemleri detaylı olarak ele alınmaktadır.
Last updated
Akış Diyagramı
e-Defter Tanımlamaları
E-Defter oluşturabilmek için ilk önce tanımlamaların yapılması ve defteri oluşturacak müşavir bilgilerinin eklenmesi gerekmektedir. Bu tanımlamalar ilgili uç noktalar ile eklenebilir.
e-Defter Oluşturma
Tanımlamalar yapıldıktan sonra E-Defter oluşturmak için örnek .csv dosyası formatındaki veri dosya olarak veya base64 string olarak gönderilebilir. Dosya yükleme işlemi başarılı olduğunda E-Deftere kaynak olacak veriler bir ön kontrole tabi tutulmaktadır. Burada kuyruk yapısı kullanıldığı için için dosya yükleme işlemi başarılı yanıtı dönse bile ön kontrol sonucu hatalı olabilmektedir. Dosya yüklendikten sonra bu dosyaya ait UUID yanıt olarak dönülür. Bu UUID ile durum kontrolü yapılabilir. Kontrol başarılı olduktan sonra imzalama ve GİB’e gönderme işlemleri yapılmalıdır.
e-Defter İmzalama
Defter imzalama işlemi 3 şekilde yapılabilmektedir: Firmanın mali mührü, mali müşavirin e-imzası ya da entegratör firmanın mali mührü ile. Firmanın mali mührü ya da mali müşavirin e-imzası ile imzalama işlemi yapmak için E-Defter tanımlamalarında SignMethod alanı SmartCard olarak seçilmelidir. Eğer imzalama işlemi Nilvera tarafından sizin adınıza yapılacaksa bu alan Hsm olarak seçilmelidir.
Eğer mali/mühür ya da e-imza ile imzalama işlemi yapılacaksa Nilvera E-Defter Socket programının bilgisayarda kurulu ve çalışıyor olması gerekmektedir.
Hsm ile İmzalama
İlk olarak imzalanması istenen defterleri ihtiva eden ayın sayısal değeri ve FiscalYearStart, FiscalYearEnd yani mali dönem başlangıç ve bitiş tarihleri /eledger/Sign/Hsm ucuna gönderilir. İmzalama işlemi kuyruğa alınır ve tamamlandığında defterlerin durumları imzalandı olarak güncellenir. Bu aşamada alınan hatalar ilgili defter dosyalarının StatusCode ve StatusDetail alanına yazılır.
E-İmza/Mali Mühür ile İmzalama
Başlangıç olarak /eledger/Sign/UUID ucuna istek yapılarak imzalanacak defterler liste olarak getirilir.
Bu liste içerisindeki herbir defter için; /eledger/Sign/Base64String ucuna istek yapılarak ilgili defter dosyası base64 string olarak alınır.
Alınan Base64 string localhost:5555/Card/Sign ucuna atılarak imzalanır.
Dönen değer /eledger/Sign/Upload ucuna atılarak defter dosyası güncellenmiş olur.
Tüm defterler imzalanınca imzalama işlemi tamamlanır ve GİB’e gönderme işlemine geçilir.
localhost:5555/Card/Sign ucuna atılan isteklerde eğer yevmiye beratı için işlem yapılıyorsa yevmiye defterinin imzalama işleminde dönen SignatureValue ve Size değerleri bu API ucuna yapılan istekte gönderilir. Kebir beratı imzalanırken de Kebir defterinin SignatureValue ve Size değerleri gönderilir.
e-Defteri GİB'e Gönderme
İmzalama işlemi tamamlandıktan sonra GİB'e gönderilmesi istenen defterler için aşağıdaki işlemler takip edilir:
/eledger/Gib/Send ucuna istek yapılır ve defter GİB'e gönderilmek üzere kuyruğa alınmış olur.
/eledger/Gib/Receive ucuna istek yapılır ve GİB onaylı beratlar getirilmek üzere kuyruğa alınmış olur.
/eledger/Gib/Send/Report ucuna istek yapılır ve defter raporu GİB'e gönderilmek üzere kuyruğa alınmış olur.
/eledger/Gib/Status/Report ucuna istek yapılarak defter raporunun GİB tarafındaki durumu sorgulanmak üzere kuyruğa alınır.
/eledger/Gib/Status ucuna istek yapılarak her aşamanın ardından defterlerin durumları kontrol edilerek ilgili işlemler yapılabilir.
Bu aşamaların tümü başarı ile tamamlandığında ilgili dönem defterleri GİB'e gönderilmiş ve kapatılmış olur. Bu aşamaların tamamında ilgili döneme ait Period ve Year değerleri gönderilmelidir.
E-Defteri GİB'e gönderme ile ilgili yukarıda belirtilen adımlardan bazıları defter durumlarının hatalıya geçmesi ile sonuçlanabilir. Bu durumda /eledger/Gib/ReSend ucuna istek yapılarak tekrar gönderilmesi gereken hatalı defterler tekrar gönderilebilir. Bu şekilde GİB'e tekrar gönderilerek çözülebilecek hatalar çözülmüş olur. Tekrar göndermenin çözüm olmadığı senaryolarda deftere kaynaklık eden veriyi güncelleyip tekrar defter oluşturmak gerekebilir.
