E-Invoicing in Turkey: How to Integrate e-Fatura and e-Arşiv

For many businesses, e-invoicing in Turkey starts as a compliance task and turns into an integration project. Invoices should come straight out of the software you already run, whether that is your online store, your marketplace connections, a B2B portal or your ERP, and travel through the Revenue Administration (GİB) system without anyone retyping them, while incoming invoices flow back into your records the same way. It sounds simple until e-Arşiv invoices, e-İrsaliye dispatch notes, taxpayer lookups, invoice scenarios, cancellations and archiving enter the picture. This guide explains how the documents differ, which integration routes exist, what to watch for when invoices start in ecommerce, marketplaces, B2B ordering or the ERP, and how to integrate e-Fatura step by step.

e-Fatura, e-Arşiv and e-İrsaliye: what is the difference?

All three belong to Turkey's e-transformation (e-Dönüşüm) programme and use a similar XML structure. What differs is who receives the document and how it gets there:

In practice, a seller registered for e-Fatura issues an e-Fatura to some customers and an e-Arşiv invoice to others. If you also use e-İrsaliye, shipments to recipients who are registered for it get a separate e-İrsaliye dispatch note alongside the invoice. So the integration should be designed for all three from the start, not one document type at a time. Other e-documents exist, such as e-SMM, e-Müstahsil and e-Defter, but this guide focuses on invoices and dispatch notes.

Who has to use e-Fatura, e-Arşiv and e-İrsaliye?

The obligations are set out in Tax Procedure Law general communiqués and announced by GİB, based on gross sales, line of business and some sector-specific criteria. The thresholds and start dates have changed several times over the years, so we deliberately give no figures here. Check GİB's current e-transformation announcements and confirm your position with your accountant. Businesses that are not required to join can still register voluntarily.

e-Arşiv and e-İrsaliye have scope criteria of their own; on the e-Arşiv side, for example, there are separate rules for businesses selling online. e-Fatura users generally issue e-Arşiv invoices to recipients outside the e-Fatura system. The practical conclusion for your software: if you are an e-Fatura user, it has to issue both invoice types. Even if you are not in scope today, designing for both saves a rewrite when you join later.

Ways to connect: GİB portal, private integrator or direct integration

The GİB portal

GİB offers a web interface where invoices are created one by one, by hand. It can be enough for a business that issues few invoices, but it is not built for software integration and offers no official API for sending invoices from your own systems. If invoices should come out of your online store or ERP automatically, the portal alone will not do it.

A private integrator (özel entegratör)

Private integrators are companies authorised by GİB to issue, transmit and store e-documents on behalf of their customers; GİB publishes the list of authorised providers. Most expose SOAP or REST web services for sending invoices, checking status, listing incoming invoices, looking up taxpayers and fetching PDF renderings. Some expect a finished UBL-TR XML, others accept their own data format and generate the XML for you. For businesses that want invoicing driven by software, this is the most common route.

Direct integration with GİB

Here a company connects its own IT systems straight to GİB. It requires an application, a test process and meeting GİB's technical and information security conditions, and it puts the financial seal (mali mühür), document storage and uptime entirely on your side. It usually suits very high-volume businesses with a strong in-house IT team.

To be clear about our role: BernSoftware is not a private integrator and does not transmit documents to GİB. We build the software layer between your chosen integrator's API and your online store, marketplace connections, B2B portal and ERP. Our e-invoice integration page describes that work in detail.

UBL-TR: the format underneath

e-Fatura, e-Arşiv and e-İrsaliye documents are XML files in UBL-TR, the Turkish customisation of the international Universal Business Language standard. GİB defines the required fields and rules in its guides and validates documents against schema and schematron rules; a document that fails is rejected. On the software side, the points that matter most are:

