Skip to content

Custom Integrator HR Operations ​

A comprehensive guide for custom integrator companies for e-invoice and e-archive invoice integration with Ödeal

Frequently Asked Questions

On this page you can find answers to the questions we most frequently encounter during the custom integrator integration process.

E-Invoice Integration with Ödeal ​

Integration Process ​

Integration Operating Model

Based on the integration documentation shared by the custom integrator, all integration work is carried out by Ödeal.

Process Flow

  1. Payment transactions are carried out via the Ödeal POS
  2. The invoice is generated by the custom integrator
  3. The invoice is sent to GİB and to its recipient

Merchant GİB Operations ​

E-Invoice Activation and Deactivation ​

Custom Integrator Responsibility

Activation and deactivation of e-invoice and e-archive invoicing for the merchant is handled by the custom integrator.

Important Information

TopicDetail
Financial SealNot required under VUK507
Operator OrganizationÖdeal must be selected in the digital tax office
ApplicationSelecting the operator organization is sufficient for the application

HR Service Requirements ​

Mandatory Integration
Service Details

The custom integrator company needs to provide a service to forward the merchant e-invoice activation requests sent by Ödeal to GİB.

Service Characteristics

  • JSON (REST) service; fields compliant with the HR Service Specification below
  • Automatic submission to GİB
  • Real-time request processing

HR Service Specification ​

Ödeal expects two mandatory services from the custom integrator: addGMO, which registers the merchant with GİB as an e-Invoice / e-Archive taxpayer, and checkGMO, which queries the result of that application. The CancelHR service for deactivation is optional.

Flow ​

  1. Once the merchant registration is complete, Ödeal calls the integrator's addGMO service. The integrator queues the request and submits the user activation notification to GİB.
  2. Ödeal stores the application with the status APPLIED.
  3. Ödeal periodically calls the checkGMO service for APPLIED applications.
  4. If the GİB code in the checkGMO response is 1300, the application becomes APPROVED; if the cancellation flag is true, it becomes CANCELLED. In all other cases the application stays APPLIED and polling continues.

When the merchant's service ends, Ödeal requests the e-Invoice / e-Archive deactivation via the optional CancelHR service. The result of the deactivation is also tracked with checkGMO (a record with IsCancel = true).

ServiceEndpointMethodPurpose
addGMO/SendHRPOSTStarts the taxpayer's user activation notification to GİB
checkGMO/GetHR/{identifier}GETReturns the taxpayer's e-Invoice / e-Archive application status
CancelHR (optional)/CancelHRPOSTDeactivates the merchant's e-Invoice / e-Archive services under VUK 507

General Rules

  • Authentication: Every request carries the Authorization: Bearer <API key> header. The API key is shared with Ödeal separately by the integrator.
  • Data format: Requests and responses are application/json, UTF-8 encoded. Dates are ISO 8601 (2026-11-04T23:21:10).

addGMO — Request ​

POST /SendHR · The taxpayer's identity, title, address and alias information is sent in the body.

FieldTypeRequiredPurpose
TaxNumberstringRequiredThe taxpayer's tax ID (VKN, 10 digits) or national ID (TCKN, 11 digits). The GİB notification is made on behalf of this number.
NamestringRequiredFull name for an individual, title for a company.
AddressInfoobjectRequiredThe taxpayer's address and contact information (fields below).
AddressInfo.AddressstringRequiredStreet address, excluding province and district.
AddressInfo.CountrystringRequiredCountry. Ödeal always sends Türkiye.
AddressInfo.CitystringRequiredProvince.
AddressInfo.DistrictstringRequiredDistrict.
AddressInfo.PostalCodestringOptionalPostal code. Ödeal sends it empty.
AddressInfo.PhoneNumberstringRequiredMobile phone; 10 digits without the leading 0 (5XXXXXXXXX).
AddressInfo.FaxstringOptionalFax. Ödeal sends it empty.
AddressInfo.EmailstringRequiredThe taxpayer's e-mail address.
AddressInfo.WebSitestringOptionalWebsite. Ödeal sends it empty.
AddressInfo.TaxOfficestringRequiredTax office name.
EInvoiceSendingUnitstringRequiredThe sender unit (GB) alias the taxpayer will use at GİB. The alias format belongs to the integrator and is shared with Ödeal before the integration.
EInvoicePostBoxstringOptionalThe post box (PK) alias the taxpayer will use at GİB. Not sent if only the GB alias is to be activated. The alias format belongs to the integrator and is shared with Ödeal before the integration.

Sample request (personal data is illustrative):

