Connecting Your Own Software to Turkish e-Invoicing
Business

Connecting Your Own Software to Turkish e-Invoicing

Portal, direct integration or a private integrator? The right route depends on your invoice volume, your software and who can keep the connection running.

Short answer

E-fatura entegrasyonu (e-invoice integration) means your own accounting, ERP or e-commerce software creates, sends and receives invoices in the UBL-TR format set by the Revenue Administration. You can do it through GİB's free portal, by connecting your system directly to GİB, or through a private integrator that GİB has authorised. Businesses that issue invoices from their own software usually choose a private integrator.

What is e-invoice integration, and how do you connect your own software to the Turkish Revenue Administration?

E-invoice integration (e-fatura entegrasyonu) means your own accounting, ERP or e-commerce software creates invoices electronically in the format set by the Revenue Administration (GİB), sends them and receives incoming ones. There are three routes: GİB's free portal, a direct integration that connects your software to the GİB system, or a private integrator (özel entegratör) that GİB has authorised. If you want your software to do the work, the second or third route is usually the relevant one.

Start with the basics. According to GİB's eBelge site, an e-invoice is an electronic document that carries the information the Tax Procedure Law (No. 213) requires on an invoice and has the same standing as a paper invoice. It travels from seller to buyer through a central platform run by GİB, and the data format is UBL-TR, an XML-based standard. Taxpayers registered in the e-invoice system must send and receive invoices for goods and services between themselves as e-invoices. For a buyer who is not registered, a paper invoice is issued or, if you are in the e-Arşiv (e-archive invoice) system, an e-Arşiv invoice.

So integration is really two separate decisions: which document type (e-invoice, e-Arşiv, e-waybill) and which connection route. Confirm with your accountant (mali müşavir) and GİB's current transition schedule which applications you must join, because scope changes through communiqués.

What is the difference between e-invoice, e-Arşiv and e-waybill, and which route fits?

All three are GİB eBelge applications, but they cover different documents and different recipients. The table compares document types and connection routes from an integration point of view. Knowing which ones your software must produce sets the scope of the build.

OptionWhat it is forWhat to watch in integration
e-FaturaRegistered taxpayer to registered taxpayerCheck whether the buyer is registered
e-Arşiv invoiceElectronic invoice to unregistered buyersSeparate guide and delivery rules
e-İrsaliye (e-waybill)Electronic delivery noteOnly groups named in communiqués
GİB portalFree web application, manual invoicingFile upload, not a software link
Private integratorSending via an authorised provider's systemYour software calls the integrator's service
Direct integrationYour system connects to GİB itselfNeeds a continuous 7/24 connection

The scope of e-Arşiv is described on GİB's e-Arşiv page: an authorised taxpayer issues e-invoices to registered buyers, and e-Arşiv invoices to unregistered buyers and to buyers who are not taxpayers; an e-Arşiv invoice is delivered on paper or electronically at the buyer's request. The e-waybill is mandatory only for certain sectors and taxpayer groups named in communiqués. Check GİB's transition schedule table to see whether it applies to you.

Portal, direct integration or private integrator: which one suits you?

GİB defines three methods of using the system and says plainly who each is for.

  • Portal: a free web application from GİB. The e-Fatura Portal is for users without the infrastructure to integrate. You can create invoices by hand in the portal, or prepare them in your own system in the format GİB specifies and upload them. It does not give your software a live connection.
  • Direct integration: the integration of your own IT system method is meant for taxpayers who can connect their system to GİB's and keep it connected 7/24. After the electronic application, and once TÜBİTAK - KamuSM has delivered the financial seal (mali mühür) certificate, you submit a BİS report and a test definition form.
  • Private integrator: special integration is for taxpayers with differing invoicing needs or large invoice volumes whose own infrastructure falls short. You send and receive invoices through the system of an institution that holds GİB's permission. The list of authorised institutions is published on the eBelge site, so check that a firm appears on it before you sign.

A practical rule: if invoices are produced in your ERP or your own software and using the portal by hand is not sustainable, most businesses connect to a private integrator's service. Direct integration means you take on connection reliability and certificate management yourself.

What steps do you follow to connect your software to e-invoicing?

Whichever route you pick, the technical work has similar parts. For direct integration you follow GİB's guides; with a private integrator you follow the integrator's API documentation. GİB's legislation and technical architecture page lists the integration guide, the envelope and system-response schemas, and the UBL-TR guides and package.

  1. Write down the scope. Which documents (e-invoice, e-Arşiv, e-waybill), which sources (ERP, web shop, subscription system) and roughly how many documents a month.
  2. Choose the route. Portal, private integrator or direct integration. Use the questions in the next section.
  3. Application and certificate. The direct route needs an electronic application and a financial seal certificate. With an integrator, ask about the application steps before you sign.
  4. Data mapping. Map the fields on your invoice to UBL-TR fields: party details, tax IDs, line items, VAT rates, exemption codes, currency. The mapping table becomes the main document for debugging.
  5. Buyer lookup. Before issuing, check whether the buyer is a registered e-invoice user and choose the document type accordingly. GİB publishes registered-user lists.
  6. Test environment. Try everything on test endpoints before real invoices. GİB has an e-Fatura Test Portal, and integrators have their own test environments.
  7. Status tracking. Pull the status of every sent invoice (accepted, rejected, error) back into your software and show it to the user.
  8. Retention. Confirm the retention period and method for issued and received invoices with your accountant.

