Build e-Fatura (UBL-TR 1.2) Invoice XML

Skill: Convert a B2B invoice into the e-Fatura UBL-TR XML routed through GİB

Region: Türkiye (Turkey) Category: E-Invoicing — e-Fatura Does: Takes ordinary B2B invoice data and produces the e-Fatura XML in the Turkish UBL-TR 1.2 customization of OASIS UBL 2.1 (Invoice), carrying the ETTN (Evrensel Tekil Tanımlama Numarası) UUID, sender/receiver VKN/TCKN, and KDV lines, routed through the GİB (Gelir İdaresi Başkanlığı) either via the central portal (merkez) or a private integrator (özel entegratör). Standard: UBL-TR 1.2 (Turkish customization of OASIS UBL 2.1)

e-Fatura is mandatory for transactions between registered e-Fatura users (both sender and receiver are in the GİB user registry). If the receiver is not a registered e-Fatura user, the document must instead be an e-Arşiv Fatura. The XML is digitally signed (Mali Mühür / e-imza) and delivered through GİB merkez, özel entegratör, or an entegrasyon connection. Validate against the current UBL-TR schema and GİB schematron before sending.

When this applies

• Both parties are registered e-Fatura users in the GİB registry (registration is required above the Maliye-set turnover threshold and for certain sectors).
• The scenario is one of the UBL-TR profiles: TEMELFATURA (basic, no formal rejection) or TICARIFATURA (commercial, allows acceptance/rejection within the response window).
• For B2C or unregistered receivers, use the e-Arşiv Fatura skill instead.

Input data required

The VKN (Vergi Kimlik Numarası, 10 digits) identifies legal entities; the TCKN (T.C. Kimlik Numarası, 11 digits) identifies individuals. Party identification uses cac:PartyIdentification/cbc:ID with schemeID="VKN" or schemeID="TCKN".

Document structure (UBL-TR 1.2)

Invoice
├── cbc:UBLVersionID            (2.1)
├── cbc:CustomizationID         (TR1.2)
├── cbc:ProfileID               (TEMELFATURA | TICARIFATURA)
├── cbc:ID                      (16-char invoice number)
├── cbc:UUID                    (ETTN)
├── cbc:IssueDate / cbc:IssueTime
├── cbc:InvoiceTypeCode         (SATIS, IADE, TEVKIFAT, ISTISNA, OZELMATRAH)
├── cbc:DocumentCurrencyCode    (TRY)
├── cac:AccountingSupplierParty (satıcı — VKN, vergi dairesi, adres)
├── cac:AccountingCustomerParty (alıcı — VKN/TCKN, adres)
├── cac:TaxTotal                (per-rate cac:TaxSubtotal, KDV)
├── cac:LegalMonetaryTotal      (LineExtension, TaxExclusive, TaxInclusive, Payable)
└── cac:InvoiceLine ...         (Quantity, Price, LineExtensionAmount, TaxTotal)

KDV is identified by TaxTypeCode 0015 (Katma Değer Vergisi). Standard KDV rate is 20%; reduced rates 10% and 1%. Tevkifat (KDV withholding) uses cac:WithholdingTaxTotal with the relevant tevkifat code.

Calculation rules

• Line amount (LineExtensionAmount) = quantity × unit price − line discounts (2 decimals).
• Group lines by KDV rate → per-rate cac:TaxSubtotal with TaxableAmount and TaxAmount = TaxableAmount × rate.
• LegalMonetaryTotal/TaxExclusiveAmount = sum of line amounts; TaxInclusiveAmount = tax-exclusive + total KDV.
• PayableAmount = TaxInclusiveAmount − allowances + charges − any tevkifat withheld.
• KDV rates: standard 20%, reduced 10% and 1%; some deliveries are istisna (exempt, code with cbc:TaxExemptionReasonCode).

