ERC Soft

API Doküman

API BAĞLANTI

Kullanıcı Girişi

https://portal.ercsoft.com.tr/api/login adresine, portal giriş bilgileri

  • email - E-posta
  • pass - Şifre
parametreleri doldurularak gönderilir.

JWT Parametresi

Başarıyla giriş yaptıktan sonra, dönen sonuçta jwt bilgisi gelmektedir.
Bu parametre, yapılan her istekte gönderilmek zorundadır ve süresi 1 saattir. Parametrenin süresi sona erdiğinde Kullanıcı Girişi bölümü tekrarlanır.

Fatura Oluşturma

Doküman sonundaki XML şablonu ile örtüşen fatura taslağınızı https://portal.ercsoft.com.tr/api/faturaolustur adresine

  • jwt - Oturum Anahtarı
  • xml - Fatura XML Şablonu
parametreleri ile göndermeniz gerekmektedir.

ALICI BİLGİLERİ

Alıcı Kaydı Oluşturma
  • XML şablonunda receiver etiketleri arasında bulunan bilgiler doğrultusunda, kayıtlı alıcı oluşturur veya var olanı seçer.
  • Hesabınızda, belirttiğiniz kullanıcıya ait kayıt olup olmadığı, VKN/TCKN ile kontrol edilir.
  • Alıcı firma listenizde kayıtlı değilse; Kayıt Adı, Kayıtlı Alıcılar listesinde, alıcı firmanın unvanı olarak atanır.
Alıcı - XML Etiket Açıklamaları
* ile işaretlenenler zorunludur.
  • title * - Alıcı Unvan / Ad Soyad
  • identifier * - Alıcı Vergi Kimlik Numarası / T.C Kimlik Numarası
  • taxAdmin - Vergi Dairesi
  • alias - Alıcı Etiket Bilgisi

    Eğer alıcı GiB'e kayıtlıysa bu alan zorunludur. Alıcının Posta Kutusu adresi girilmelidir.

  • Alıcı Adres Bilgileri
  • country * - Ülke
  • city * - Şehir
  • district - İlçe
  • quarter - Mahalle
  • street - Cadde / Sokak
  • town - Kasaba / Köy
  • buildingName - Bina Adı
  • buildingNumber - Bina Numarası
  • doorNumber - Kapı Numarası
  • postalCode - Posta Kodu
  • phoneNumber - Telefon Numarası
  • faxNumber - Faks Numarası
  • emailAddress - E-Posta Adresi
  • website - İnternet Sitesi
  • Alıcı Tanım Bilgileri

    Alıcıya ait; Mersis No, Telefon No, Hizmet No gibi bilgileri kayıt edebilirsiniz.

  • descriptions - Tanımlar

    Bu bölüm döngü içerisinde olmalıdır ve döngüye <description> ile başlanmalıdır.

  • name - Tanım Seçimi

    Bu değer <description> etiketi içerisinde gönderilmelidir.

  • value - Tanım Değeri

    Bu değer <description> etiketi içerisinde gönderilmelidir.

    Bu değer için kabul edilen girdiler:

    • MERSISNO
    • HIZMETNO
    • MUSTERINO
    • TESISATNO
    • TELEFONNO
    • DISTRIBUTORNO
    • TICARETSICILNO
    • TAPDKNO
    • BAYINO
    • ABONENO
    • SAYACNO
    • URETICINO
    • CIFTCINO
    • IMALATCINO
    • DOSYANO
    • HASTANO

    Not: value için gönderilecek olan veri bitişik ve büyük harfle yazılmalıdır.

  •                                 
                                        <!-- Örnek Yapı -->
                                        <descriptions>
                                            <description>
                                                <name>MERSISNO</name>
                                                <value>11111111111</value>
                                            </description>
                                            <description>
                                                <name>TELEFONNO</name>
                                                <value>05050505050</value>
                                            </description>
                                        </descriptions>
                                    
                                