json
{
  "TaxNumber": "11111111111",
  "Name": "AYŞE YILMAZ",
  "AddressInfo": {
    "Address": "Caferağa Mah. Örnek Sok. No:1",
    "Country": "Türkiye",
    "City": "İstanbul",
    "District": "Kadıköy",
    "PostalCode": "",
    "PhoneNumber": "5321234567",
    "Fax": "",
    "Email": "[email protected]",
    "WebSite": "",
    "TaxOffice": "KADIKÖY"
  },
  "EInvoiceSendingUnit": "urn:mail:[email protected]",
  "EInvoicePostBox": "urn:mail:[email protected]"
}

addGMO — Response ​

A successful response only indicates that the request has been queued; the GİB result is obtained with checkGMO.

Success (HTTP 200): The body is plain text.

json
"Submission queued"

Error (HTTP 4xx / 5xx): The body is the object below.

FieldTypeRequiredPurpose
MessagestringRequiredGeneral description of the error.
ErrorsarrayRequiredError items; contains at least one item.
Errors[].CodeintegerRequiredThe integrator's error code.
Errors[].DescriptionstringRequiredShort description of the error.
Errors[].DetailstringOptionalDetails; if GİB returned a message, it is passed here verbatim.
json
{
  "Message": "User could not be added",
  "Errors": [
    {
      "Code": 400,
      "Description": "GİB user activation notification rejected",
      "Detail": "Özel entegratörün mükellef adına VUK 507 kapsamında kullanıcı açma bildirimi yetkisi yoktur."
    }
  ]
}

If the HTTP status is not 2xx or Errors is populated in the body, Ödeal treats the application as failed and shows the error to the merchant. Returning the successful response as a JSON object ({"Success": true, "Message": "..."}) is also accepted.

checkGMO — Request ​

GET /GetHR/{identifier} · No body.

ParameterLocationTypeRequiredPurpose
identifierpathstringRequiredThe VKN or TCKN of the taxpayer whose application is queried (the TaxNumber in addGMO).

checkGMO — Response ​

Success (HTTP 200): The body is an array of the taxpayer's application records. Each activation and deactivation is a separate record. For e-Invoice records, the Alias field indicates whether the record is GB or PK; if only GB was activated, no PK record is returned. If there is more than one record for the same UserOption + Alias pair, Ödeal uses the one with the most recent GIBDate.

FieldTypeRequiredPurpose
TaxNumberstringRequiredThe taxpayer's VKN or TCKN.
NamestringOptionalThe taxpayer's full name or title.
UUIDstringOptionalThe record's unique ID at the integrator.
GIBCodestringRequiredGİB operation result code. 1300 = completed successfully.
GIBDescriptionstringOptionalGİB result description; on failure the GİB message is passed verbatim.
GIBDatedatetimeRequiredGİB operation date. Used to pick the most recent record within the same UserOption + Alias pair.
CreationDateTimedatetimeOptionalWhen the record was created at the integrator.
IsCancelbooleanRequiredfalse = activation, true = deactivation (alias cancellation).
UserOptionstringRequiredApplication type: EFATURA or EARSIV.
AliasstringRequired (e-Invoice)Which alias the record belongs to: GB (sender unit) or PK (post box). null for e-Archive records.
AliasValuestringRequired (e-Invoice)The value of the activated or deactivated alias (e.g. urn:mail:[email protected]). null for e-Archive records.
json
[
  {
    "TaxNumber": "11111111111",
    "Name": "AYŞE YILMAZ",
    "UUID": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "GIBCode": "1300",
    "GIBDescription": "Completed successfully",
    "GIBDate": "2026-11-05T10:12:00",
    "CreationDateTime": "2026-11-04T23:21:10",
    "IsCancel": false,
    "UserOption": "EFATURA",
    "Alias": "GB",
    "AliasValue": "urn:mail:[email protected]"
  },
  {
    "TaxNumber": "11111111111",
    "Name": "AYŞE YILMAZ",
    "UUID": "4a7e1b2c-9d3f-4e6a-8b5c-1d2e3f4a5b6c",
    "GIBCode": "1300",
    "GIBDescription": "Completed successfully",
    "GIBDate": "2026-11-05T10:12:00",
    "CreationDateTime": "2026-11-04T23:21:10",
    "IsCancel": false,
    "UserOption": "EFATURA",
    "Alias": "PK",
    "AliasValue": "urn:mail:[email protected]"
  },
  {
    "TaxNumber": "11111111111",
    "Name": "AYŞE YILMAZ",
    "UUID": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "GIBCode": "1300",
    "GIBDescription": "Completed successfully",
    "GIBDate": "2026-11-20T09:30:00",
    "CreationDateTime": "2026-11-20T09:05:00",
    "IsCancel": true,
    "UserOption": "EFATURA",
    "Alias": "PK",
    "AliasValue": "urn:mail:[email protected]"
  },
  {
    "TaxNumber": "11111111111",
    "Name": "AYŞE YILMAZ",
    "UUID": "8b1d2e4f-6a7c-4d9e-b0f1-2c3d4e5f6a7b",
    "GIBCode": "1300",
    "GIBDescription": "Completed successfully",
    "GIBDate": "2026-11-05T10:12:00",
    "CreationDateTime": "2026-11-04T23:21:10",
    "IsCancel": false,
    "UserOption": "EARSIV",
    "Alias": null,
    "AliasValue": null
  }
]

