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
- Payment transactions are carried out via the Ödeal POS
- The invoice is generated by the custom integrator
- 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
| Topic | Detail |
|---|---|
| Financial Seal | Not required under VUK507 |
| Operator Organization | Ödeal must be selected in the digital tax office |
| Application | Selecting the operator organization is sufficient for the application |
HR Service Requirements
Mandatory IntegrationService 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
- 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.
- Ödeal stores the application with the status
APPLIED. - Ödeal periodically calls the checkGMO service for
APPLIEDapplications. - If the GİB code in the checkGMO response is
1300, the application becomesAPPROVED; if the cancellation flag istrue, it becomesCANCELLED. In all other cases the application staysAPPLIEDand 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).
| Service | Endpoint | Method | Purpose |
|---|---|---|---|
| addGMO | /SendHR | POST | Starts the taxpayer's user activation notification to GİB |
| checkGMO | /GetHR/{identifier} | GET | Returns the taxpayer's e-Invoice / e-Archive application status |
| CancelHR (optional) | /CancelHR | POST | Deactivates 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.
| Field | Type | Required | Purpose |
|---|---|---|---|
TaxNumber | string | Required | The taxpayer's tax ID (VKN, 10 digits) or national ID (TCKN, 11 digits). The GİB notification is made on behalf of this number. |
Name | string | Required | Full name for an individual, title for a company. |
AddressInfo | object | Required | The taxpayer's address and contact information (fields below). |
AddressInfo.Address | string | Required | Street address, excluding province and district. |
AddressInfo.Country | string | Required | Country. Ödeal always sends Türkiye. |
AddressInfo.City | string | Required | Province. |
AddressInfo.District | string | Required | District. |
AddressInfo.PostalCode | string | Optional | Postal code. Ödeal sends it empty. |
AddressInfo.PhoneNumber | string | Required | Mobile phone; 10 digits without the leading 0 (5XXXXXXXXX). |
AddressInfo.Fax | string | Optional | Fax. Ödeal sends it empty. |
AddressInfo.Email | string | Required | The taxpayer's e-mail address. |
AddressInfo.WebSite | string | Optional | Website. Ödeal sends it empty. |
AddressInfo.TaxOffice | string | Required | Tax office name. |
EInvoiceSendingUnit | string | Required | The 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. |
EInvoicePostBox | string | Optional | The 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):
{
"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.
"Submission queued"Error (HTTP 4xx / 5xx): The body is the object below.
| Field | Type | Required | Purpose |
|---|---|---|---|
Message | string | Required | General description of the error. |
Errors | array | Required | Error items; contains at least one item. |
Errors[].Code | integer | Required | The integrator's error code. |
Errors[].Description | string | Required | Short description of the error. |
Errors[].Detail | string | Optional | Details; if GİB returned a message, it is passed here verbatim. |
{
"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.
| Parameter | Location | Type | Required | Purpose |
|---|---|---|---|---|
identifier | path | string | Required | The 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.
| Field | Type | Required | Purpose |
|---|---|---|---|
TaxNumber | string | Required | The taxpayer's VKN or TCKN. |
Name | string | Optional | The taxpayer's full name or title. |
UUID | string | Optional | The record's unique ID at the integrator. |
GIBCode | string | Required | GİB operation result code. 1300 = completed successfully. |
GIBDescription | string | Optional | GİB result description; on failure the GİB message is passed verbatim. |
GIBDate | datetime | Required | GİB operation date. Used to pick the most recent record within the same UserOption + Alias pair. |
CreationDateTime | datetime | Optional | When the record was created at the integrator. |
IsCancel | boolean | Required | false = activation, true = deactivation (alias cancellation). |
UserOption | string | Required | Application type: EFATURA or EARSIV. |
Alias | string | Required (e-Invoice) | Which alias the record belongs to: GB (sender unit) or PK (post box). null for e-Archive records. |
AliasValue | string | Required (e-Invoice) | The value of the activated or deactivated alias (e.g. urn:mail:[email protected]). null for e-Archive records. |
[
{
"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 = true | CANCELLED (deactivation) |
IsCancel = false and GIBCode = "1300" | APPROVED (activation) |
| Other codes, empty array or error | Stays 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.
| Field | Type | Required | Purpose |
|---|---|---|---|
Identifier | string | Required | The VKN or TCKN of the taxpayer to be deactivated (the TaxNumber in addGMO). |
CancelType | string | Required | Deactivation 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)
{
"Identifier": "11111111111",
"CancelType": "ALL"
}Example: PK deactivation only
{
"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) orGIBDescription(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.
UserOptionmust indicate the type, and for e-Invoice recordsAliasmust indicate GB/PK. Records whose type cannot be determined are ignored by Ödeal. - Populate the
GIBDatefield. When there are multiple records of the same type, the most recent one is selected based on this field. - Use
1300as 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
Errorsarray. - 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.
Related Resources
⚠️ Important Reminder
This documentation is prepared for the integration of custom integrator companies with Ödeal. For general integration information, visit the Main Documentation page.

