GİB Integration via a Private Integrator

An invoice on your screen has not reached GİB. Many teams assume their own software hands the e-document straight to the Turkish Revenue Administration (Gelir İdaresi Başkanlığı). That is not what GİB integration is. On the private-integrator path, a company cannot send the document from its own system directly to the administration. The record goes through a licensed private integrator. eLogo is one example of that kind of company.

The path is a straight line. The seller’s system prepares the invoice. The integrator checks the schema, completes the signature and sends the document to GİB. GİB delivers it to the side where the buyer is registered. Acceptance, rejection and every other status come back along the same path. This article explains those stops, and who does what at each one.

The document rules for e-invoice and e-waybill, the portal and direct integration are covered in a separate article. Here we open only the layer that GİB integration uses when a private integrator sits in the middle. The administration’s e-document gateway is ebelge.gib.gov.tr. The rules are published there.

Your own software does not hand the document to GİB

GİB owns the e-document regime and is the hub the documents pass through. It is not your accounting program and it is not your warehouse screen. A private integrator is not the administration either. It is a licensed company. Your software talks to that company’s service. The party that carries the document into the administration’s system is the integrator.

The split changes daily work. Pressing send does not mean the buyer can see the invoice. The button delivers the document to the integrator. Schema checks, the signature and routing sit between that delivery and acceptance by the administration. Those steps do not finish inside your ERP screen.

Direct integration is a separate authorization. On that path the company’s own information system connects to the administration. It is not the default of every project. It asks for a heavy authorization and a connection that stays up. The GİB integration we build for day-to-day work goes through a private integrator. The other article describes the direct path. This one does not write as if that authorization were already in place, and it does not claim a partnership with GİB.

The portal is a separate path as well. At low volume a document can be issued by hand on the administration’s screens. When the document is born from an order or a shipment, the private-integrator path keeps the record in your own system and still gets it to GİB.

Four stops from the seller to the buyer

GİB integration is read as four stops. The order does not change. Skipping a stop hides the place where the document is stuck.

The seller’s system. The invoice is born here. Seller and buyer identity, address, lines, quantity, unit, discount, tax and totals are your record. The document number and the date take their meaning here too. This stop is not GİB. It is your ERP, your shipping software, or the layer between them.
The private integrator. The prepared document goes to the integrator’s service. The integrator checks the schema, applies the signature and sends. The document is not with the buyer yet. Arriving at the service does not mean the administration has received the document.
GİB. The administration processes the incoming document in the e-document system and routes it to the side where the buyer is registered. The buyer may sit with a private integrator or on the portal. Routing is not your software’s job.
The buyer. The document becomes visible in the buyer’s system. On a commercial invoice the buyer can accept or reject. A basic invoice does not wait for that response. Whether a response is required depends on the scenario. What matters here is that the response also returns down the same chain.

The four stops should not look like a single confirmation on a single screen. The sentence the operator sees should say which stop the document is on. Otherwise finance closes the invoice, the warehouse finishes the shipment, and the document is still waiting at the integrator for a missing field.

The buyer’s side is not managed from inside your integrator screen. GİB delivers the document to the system the buyer is connected to. Your record reads the result of that delivery from your own integrator. A sales invoice follows the same order: the record is finalized with you, the integrator finishes the schema and the signature, GİB routes it to the buyer, and the result returns to the same record.

Status comes back along the same path

The outbound trip is not one way. The result at GİB returns to the seller’s system through the integrator’s status service. The return is written beside the invoice. It is not left in a separate mailbox.

The meanings to track are short. The names change with the integrator’s contract. The meaning should not.

Queued. The document is ready on your side. It has not been delivered to the integrator yet, or the delivery attempt is still running.
At the integrator. The document has reached the service. The schema or the signature may still be unfinished.
Returned. The document did not go to the administration because of the schema, the signature or a field. The reason is visible as a sentence.
Reached GİB. The administration has received the document. That does not mean the buyer has accepted it.
Delivered to the buyer. The document is in a visible state in the buyer’s system.
Response. On a commercial invoice, acceptance or rejection comes back the same way. A basic invoice has no such step.

If the network drops, the record stays local. A retry after a timeout must not create the same invoice a second time. Every send has an operation key. The key lives in your software. The envelope or document identifier the integrator returns is matched to that key. Without the match, the status is written onto the wrong invoice.

The work the private integrator takes on

The private integrator takes on four jobs. Burying those four jobs inside the ERP puts GİB integration on the wrong layer.

Schema. The document has to follow the form the administration publishes. A missing identity, a unit that does not fit, a tax breakdown that does not add up, or totals that disagree are caught at the integrator. The integrator runs the check and returns a result that can be read. Your software shows that result as a sentence to the person who produced the invoice.

Signature. Completing the document with a financial seal or an electronic signature is the integrator’s job. Your own screen does not manage the signing device. The fact that it was signed is a result that comes back from the integrator. Until the signature is complete, the document has not gone to GİB.