Alıcı İstisna Durumlar
  • Eğer, Fatura Senaryo (invoiceScript) IHRACAT ise Mal Alan Firma bilgileri girilmelidir.
  • Eğer, Fatura Senaryo (invoiceScript) YOLCUBERABER ise Turist bilgileri girilmelidir.
Alıcı XML Örneği
                                
                                
                            

GÖNDERİCİ BİLGİLERİ

Gönderici Bilgileri
  • XML şablonunda sender etiketleri arasında gönderilen bilgilerdir.
Gönderici - XML Etiket Açıklamaları
  • alias - Gönderici Etiket

    Eğer Fatura Senaryo e-Arşiv (EARSIVFATURA) ise bu bilgiye ihtiyaç yoktur.

Gönderici bilgileri sisteme kayıt olurken girilen bilgiler olarak belirlenir ve düzenleme yapılamaz.

Gönderici XML Örneği
                                
                                
                            

FATURA BİLGİLERİ

Fatura Senaryo
  • XML şablonunda invoiceScript etiketi arasında gönderilen bilgidir.
  • Kabul edilen değerler :
    • TEMELFATURA

      Eğer Alıcı GiB'e kayıtlı değilse TEMELFATURA gönderilemez.

    • TICARIFATURA

      Eğer Alıcı GiB'e kayıtlı değilse TICARIFATURA gönderilemez.

    • EARSIVFATURA

      Fatura Senaryo EARSIVFATURA ise, Gönderim Şekli mecburidir.

    • IHRACAT

      Fatura Senaryo IHRACAT ise, Mal Alan Firma bilgileri girilmelidir.
      İstisna Fatura Sebebi, 301 değerini almalıdır.

    • YOLCUBERABER

      Fatura Senaryo YOLCUBERABER ise, Turist bilgileri girilmelidir.
      İstisna Fatura Sebebi, 501 değerini almalıdır.

    • KAMU

      Fatura Senaryo KAMU ise, Ödeme Bilgisi bilgileri girilmelidir.

  • Gönderim Şekli

    sendType etiketi arasında gönderilen bilgidir. İki çeşit Gönderim Şekli vardır:

    • Elektronik - elektronik ( gönderilen veri )
    • Kağıt - kagit ( gönderilen veri )

Not: invoiceScript içinde gönderilen veri bitişik ve büyük harfle yazılmalıdır.

Fatura Tipi
  • XML şablonunda invoiceType etiketi arasında gönderilen bilgidir.
  • Kabul edilen değerler :
    • SATIS
    • IADE
    • ISTISNA
    • TEVKIFAT
    • OZELMATRAH
    • IHRACKAYITLIFATURA
    • SGK

Not: invoiceType içinde gönderilen veri bitişik ve büyük harfle yazılmalıdır.

Müşteri Fatura Numarası
  • XML şablonunda custInvNo etiketi arasında gönderilen bilgidir.
  • Zorunlu alan değildir. Fatura gönderilirken de oluşturulabilir.
Fatura Düzenleme Tarihi / Saati
  • invoiceDate * - Düzenleme Tarihi
  • invoiceTime - Düzenleme Saati
Doküman Para Birimi Bilgisi
  • XML şablonunda documentCurrency etiketi arasında gönderilir.
  • XML Etiket Açıklamaları
    • currency - Para Birimi
    • rate - Kur
Sipariş Bilgisi
  • XML şablonunda orderInfo etiketi arasında gönderilir.
  • XML Etiket Açıklamaları
    • orderNumber - Sipariş Numarası
    • orderDate - Sipariş Tarihi
İrsaliye Bilgisi
  • XML şablonunda partyWaybill döngüsü oluşturulur ve döngüye wayBill etiketi ile başlanır.
  • wayBill etiketi altında:
    • wbNumber - İrsaliye Numarası
    • wbDate - İrsaliye Tarihi
