GİB UBL-TR Update: An e-Invoice Integration Guide for ERP Teams

e-Invoice integration and the 14 September 2026 UBL-TR update

On 27 July 2026, Türkiye's Revenue Administration (GİB) updated its e-Invoice (e-Fatura) package, its e-Archive Invoice package and the UBL-TR Code Lists Guide, and the changes went live on 14 September 2026. For any company issuing invoices from its ERP, this means new exemption codes, new plate and trailer rules, mandatory fields for EV charging invoices and a new alias for the e-Expense Voucher, all inside the e-invoice integration layer. Systems that send missing or outdated values in these fields can no longer get their invoices past Schematron validation.

This article explains what changed, which ERP fields and mappings are affected, how to run a test plan in your private integrator's test environment, and how to build a resilient middleware layer with queues, retries and idempotency. It ends with a checklist ERP and finance teams can use as is.

In short

• GİB's packages dated 27 July 2026 came into force on 14 September 2026; gaps in the e-Invoice package were fixed separately on 24 August 2026.
• Main areas affected: exemption code lists (233 added, 308 and 339 moved to the investment-incentive list), plate/trailer types, SARJ and SARJANLIK invoices and the erreceipt alias.
• Do not leave validation to the integrator: run the current XSD and Schematron files in your own CI pipeline.
• A queue, classified retries and ETTN-based idempotency in the middleware reduce the risk of duplicate or lost invoices.
• Track rejected invoices by error code; a rollback plan should hold affected documents, not "go back to the old format".

What did GİB publish, and when did it take effect?

According to the announcements on GİB's e-Document portal, the timeline was as follows. On 27 July 2026 the e-Invoice package, the e-Archive Invoice package and the UBL-TR (Code Lists) Guide were updated, with the changes scheduled to go live on 14 September 2026. On 11 August, gaps in the e-Archive package's earsiv.xsd were fixed. On 24 August, GİB announced that gaps in the e-Invoice package published on 27 July had also been fixed.

That last fix carries a lesson: a package can change after it is published. A team that downloaded the package in late July and installed it in test could go live with different rules if it missed the late-August fix. Store package files with their date and version, and diff them every time a new announcement appears.

Which files changed?

Technically, the changes live in the code list and Schematron files of GİB's UBL-TR 1.2.1 package. According to NES's 24 August analysis, the fix covered UBL-TR_Codelist.xml, UBL-TR_Common_Schematron.xml and UBL-TR_Main_Schematron.xml. The code lists guide moved to version 1.43, and earsiv.xsd was updated on the e-Archive side.

What changed in the private integration guide?

Separately, on 29 June 2026 GİB updated the e-Invoice Private Integration Guide to v1.14. Its change log states that ISO certificates approved by TÜRKAK (the Turkish Accreditation Agency) are now mandatory for taxpayers applying for private integration. The guide lists ISO 27001 for information security, ISO 22301 for business continuity and ISO 20000 for IT service management. Companies that send invoices through a private integrator only need to confirm these certificates with their integrator.

Which ERP fields and mappings are affected?

Most of the update touches master data and mapping tables in the ERP, not the code that generates XML. How fields such as "exemption code", "plate" and "invoice type" are stored in the ERP, and how they map to UBL-TR elements, decides whether an invoice is accepted.

Exemption codes and invoice types

Exemption code 233 was added to the code list: transfers of real estate to the state and public legal entities under the Expropriation Law No. 2942. Codes 308 and 339 were removed from the general list and moved to a new investment-incentive exemption list (YatirimTesvikTaxExemptionReasonCodeType). Under the Schematron rule, codes on the exemption list may only be used with the ISTISNA, IADE, IHRACKAYITLI, SGK, YTBISTISNA and YTBIADE invoice types. KAMU was also added to the scenarios allowed for IADE (return) invoices.

Plate and trailer fields

YABANCIDORSE, YABANCIPLAKA and YABANCIDORSEPLAKA were added to the plate types alongside DORSEPLAKA. With the 24 August fix, schemeID values in LicensePlateID were limited to PLAKA and YABANCIPLAKA, and trailer types moved to a TransportEquipment/ID check. Foreign plates accept only capital letters, digits, underscores and hyphens. In e-Dispatch notes, a plate is mandatory whenever a driver (DriverPerson) is present. If "plate" is a single free-text field in your ERP, you may need to split vehicle versus trailer and domestic versus foreign into separate fields.

EV charging invoices (SARJ and SARJANLIK)

SARJ and SARJANLIK energy invoices now require a buyer identifier with schemeID="PLAKA". The invoice period (InvoicePeriod) must include start and end dates and times. SARJ invoices also need an ESURaporID in GUID format plus the report date, and SARJANLIK invoices need a serial number. Companies running charging stations often have none of these fields in the ERP; they have to be carried over from the operations platform.

e-Expense Voucher and the erreceipt alias

