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.
| Option | What it is for | What to watch in integration |
|---|---|---|
| e-Fatura | Registered taxpayer to registered taxpayer | Check whether the buyer is registered |
| e-Arşiv invoice | Electronic invoice to unregistered buyers | Separate guide and delivery rules |
| e-İrsaliye (e-waybill) | Electronic delivery note | Only groups named in communiqués |
| GİB portal | Free web application, manual invoicing | File upload, not a software link |
| Private integrator | Sending via an authorised provider's system | Your software calls the integrator's service |
| Direct integration | Your system connects to GİB itself | Needs 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.
- 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.
- Choose the route. Portal, private integrator or direct integration. Use the questions in the next section.
- 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.
- 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.
- 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.
- 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.
- Status tracking. Pull the status of every sent invoice (accepted, rejected, error) back into your software and show it to the user.
- 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.