Worked example (TEMELFATURA, header + one line)

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
  xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
  xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>TR1.2</cbc:CustomizationID>
  <cbc:ProfileID>TEMELFATURA</cbc:ProfileID>
  <cbc:ID>ABC2026000000123</cbc:ID>
  <cbc:UUID>f47ac10b-58cc-4372-a567-0e02b2c3d479</cbc:UUID>
  <cbc:IssueDate>2026-06-04</cbc:IssueDate>
  <cbc:IssueTime>10:15:00</cbc:IssueTime>
  <cbc:InvoiceTypeCode>SATIS</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>TRY</cbc:DocumentCurrencyCode>
  <cbc:LineCountNumeric>1</cbc:LineCountNumeric>
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyIdentification><cbc:ID schemeID="VKN">1234567890</cbc:ID></cac:PartyIdentification>
      <cac:PartyName><cbc:Name>Örnek Teknoloji A.Ş.</cbc:Name></cac:PartyName>
      <cac:PostalAddress><cbc:CitySubdivisionName>Şişli</cbc:CitySubdivisionName><cbc:CityName>İstanbul</cbc:CityName><cac:Country><cbc:Name>Türkiye</cbc:Name></cac:Country></cac:PostalAddress>
      <cac:PartyTaxScheme><cac:TaxScheme><cbc:Name>Mecidiyeköy</cbc:Name></cac:TaxScheme></cac:PartyTaxScheme>
    </cac:Party>
  </cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>
    <cac:Party>
      <cac:PartyIdentification><cbc:ID schemeID="VKN">9876543210</cbc:ID></cac:PartyIdentification>
      <cac:PartyName><cbc:Name>Alıcı Sanayi Ltd. Şti.</cbc:Name></cac:PartyName>
      <cac:PostalAddress><cbc:CitySubdivisionName>Çankaya</cbc:CitySubdivisionName><cbc:CityName>Ankara</cbc:CityName><cac:Country><cbc:Name>Türkiye</cbc:Name></cac:Country></cac:PostalAddress>
    </cac:Party>
  </cac:AccountingCustomerParty>
  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="TRY">2000.00</cbc:TaxAmount>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="TRY">10000.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="TRY">2000.00</cbc:TaxAmount>
      <cbc:Percent>20</cbc:Percent>
      <cac:TaxCategory><cac:TaxScheme><cbc:Name>KDV</cbc:Name><cbc:TaxTypeCode>0015</cbc:TaxTypeCode></cac:TaxScheme></cac:TaxCategory>
    </cac:TaxSubtotal>
  </cac:TaxTotal>
  <cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="TRY">10000.00</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="TRY">10000.00</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="TRY">12000.00</cbc:TaxInclusiveAmount>
    <cbc:PayableAmount currencyID="TRY">12000.00</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="C62">40</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="TRY">10000.00</cbc:LineExtensionAmount>
    <cac:TaxTotal>
      <cbc:TaxAmount currencyID="TRY">2000.00</cbc:TaxAmount>
      <cac:TaxSubtotal>
        <cbc:TaxableAmount currencyID="TRY">10000.00</cbc:TaxableAmount>
        <cbc:TaxAmount currencyID="TRY">2000.00</cbc:TaxAmount>
        <cbc:Percent>20</cbc:Percent>
        <cac:TaxCategory><cac:TaxScheme><cbc:Name>KDV</cbc:Name><cbc:TaxTypeCode>0015</cbc:TaxTypeCode></cac:TaxScheme></cac:TaxCategory>
      </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:Item><cbc:Name>Danışmanlık hizmeti</cbc:Name></cac:Item>
    <cac:Price><cbc:PriceAmount currencyID="TRY">250.00</cbc:PriceAmount></cac:Price>
  </cac:InvoiceLine>
</Invoice>

Sign the document with the Mali Mühür (corporate seal) or e-imza, then deliver via GİB merkez, an özel entegratör, or a direct entegrasyon connection.

Validation checklist

• CustomizationID = TR1.2; ProfileID is TEMELFATURA or TICARIFATURA
• cbc:UUID is a valid ETTN; cbc:ID is the 16-char invoice number (prefix + year + sequence)
• Receiver is a registered e-Fatura user (otherwise use e-Arşiv Fatura)
• Seller VKN + vergi dairesi present; buyer VKN/TCKN with correct schemeID
• Each line: quantity (unitCode), price, KDV rate, line/tax amounts; KDV TaxTypeCode 0015
• Per-rate KDV subtotals reconcile with line totals (20% / 10% / 1%); tevkifat/istisna handled if applicable
• TaxInclusiveAmount = tax-exclusive + KDV; PayableAmount correct after allowances/withholding
• Document signed (Mali Mühür / e-imza) and passes UBL-TR schema + GİB validation before routing

Last updated: 2026-06-04 — confirm the active schema version, field codes, and GİB requirements against the current Gelir İdaresi Başkanlığı (Revenue Administration) specifications before use.