GİB added the erreceipt alias, representing the e-Expense Voucher (e-Gider Pusulası), to the reserved aliases that may not be used in e-document XML and to the user envelope aliases. For erreceipt user accounts, the UserOptionCode field is mandatory and must be 171, 172, 173 or 174. GİB also updated the e-Expense Voucher package on 15 September 2026.

The e-Archive side

According to Vergi Teknolojileri's summary, the e-Archive XSD now accepts more than one ESU report ID. Buyer details must be given either as a legal entity (tax number and title) or as a natural person (national ID number and name), never both. For technology-support invoices (TEKNOLOJIDESTEK), the profile must be EARSIVFATURA.

Change	Affected field / process	Action
Exemption code 233 added	Exemption code master data, sales invoice templates	Add it to the mapping table; allow it only with permitted invoice types
308 and 339 moved to the investment-incentive list	Incentive sales invoices, YTBISTISNA/YTBIADE flow	Read the codes from the right list; retire the old mapping
Exemption code ↔ invoice type rule	Invoice type selection, ERP validation rules	Enforce the same rule at entry time and show the error to the user
Foreign plate/trailer types, TransportEquipment for trailers	Vehicle master data, shipping, e-Dispatch	Split vehicle and trailer fields; validate foreign plate format
Plate mandatory when a driver is present	Dispatch note screen, logistics integration	Make plate required once a driver is entered
SARJ / SARJANLIK mandatory fields	Energy invoices, charging platform data	Carry plate, period times, ESURaporID and serial number from the source
erreceipt alias and UserOptionCode	Envelope generation, user list processing	Add the alias check and the 171–174 value check
e-Archive buyer rule	Customer master, retail sales	Prevent tax number and national ID from being sent together

What test plan should you run in the integrator's test environment?

The goal is to see every scenario that would be rejected in production while you are still in test. That requires a scenario matrix built from real ERP data and deliberately broken negative test documents. Run them end to end in your private integrator's test environment, including signature, envelope and response.

Scenario matrix

Rows are invoice types and scenarios (TEMELFATURA, TICARIFATURA, KAMU, EARSIVFATURA and so on); columns are the fields touched by the update. Produce at least one valid document per cell. Picking one example of every type and exemption combination from the last six months of invoices is the quickest way to catch forgotten edge cases.

Negative tests

Negative tests are expected to be rejected: sending code 233 with a disallowed invoice type, putting lower-case letters or spaces in a foreign plate, leaving the plate empty on a dispatch note that has a driver. They prove your Schematron is current and that rejection codes flow back to the ERP correctly.

Why should Schematron and XSD validation run in your own CI?

XSD checks a document's structure: which element goes where and with what type. Schematron checks business rules, such as "this exemption code may only be used with these invoice types". The Schematron files in GİB's package are the source of the rules your integrator and GİB enforce.

Leaving these checks to the integrator means finding errors at the latest and most expensive point. Instead, put the XSD and Schematron files from GİB's package under version control and validate your sample documents against them automatically on every mapping change. When a fix like the one on 24 August arrives, updating the file and re-running the tests takes minutes.

Pre-validation belongs in the middleware too

The same validation can run in production, in the middleware, before a document reaches the integrator. A bad document is then flagged as a "business error" in the queue, never leaves your system, and the user sees the error on the ERP screen. That cuts rejections and back-and-forth with the integrator.

Middleware: queue, retry and idempotency

In many companies the ERP calls the integrator's API directly. That model is exposed to lost invoices or duplicate submissions whenever the integrator slows down or the network hiccups. An enterprise integration middleware layer manages these risks in one place.

Queue and outbox

In the same database transaction that saves the invoice, the ERP writes a "to send" row into an outbox table. The middleware reads that table and enqueues the work, so if an invoice was saved, its send task definitely exists. Our article on the outbox pattern, idempotency and retries goes into detail.

Classified retries

Not every error should be retried. Technical errors such as timeouts or temporary service failures are retried with increasing back-off. Business errors such as Schematron rejections are not retried; the document goes back to the ERP for correction. Without that split, a broken document circles the queue indefinitely.

Idempotency with the ETTN

Each invoice's universally unique identifier (ETTN, a UUID) should be generated once when the document is created and stay the same across retries. The middleware uses it as the idempotency key: if a second send request arrives with the same ETTN, it returns the earlier result. Contract tests help when the integrator's API changes; we covered that approach in API contract design and backward compatibility.

• • •

How do you build a rollback plan?

Since GİB no longer accepts documents under the old rules after 14 September, rollback cannot mean "go back to the old format". A sound rollback plan pauses and holds the affected document type when a bug appears in the new mapping code, while other documents keep flowing.

• Switch new mappings on behind a feature flag, starting with a pilot series or branch.
• Version your mapping tables so you can return to the previous correct version in one step.
• Define a per-document-type "hold" switch so held documents stay safely in the queue.
• After the fix, resend held documents with the same ETTN at a controlled rate.
• Log every rollback decision with who made it, when and why.

How do you monitor rejected invoices?