Ödeme Bilgisi
  • XML şablonunda paymentInfo etiketi arasında gönderilir.
  • XML Etiket Açıklamaları
    • type - Ödeme Şekli
    • channel - Ödeme Kanalı
    • currency - Para Birimi
    • iban - IBAN
    • note - Ödeme Notu
Doküman Bilgisi
  • XML şablonunda partyDocumentInfo döngüsü oluşturulur ve döngüye documentInfo etiketi ile başlanır.
  • documentInfo etiketi altında:
    • note - Doküman Notu
    • date - Doküman Tarihi
    • type - Doküman Tipi
Fatura Notları
  • XML şablonunda invoiceNotes döngüsü oluşturulur ve döngüye note etiketi ile başlanır.
  • XML Etiket Açıklamaları
    • note - Fatura Notu
Dönem Bilgisi
  • XML şablonunda period etiketi arasında gönderilir.
  • XML Etiket Açıklamaları
    • periodStartDate - Dönem Başlangıç Tarihi
    • periodEndDate - Dönem Bitiş Tarihi
İnternet Satış
  • XML şablonunda internetSale etiketi arasında gönderilir.
  • Fatura Senaryosu EARSIVFATURA olduğunda veya Fatura Tipi Tevkifat olduğunda gönderilebilir.
  • XML Etiket Açıklamaları
    • type - Ödeme Şekli
    • channel - Ödeme Kanalı
    • currency - Para Birimi
    • iban - IBAN
    • note - Ödeme Notu
İstisna Fatura Sebebi
  • XML şablonunda invoiceExceptionReason etiketi arasında gönderilen bilgidir.
  • Sadece kod olarak kabul edilir. (101, 301, 501 vb.)
  • Fatura Senaryo YOLCUBERABER ise kod 501, IHRACAT ise kod 301 gönderilmelidir.
İhraç Kayıtlı Fatura
  • XML şablonunda issuedInvoiceReason etiketi arasında gönderilen bilgidir.
  • Sadece kod olarak kabul edilir. (701, 702, 703)
Özel Matrah
  • XML şablonunda taxAssessment etiketi arasında gönderilir.
  • Fatura Senaryosu EARSIVFATURA olduğunda veya Fatura Tipi Tevkifat olduğunda gönderilebilir.
  • XML Etiket Açıklamaları
    • value - Özel Matrah
    • percentage - Yüzde
    • amount - Miktar
    • reason - Özel Matrah Nedeni

      Sadece kod kabul edilir. ( 801, 802, 803 vb. )

Fatura Bilgileri XML Örneği
                            
                        

MAL/HİZMET BİLGİLERİ

Mal/Hizmet Oluşturma
  • XML şablonunda partyInvoiceLine döngüsü oluşturulur ve döngüye invoiceLine etiketi ile başlanır.
Mal/Hizmet - XML Etiket Açıklamaları

Bu sayfadaki tüm XML kodları invoiceLine etiketi arasına yazılmalıdır.

  • itemName * - Mal/Hizmet Adı
  • invoicedQuantity * - Miktar
  • Birim - unitetiketi altında.
    • unitCode * - Birim Kodu (Adet = C62 vb.)
    • unitPrice * - Birim Fiyat
  • Mal/Hizmet Tutar - priceetiketi altında.
    • priceAmount * - Mal/Hizmet Tutar (Vergiler Hariç)
    • taxIncludedPrice * - Vergiler Dahil Toplam Tutar
  • İskonto - discountetiketi altında.
    • rate - İskonto Oranı
    • amount - İskonto Tutarı
  • Diğer Vergiler - otherTaxes döngüsü oluşturulur ve döngüye tax etiketi ile başlanır.
    • name - Vergi Adı
    • rate - Vergi Oranı
    • amount - Vergi Tutarı
  • KDV - VATetiketi altında.
    • rate * - KDV Oranı
    • amount * - KDV Tutarı
    • KDV ->Tevkifat - withHoldingetiketi altında.
      • type - Tevkifat Tipi
      • rate - Tevkifat Oranı
      • amount - Tevkifat Tutarı
  • Kalem Notları - itemNotes döngüsü oluşturulur ve döngüye note etiketi ile başlanır.
    • note - Kalem Notu
  • buyerInfo - Alıcı Ürün Bilgisi
  • senderInfo - Gönderici Ürün Bilgisi
  • itemOrigin - Menşei
  • Sınıflandırma - sortingetiketi altında.
    • code * - Sınıflandırma Kodu
    • version * - Sınıflandırma Versiyonu
    • value * - Sınıflandırma Değeri