• ETTN: every document carries a universally unique identifier in UUID format. Generate it once, store it with the order and reuse it on retries; that helps stop a dropped connection from producing a second invoice for the same order. Check in the test environment how your integrator handles a repeat submission with the same ETTN.
• Document number: it follows a fixed pattern of series, year and sequence and runs in order within a series. Decide early whether the integrator or the ERP assigns it.
• Invoice type and scenario: types such as sale, return, withholding and exemption, plus the scenario, are part of the document.
• Tax and exemption codes: tax types, withholding and exemption reasons are expressed with code lists published by GİB, and the tax setup in your ERP or store must map to them correctly.
• Rendering: the PDF or on-screen view comes from an XSLT template attached to the document. The XML is the legal document; the PDF is only a view of it.

Taxpayer lookup: e-Fatura or e-Arşiv?

Before an invoice is issued, the system checks whether the buyer is registered for e-Fatura. GİB publishes the list of registered users, and integrators offer lookup services by tax number or national ID number. The usual flow:

1. Take the buyer's tax number or national ID from the order.
2. Look it up through the integrator or a current copy of the registered user list.
3. If the buyer is registered, issue an e-Fatura to their mailbox alias. Some companies have more than one alias, so pick the right one.
4. If not, issue an e-Arşiv invoice and deliver it by email or link.

A common mistake is downloading the list once and caching it for weeks. Businesses register all the time, so look up as close to invoicing as you can, or refresh the cache often. e-İrsaliye has its own separate list of registered users.

Basic and commercial invoice scenarios

An e-Fatura is sent under one of two main scenarios, and the choice changes which states your software has to track:

• Basic invoice (temel fatura): the process ends when the invoice reaches the buyer's mailbox. The buyer cannot accept or reject it inside the system; objections go through the other channels defined in the legislation.
• Commercial invoice (ticari fatura): the buyer can send an acceptance or rejection through the system within the period set by the legislation, and your software needs to pick up that response and update the invoice status.

The issuer picks the scenario, usually based on the trading relationship and accounting preferences. The distinction only applies to e-Fatura; an e-Arşiv recipient cannot respond through the system. Special cases such as exports have scenarios of their own.

Where invoices originate

Online store

In a store selling to consumers, most invoices will be e-Arşiv invoices; when a business customer enters tax details, the lookup may call for an e-Fatura instead. Agree with your accountant whether the invoice is issued when payment is confirmed or when the order ships. When that moment comes, the order goes into a queue, the invoice is sent to the integrator, and the resulting PDF and link are emailed to the customer and shown in their account. For online sales, the e-Arşiv invoice must also carry extra details such as the website address, payment method and date, shipping date and carrier. Our ecommerce development page shows how payments, shipping and invoicing are designed together.

Marketplaces

When you sell on Trendyol, Hepsiburada or Amazon, you as the seller invoice the buyer. Orders are pulled through the marketplace's seller API, the invoice is issued, and it is attached to the order in whatever form the marketplace supports, such as an invoice link or file. The commission and service invoices the marketplace sends you are incoming invoices that need to land on the right accounts. Selling on several marketplaces is easier when orders and invoices meet in one place. Our Trendyol, Hepsiburada and Amazon integration guide covers the marketplace side, and our marketplace integration page describes the service.

B2B orders

Dealers and business customers are often registered for e-Fatura, so B2B ordering leans on e-Fatura, plus e-İrsaliye for shipments when both sides are registered for it. The order comes in through the portal, is approved in the ERP, and the dispatch note and then the invoice are issued at shipping. Dealers who can see their own invoices and dispatch notes in the portal call head office less often. We cover the portal side in our B2B ordering portal article.

ERP

Widely used ERPs such as Logo, Mikro, Netsis and SAP offer e-document modules or integrator connectors, with coverage varying by product and version. In that setup the store or portal does not invoice by itself: it passes the order to the ERP, the ERP issues the invoice, and the result (number, ETTN and PDF link) comes back. The alternative is issuing through the integrator's API and posting the invoice to the ERP as an accounting entry. Both work, as long as each order is invoiced by exactly one system and it is clear which system uses which number series. Our article on ERP integration methods covers the connection options, and our ERP integration page describes the service.

Handling incoming invoices

Integration is not only about outgoing invoices. Incoming e-Fatura invoices from suppliers, marketplaces and service providers land in your integrator inbox. Instead of downloading them and retyping them into the ERP, you can set up a flow like this:

• New incoming invoices are pulled from the integrator's API on a schedule.
• The sender's tax number is matched to a supplier account, and the lines to a purchase order or dispatch note.
• Matched invoices go to approval; the rest go to a review list.
• For commercial-scenario invoices, the accept or reject decision is made in time and sent back through the system.
• Incoming e-İrsaliye dispatch notes can be answered with a receipt response stating the quantities received.

This cuts manual entry for purchasing and accounting and stops the same invoice from being booked twice.

Cancellations, rejections and returns

• e-Fatura: once delivered, it cannot be deleted from the system. Under the commercial scenario the buyer can reject it; under the basic scenario, cancellations and objections follow the routes defined in the legislation.
• e-Arşiv: where the rules allow, it can be cancelled through the integrator, and the cancellation shows up in the report to GİB.
• Returns: a return is not a cancellation. Returned goods are recorded with a separate document such as a return invoice, and who issues it depends on the buyer, for example whether it is a business or a consumer.

Your software should track each document's state separately: queued, sent, delivered, accepted, rejected, cancelled or failed. Which document to issue in each case is an accounting decision, not a technical one, so agree it with your accountant.

Archiving

e-Fatura and e-Arşiv invoices must be kept electronically for the legal retention period and produced on request; a PDF or printout does not replace the XML. Integrators usually offer storage, but it is still good practice to keep each invoice's ETTN, number, status and XML in your own system, so you can find a document quickly when you change integrator, face an audit or a customer asks for an old invoice. e-Arşiv invoices can contain personal data such as names, addresses, national ID numbers and contact details, so access should be restricted in line with KVKK, Turkey's data protection law.

Testing in the integrator's test environment

Most integrators provide a test environment and test credentials separate from production. Testing in production means sending a valid invoice to a real buyer, so run the whole flow in the test environment first. At a minimum, test:

• An e-Fatura to a registered buyer and an e-Arşiv invoice to an unregistered one
• Mixed VAT rates, discounts, rounding and foreign currency invoices
• Withholding, exempt and return invoices
• Commercial-scenario accept and reject responses, and e-Arşiv cancellation
• Queuing and retrying when the integrator is unreachable
• Blocking a second invoice for the same order
• Edge cases such as Turkish characters, long product names and missing address details

Reviewing the test results with your accountant is a practical way to catch tax code errors before go-live.

Common e-invoicing mistakes

1. Deciding from a stale taxpayer list: a buyer who has just registered must receive an e-Fatura, not an e-Arşiv invoice.
2. Invoicing the same order from two places: if both the store and the ERP can invoice the same order, or two systems share one number series, duplicates and numbering collisions follow. Make one system responsible for each order's invoice, and give each invoicing system its own series.
3. Ignoring rounding: VAT calculated per line and per document can differ, so the store, the ERP and the invoice must use the same rule.
4. Treating the PDF as the invoice: the XML is the legal document; keeping only PDFs is not enough.
5. Not tracking status: if nobody checks whether an invoice was delivered or rejected, problems surface only when the customer calls.
6. Swallowing errors: integrator error messages belong on a dashboard with someone notified.
7. Leaving tax code mapping until last: agree exemption and withholding codes with accounting before go-live.

Setting up e-invoicing in Turkey step by step

1. Map what you have: which documents you issue, from which systems and in what volume.
2. Pin down the integrator and its API: sending, status checks, incoming invoices, taxpayer lookup and cancellation.
3. Choose a single source: which system invoices each order, and who manages the number series.
4. Agree the mappings: tax codes, units, customer and product codes, together with accounting.
5. Build the plumbing: a queue, retries, status tracking and an error dashboard.
6. Test, then go live in a controlled way: run every scenario in the test environment before switching to production.

BernSoftware builds online stores, B2B portals and ERP connections and wires them to the private integrator you choose. To plan your e-Fatura, e-Arşiv and e-İrsaliye flow, visit our e-invoice integration page, fill in the project planner or get in touch. Once the scope is clear, we share a transparent quote and a clear timeline.