In this example, the taxpayer's e-Invoice GB and PK aliases were activated on 5 November and the PK alias was deactivated on 20 November. Ödeal takes the most recent record for each pair: GB APPROVED, PK CANCELLED, e-Archive APPROVED. For a taxpayer with only GB activated, no PK records are returned at all.

Error (HTTP 4xx / 5xx): Same as the addGMO error structure (Message, Errors[]). Returning an empty array ([]) when no record is found is accepted.

Ödeal's status mapping

Value in the response (most recent record of the pair)Alias status at Ödeal
IsCancel = trueCANCELLED (deactivation)
IsCancel = false and GIBCode = "1300"APPROVED (activation)
Other codes, empty array or errorStays APPLIED, polling continues

CancelHR (Optional) — Request ​

POST /CancelHR · Starts the deactivation of the merchant's e-Invoice and e-Archive services activated under VUK 507.

Optional Method

If, according to the commercial agreement, deactivation (cancellation) will not be performed by Ödeal, the integrator does not need to develop this method.

FieldTypeRequiredPurpose
IdentifierstringRequiredThe VKN or TCKN of the taxpayer to be deactivated (the TaxNumber in addGMO).
CancelTypestringRequiredDeactivation scope. ALL: e-Invoice GB, e-Invoice PK and e-Archive services are all deactivated in a single request. PK: only the e-Invoice PK alias is deactivated; GB and e-Archive remain active.

Example: deactivation of all services (GB, PK and e-Archive)

json
{
  "Identifier": "11111111111",
  "CancelType": "ALL"
}

Example: PK deactivation only

json
{
  "Identifier": "11111111111",
  "CancelType": "PK"
}

CancelHR (Optional) — Response ​

The response structure is the same as addGMO: on success HTTP 200 and plain text ("Cancellation request queued"), on error HTTP 4xx / 5xx and a Message + Errors[] object. If CancelType is not sent or has a value other than ALL / PK, the request must be rejected with HTTP 400.

The GİB result of the deactivation is obtained with checkGMO; a separate record with IsCancel = true is returned for each deactivated service:

  • ALL: three records — EFATURA + GB, EFATURA + PK, EARSIV. If PK was never activated for the taxpayer, only the active services are deactivated and no PK record is returned.
  • PK: a single record — EFATURA + PK.

Expectations from the Integrator ​

  • Pass the GİB message through verbatim. On rejection, the text returned by GİB must appear unchanged in Errors[].Detail (addGMO) or GIBDescription (checkGMO). For example, on a VUK 507 authorization error we use this message to direct the merchant to "grant custom integrator authorization at GİB".
  • Separate e-Invoice and e-Archive records. checkGMO must return a separate record for each activation and deactivation. UserOption must indicate the type, and for e-Invoice records Alias must indicate GB/PK. Records whose type cannot be determined are ignored by Ödeal.
  • Populate the GIBDate field. When there are multiple records of the same type, the most recent one is selected based on this field.
  • Use 1300 as the success code. If a different success code is used, notify Ödeal before the integration.
  • Do not return 2xx on errors. A failed addGMO request must return HTTP 4xx / 5xx with an Errors array.
  • Provide a test environment. The test URL, test API key and a list of test VKN/TCKN numbers must be shared with Ödeal before the integration starts.

Integration Requirements ​

Required Steps ​

Integration Checklist

Custom Integrator Side

  • Share the integration documentation with Ödeal
  • Prepare the addGMO and checkGMO services (and optionally CancelHR) and provide the endpoint information
  • Manage the GİB e-invoice activation/deactivation processes

Merchant Side

  • Select Ödeal as the operator organization in the digital tax office
  • Complete the e-invoice application
  • Ensure VUK507 compliance

Ödeal Side

  • Develop the integration according to the custom integrator's documentation
  • Provide the POS device and payment infrastructure
  • Forward merchant requests to the custom integrator

Support and Contact ​

Need Help?

For Custom Integrator Companies

For technical matters or questions encountered during the integration process, you can contact the Ödeal technical support team.

For Merchants

For questions about e-invoice activation, deactivation, or the general process, you can contact your custom integrator company.



⚠️ Important Reminder

This documentation is prepared for the integration of custom integrator companies with Ödeal. For general integration information, visit the Main Documentation page.

Ödeal A.Ş.