In the private integrator model, every document gets a system response, and commercial invoices also get the buyer's application response. If these responses are not written back to the ERP record, finance learns about a rejected invoice only when the customer calls. The dashboard should show at least the rejection rate by document type, the breakdown by error code, the number of queued documents and the age of the oldest one.

When thresholds are breached, alerts should reach both the integration team and accounting. The first two weeks after a cut-over date like 14 September are the most critical time to watch the rejection rate daily and turn the most frequent error codes into mapping fixes quickly.

For a refresher on how e-Invoice and e-Archive Invoice work, GİB's short introductory video (in Turkish) is a good start:

Checklist for ERP teams

The list below is written so you can reuse it when the next GİB package arrives:

• Someone is assigned to check GİB e-Document announcements weekly.
• The current UBL-TR package, code lists and Schematron files are stored in the repository with date and version.
• Exemption code, invoice type, plate and trailer mapping tables have been reviewed against V1.43.
• ERP screens enforce the exemption code ↔ invoice type rule at entry time.
• Vehicle, trailer and foreign plate data sit in separate fields and their format is validated.
• If SARJ/SARJANLIK or the e-Expense Voucher are used, the source of each mandatory field is identified.
• The scenario matrix and negative tests have run end to end in the integrator's test environment.
• XSD and Schematron validation run in CI and in the middleware.
• Outbox, classified retries and ETTN-based idempotency are in place.
• Feature flag, mapping versions and a per-document-type hold switch are ready.
• Rejection rate and error-code breakdown are on the dashboard; threshold alerts also reach accounting.
• The private integrator's current ISO certificates and package update schedule are confirmed.

Plates and trailers: now separate fields with separate checks.

Shipping: a plate is mandatory when a driver is on the e-Dispatch note.

e-Expense Voucher: the erreceipt alias is now part of envelope checks.

How Aksiyon Soft can help

At Aksiyon Soft we treat e-Invoice and e-Archive flows as a middleware layer independent of the ERP. Work starts with discovery: we review current mappings, recent rejection codes and the integrator connection, then list the affected fields. Next we build an MVP with queueing, validation and monitoring, move forward with two-week sprint demos, and provide hypercare and SLA-backed support after go-live.

We deliver this through our API and integration and enterprise software solutions services, using our API and data integration platform as the foundation. If you want a quick review of your current flow, see our e-invoice UBL-TR integration check service. We are headquartered in Samsun, work remotely across Türkiye and make planned on-site visits when needed.

Frequently asked questions

Does the 14 September 2026 update affect every e-Invoice user?

The rules live in GİB's Schematron and code lists, so every document is checked against them. The practical impact depends on the invoice types you use: if you do not issue exempt sales, vehicle and shipping documents, EV charging invoices or e-Expense Vouchers, the change may be limited.

If our private integrator has updated, do we still need to do anything?

The integrator updates its own validation and delivery layer. Making sure your ERP sends the right exemption code, plate type or mandatory field is your responsibility. If mappings are not updated, documents are rejected by the integrator or by GİB.

Is resending an invoice that failed Schematron enough?

No. A Schematron rejection is a business error; resending the same document gives the same result. Fix the data or mapping in the ERP first, then regenerate and resend the document.

Which documents should we try in the test environment?

At least one example of every invoice type and exemption combination you issued recently, shipments with foreign plates and trailers, SARJ/SARJANLIK invoices if you issue them, and deliberately broken negative test documents.

Who should generate the ETTN?

The ETTN should be generated once when the document is created and never change across retries. It can be generated in the ERP or the middleware; what matters is that the same invoice always goes out with the same ETTN.

How do we prepare for the next GİB package?

Someone watching announcements, versioned package files, automated validation in CI and a current scenario matrix. With those four in place, a new package becomes a few days of mapping work.

Sources

• Revenue Administration (GİB) e-Document portal — Announcements (27 Jul, 11 Aug, 24 Aug, 15 Sep 2026)
• Revenue Administration (GİB) e-Document portal — e-Invoice legislation, UBL-TR 1.2.1 package and guides
• Revenue Administration (GİB) — e-Invoice Private Integration Guide v1.14 (29 Jun 2026, Turkish)
• NES — GİB updates e-Invoice, e-Archive and UBL-TR packages (27 Jul 2026, Turkish)
• NES — Plate and trailer checks fixed in GİB e-Invoice package (24 Aug 2026, Turkish)
• Vergi Teknolojileri — GİB e-Invoice and e-Archive guides updated: changes going live on 14 September (2026, Turkish)
• Müşavirler Kulübü — GİB e-Invoice and e-Archive guide updates in force on 14 September 2026 (14 Sep 2026, Turkish)

Let's talk about your project

If you want to check your ERP's readiness for the UBL-TR update, bring down your rejection rate or move your e-invoice integration onto a resilient middleware layer, get in touch with us. In a first call we will review your current flow and recent rejection codes together and sketch a concrete roadmap.