Which questions should you ask when choosing an integrator or a direct connection?

The choice should be steered by more than a price list. Ask for quotes against the same scope, because every provider structures its items and units differently.

  • Is the firm on the private integrator list that GİB publishes?
  • Is the API documentation open, and which formats (UBL-TR XML, JSON) does it accept?
  • Is there a test environment you can use before real invoices?
  • Do error codes and rejection reasons come back clearly in the API response?
  • Can incoming invoices be imported into your software automatically?
  • If the contract ends, can you export the archived invoices?
  • How much of your software must change if you move to another integrator?

The last two questions are often forgotten. If integrator-specific fields are spread through your software, changing provider later becomes a new project. Keeping all integrator calls in one module reduces that risk.

Example: how does a distributor with its own order software proceed?

For example, take a hypothetical distributor that issues about 1,200 invoices a month from its own order software. Some customers are registered for e-invoicing; the rest are small traders and individuals. Using the portal by hand means re-entering data for every invoice, which at 1,200 documents a month is slow and error-prone.

The company chooses the private integrator route. The order software converts each approved order into UBL-TR fields and sends it to the integrator's service. If the buyer is registered, an e-invoice is issued; if not, an e-Arşiv invoice. The status of each document returns to the software. Documents rejected for a wrong tax ID land in an error queue, where an accounts clerk corrects and resends them.

The first week goes on scope and the mapping table. Then about 50 sample documents are tried in the test environment: a normal sale, a return, different VAT rates, an exempt sale, a foreign currency. On the first day of live invoicing the documents are checked by hand. These numbers only illustrate the logic; your own timeline depends on the source system and the document types.

What are the most common mistakes in e-invoice integration?

  • Not checking the buyer type. An e-invoice must go to a registered buyer as an e-invoice; choose the document type from the buyer lookup.
  • Not designing for failures. Without a queue, retries and alerts for rejected or unanswered documents, an invoice can disappear quietly.
  • Sending the same invoice twice. If you retry after a network error, store a unique ID for each document and block duplicate sends.
  • Leaving tax fields on defaults. VAT rates and exemptions must come out right line by line; test them together with your accountant.
  • Leaving the certificate without an owner. If nobody is responsible for the financial seal certificate's expiry and password, the connection can break one morning.
  • Writing integrator-specific code everywhere. Without a separate layer for integrator calls, switching provider gets expensive.

How Hatson Tech helps

Hatson Tech connects your existing accounting, ERP or e-commerce software to e-invoice and e-Arşiv flows as part of its custom software development service: scoping, the mapping table, the integrator connection, the error queue and status screens. The first meeting and discovery are free. We do not publish fixed prices, because cost depends on document types and source systems. On your tax obligations your accountant's view is what counts; we build the technical side.

If you are weighing up replacing an old system, see our application modernisation decision guide; if you want to process documents such as incoming invoices automatically, see our article on document processing automation.

Key takeaways

  • Treat integration as two decisions: which document type (e-invoice, e-Arşiv, e-waybill) and which connection route.
  • GİB offers three routes: a free portal, direct integration of your own system, and an authorised private integrator.
  • Most businesses that issue invoices from an ERP or their own software connect to a private integrator's service.
  • Map your invoice fields to UBL-TR, test on a test environment and bring every document's status back into your software.
  • Keep integrator calls in one module so that changing provider later does not become a new project.

Frequently asked questions

How is e-fatura entegrasyonu done?

First decide which documents you need (e-invoice, e-Arşiv, e-waybill) and which route you will use. Then map your invoice fields to UBL-TR, test on a test environment, handle rejections and bring each document's status back into your software.

Is a private integrator mandatory for e-invoicing?

No. GİB describes three methods: its free portal, integration of your own IT system, and a private integrator. A private integrator is meant for taxpayers whose own infrastructure is insufficient or who issue many invoices.

What is the difference between e-invoice and e-Arşiv invoice?

E-invoices go between taxpayers registered in the e-invoice system. An authorised taxpayer issues an e-Arşiv invoice to buyers who are not registered or are not taxpayers, and it is delivered on paper or electronically at the buyer's request.

What is UBL-TR?

UBL-TR is the XML-based format GİB adopted for e-invoices, built on the international UBL standard. Your software must produce invoice data in this format, directly or through an integrator.

Can I try the integration before issuing real invoices?

Yes. GİB runs an e-Fatura Test Portal and integrators usually offer their own test environments. Test normal sales, returns, different VAT rates and rejection cases before going live.

All articles