Ortak Mal Hizmet Bilgileri
  • Eğer Fatura Senaryo, IHRACAT ise invoiceLine etiketi altında bu bilgiler gönderilmelidir.
Eşyanın Teslim Yeri
    Eşyanın teslim edileceği adres bilgisi deliveryLocation etiketi altında gönderilmelidir.
  • country * - Ülke
  • city * - Şehir
  • district * - İlçe
  • quarter - Mahalle
  • street - Cadde / Sokak
  • town - Kasaba / Köy
  • buildingName - Bina Adı
  • buildingNumber - Bina Numarası
  • doorNumber - Kapı Numarası
  • postalCode - Posta Kodu
Kap Bilgileri
    Eşyanın bulunduğu kap bilgisi containerInfo etiketi altında gönderilmelidir.
  • gtipNo * - GTIP Numarası
  • containerType * - Kap Cinsi

    Sadece Kod gönderilmelidir. ( AE, AP, AT vb. )

  • containerNumber * - Kap Numarası
  • containerAmount - Kap Adet
  • containerBrand - Kap Markası
Diğer Bilgiler
  • deliveryCondition * - Teslim Şartı

    Sadece Kod gönderilmelidir. ( CFR, CIP, CPT vb. )

  • containerType * - Teslim Şekli

    Sadece Kod gönderilmelidir. ( 1, 2, 3 vb. ) Sıralama aşağıdaki gibidir.

    1. Denizyolu
    2. Demiryolu
    3. Karayolu
    4. Havayolu
    5. Posta
    6. Çok Araçlı
    7. Sabit Taşıma Tesisleri
    8. İç su taşımacılığı
  • containerNumber * - Kap Numarası
  • containerAmount - Kap Adet
  • containerBrand - Kap Markası
  • Denizyolu - seawayDeliveryetiketi altında.
    • imoNo - IMO ve MMSI No
    • shipName - Geminin Adı
    • radioName - Radyo Çağrı Adı
    • shipRegisterName - Geminin Kayıt Adı
    • shipNetWeight - Geminin Net Ağırlığı
    • shipNeeds - Geminin İhtiyaçları
    • shipGrossWeight - Geminin Brüt Ağırlığı
    • shipPort - Geminin Kayıt Limanı
  • Demiryolu - railwayDeliveryetiketi altında.,
  • trainNumber - Tren Numarası
  • carNumber - Vagon Numarası
  • Karayolu - highwayDeliveryetiketi altında.,
  • licensePlateNumber - Plaka Numarası
  • Havayolu - airwayDeliveryetiketi altında.,
  • aircraftNumber - Hava Aracı Numarası
Mal/Hizmet - XML Örneği
                                
                            

TOPLAMLAR

Toplam Tutar
  • XML şablonunda total etiketleri arasında gönderilen bilgilerdir.
Toplam Tutar - XML Etiket Açıklamaları
  • totalItemPrice * - Mal/Hizmet Toplam Tutar (Vergiler Hariç)
  • taxIncludedTotal * - Vergiler Dahil Toplam Tutar
  • paidAmout * - Ödenecek Toplam Tutar
Toplam Tutar - XML Örneği
                            
                        

XML ŞABLON ÖRNEĞİ