Sending. Forwarding the signed document to the administration’s system belongs to the integrator. Your service does not call that step against GİB. You deliver the document to the integrator. The moment of delivery and the moment of acceptance by the administration are written separately.

Status. The integrator exposes the status of the document and, when there is one, the buyer’s response. Your software asks for that status on a set interval and writes the result beside the invoice. The query lives at the integrator. Reading the result and applying it to the right record is yours.

eLogo is one integrator that provides these four jobs. With another licensed integrator the service names and the fields change. The four jobs stay the same.

Invoice data, matching and errors stay with the company

The integrator does not issue the invoice in your place. The record to be issued is born with you. On a GİB integration, three pieces of work stay inside the company.

Invoice data. Seller and buyer, address, lines, quantity, unit, discount, tax and totals are your master data. If the shipment has closed, the quantity comes from that closed shipment. The same number is not typed again into a second list. A missing tax identity or an empty unit should stop on your screen before the document goes to the integrator. Waiting for a schema error holds up the shift. An early check does not replace the integrator’s schema job. It catches the same gap before the document leaves.

Matching. Every outbound document has an owner on your side. An order, a shipment or an accounting record can be that owner. The identifier that comes back from the integrator is matched to this owner. If the match is not written, the status floats. An incoming e-invoice needs the same work. The document the other party issued should stand next to your purchase record. If the amount or the identity does not agree, the match stays open. An open line is not treated as paid.

Errors. A schema error, a timeout and a buyer rejection are three different states. A schema error means correcting the document and sending again with the same operation key. A timeout means not opening a second document before asking whether the first one arrived. A rejection is the buyer’s commercial response, and it is a decision to issue a new invoice. Putting all three in the same error box makes the team do the wrong job.

These three jobs are not finished on the private integrator’s screen. The meaning lives in your order and in your shipment. The integrator does not know that meaning. The administration does not know it either. Matching and error handling therefore stay in the company’s own software.

The layer that builds the GİB integration

GİB integration is not placing two programs side by side. It is the layer between the seller’s system and the private integrator. softhan builds that layer. The layer takes the invoice data from your record, turns it into the call the integrator expects, writes the returning status onto the same record and shows the error to the team that should see it.

In our e-invoice and e-document integration service, the document is produced from your ERP or shipping record, delivered to the integrator and tracked on the same record. The accounting or shipping software you already run stays in place. A new program is not required.

The flow we have delivered with this layer is the e-invoice. An e-waybill can sit on the same backbone. Which document types enter a project is written at the start. We do not treat a document outside that scope as delivered. The dispatch rules for the e-waybill are in the article linked above. This page does not retell those rules, and it does not assume a delivered e-waybill engagement.

On an e-invoice engagement that works with eLogo, we wrote the layer that connects the seller’s record to the integrator. The scope was the e-invoice. The project page describes that work. With another licensed integrator the same split applies. You keep the data and the matching. The integrator keeps schema, signature, sending and status. We stand between the two.

softhan is not a partner of GİB or of eLogo. We write the software that lets your system speak to a licensed integrator’s service. Brand names belong to their owners. The authorization sits in the integrator’s own relationship with the administration. We do not take that relationship on.

Decisions written before the work starts

The layer becomes clear in four decisions, before any code.

The path. Private integrator, portal or direct integration. This article describes the first. If the path changes, the scope changes with it.
The integrator. eLogo or another licensed integrator. The service contract and the test environment come with this decision. A live document is not the place for the first trial.
The document type. The e-invoice is the first link. Another e-document is added to the same layer as its own piece of work. A document that was not added is not shown on the screen as if it were there.
Who sees the error. Finance, shipping, or both. An error nobody sees is treated as finished. The sentence on the screen should say the job to do, not a service code.

These decisions come before the choice of tools. The document should go once, the status should be written on the right record, and the error should be visible to the team that should act. The system you already have stays in place.

Frequently Asked Questions

Can our own software send an invoice straight to GİB?

Not on the private-integrator path. The document goes first to a licensed integrator. The integrator completes the schema and the signature, then forwards it to GİB. Direct integration is a separate authorization, and it is not the flow this article describes.

How is the integrator’s work split from the company’s software?

The integrator takes on the schema check, the signature, the send to GİB and the status. The company’s software produces the invoice data, matches the document to an order or a shipment, and shows the error to the team that should see it.

Can the same layer be built with an integrator other than eLogo?

Yes. eLogo is one of the private integrators we have used. With another licensed integrator the service names change. Schema, signature, sending and status stay in the same split of work.

How does the document’s status return to the seller?

The result at GİB is reflected on the integrator’s status service. Your software queries that result and writes it beside the invoice. The buyer’s acceptance or rejection comes back along the same path.

Facing a similar challenge? Tell us about your project and we will get back to you within one business day.

All product and company names are trademarks of their respective owners; softhan is not an authorized representative or partner of these companies.