# MYSOFT e-Fatura Oluşturma (Fatura İşlemleri)

MYSOFT EDocument API üzerinden fatura oluşturma, taslak yönetimi ve GİB Portal gönderim işlemlerinin referans dokümantasyonu.

> **Kaynak:** [MYSOFT API Dokümantasyonu](https://edocumentapi.mysoft.com.tr/index.html#tag/Fatura-Islemleri)

---

## İçindekiler

- [Base URL](#base-url)
- [Kimlik Doğrulama (OAuth 2.0)](#kimlik-dogrulama-oauth-20)
- [Ortak Yanıt Formatı](#orttak-yant-formati)
- [Endpoint Listesi](#endpoint-listesi)
- [1. Portal Fatura Ekleme (Yeni) — `invoiceDraftNew`](#1-portal-fatura-ekleme-yeni--invoicedraftnew)
- [2. Portal Fatura Ekleme — `invoiceDraft`](#2-portal-fatura-ekleme--invoicedraft)
- [3. Fatura Not Ekleme — `invoiceNote`](#3-fatura-not-ekleme--invoicenote)
- [4. Fatura İlaç/Tıbbi Cihaz — `invoiceDrugAndMedical`](#4-fatura-ilactibbi-ciha--invoicedrugandmedical)
- [5. Taslak Fatura Silme — `deleteInvoiceDraft`](#5-taslak-fatura-silme--deleteinvoicedraft)
- [6. Taslak Fatura İmzala & Gönder — `invoiceDraftSignAndSend`](#6-taslak-fatura-imzala--gnder--invoicedraftsignandsend)
- [7. Fatura Sorgulama (Tekil) — `getInvoiceModel`](#7-fatura-sorgulama-tekil--getinvoicemodel)
- [8. Fatura Listesi — `getInvoiceModelList`](#8-fatura-listesi--getinvoicemodellist)
- [9. Fatura Listesi (Başlıklı) — `getInvoiceWithHeaderInfoList`](#9-fatura-listesi-baslikli--getinvoicewithheaderinfolist)
- [10. Taslak Fatura PDF — `getInvoiceDraftPdfAsZip`](#10-taslak-fatura-pdf--getinvoicedraftpdfaszip)
- [11. GİB Portal'a Fatura Gönderme — `invoiceDraftSendToGib`](#11-gib-portala-fatura-gnderme--invoicedraftsendtogib)
- [12. GİB Portal'a Fatura Gönderme (XML) — `invoiceDraftSendToGibUblXml`](#12-gib-portala-fatura-gnderme-xml--invoicedraftsendtogibublxml)
- [13–18. GİB Portal Diğer İşlemler](#13-18-gib-portal-dier-islemler)
- [Ek: Cari Hesap Modeli (AccountModel)](#ek-cari-hesap-modeli-accountmodel)
- [Ek: Fatura Kalem Modeli (InvoiceDetailModel)](#ek-fatura-kalem-modeli-invoicedetailmodel)
- [Ek: PHP (Laravel) Örnek](#ek-php-laravel-ornek)

---

## Base URL

| Ortam      | URL                                  |
| ---------- | ------------------------------------ |
| Production | `https://edocumentapi.mysoft.com.tr` |
| Test       | `https://edocumentapi.mytest.tr`     |

Tüm endpoint'ler `/api/...` prefix'i ile başlar.

---

## Kimlik Doğrulama (OAuth 2.0)

API'de kimlik doğrulama **OAuth 2.0** altyapısı ile yapılmaktadır. Herhangi bir API metodu çağrılmadan önce bir **access token** oluşturulmalı ve isteklere `Authorization` başlığı eklenmelidir.

### Token Oluşturma

**İstek:**

```
POST https://edocumentapi.mytest.tr/oauth/token
Content-Type: application/x-www-form-urlencoded
```

| Parametre       | Değer / Açıklama                                           |
| --------------- | ---------------------------------------------------------- |
| `grant_type`    | `client_credentials`                                       |
| `client_id`     | Mysoft Portal → **Erişim Anahtarı** menüsünden oluşturulur |
| `client_secret` | Mysoft Portal → **Erişim Anahtarı** menüsünden oluşturulur |

**Yanıt:**

```json
{
    "access_token": "TRqkQO1Dg0sHtlC8I6...",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "..."
}
```

### API İsteklerinde Kullanımı

Token alındıktan sonra, her API isteğine aşağıdaki başlık eklenir:

```
Authorization: Bearer {access_token}
Content-Type: application/json
```

---

## Ortak Yanıt Formatı

Tüm endpoint'ler aşağıdaki zarf (envelope) yapısında yanıt döner:

```json
{
    "data": "<payload, başarısızlıkta false veya null>",
    "succeed": true,
    "message": "",
    "errorCode": null,
    "afterValue": 0
}
```

| Alan         | Tip            | Açıklama                                              |
| ------------ | -------------- | ----------------------------------------------------- |
| `data`       | mixed          | Yanıt yükü. Hata durumunda `false` / `null`.          |
| `succeed`    | boolean        | `true` ise istek başarılı.                            |
| `message`    | string \| null | Durum/hata mesajı.                                    |
| `errorCode`  | string \| null | Hata kodu.                                            |
| `afterValue` | integer        | Sayfalama imleci (bir sonraki sayfa için kullanılır). |

---

## Endpoint Listesi

Tüm **Fatura İşlemleri** tag'i altındaki endpoint'ler:

| #   | Method | Path                                          | operationId                              | Açıklama                                 |
| --- | ------ | --------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| 1   | POST   | `/api/Invoice/invoiceDraftNew`                | `Invoice_InvoiceDraftNew`                | Portal Fatura Ekleme (Yeni)              |
| 2   | POST   | `/api/Invoice/invoiceDraft`                   | `Invoice_InvoiceDraft`                   | Portal Fatura Ekleme                     |
| 3   | POST   | `/api/Invoice/invoiceNote`                    | `Invoice_SaveInvoiceNote`                | Fatura Not Ekleme                        |
| 4   | POST   | `/api/Invoice/invoiceDrugAndMedical`          | `Invoice_SaveInvoiceDrugAndMedical`      | Fatura İlaç/Tıbbi Cihaz Ekleme           |
| 5   | POST   | `/api/Invoice/deleteInvoiceDraft`             | `Invoice_DeleteInvoiceDraft`             | Taslak Fatura Sil                        |
| 6   | GET    | `/api/Invoice/invoiceDraftSignAndSend`        | `Invoice_InvoiceDraftSignAndSend`        | Taslak Fatura İmzala & Gönder            |
| 7   | GET    | `/api/Invoice/getInvoiceModel`                | `Invoice_GetInvoiceModel`                | Fatura Model (Tekil Sorgu)               |
| 8   | POST   | `/api/Invoice/getInvoiceModelList`            | `Invoice_GetInvoiceResultModelList`      | Fatura Model Liste                       |
| 9   | POST   | `/api/Invoice/getInvoiceWithHeaderInfoList`   | `Invoice_GetInvoiceWithHeaderInfoList`   | Fatura Listesi (Başlıklı)                |
| 10  | GET    | `/api/Invoice/getInvoiceDraftPdfAsZip`        | `Invoice_GetInvoiceDraftPdfAsZip`        | Taslak Fatura PDF                        |
| 11  | GET    | `/api/Invoice/createInvoiceDraftTestJson`     | `Invoice_createInvoiceDraftTestJson`     | Fatura Ekleme Örnek JSON                 |
| 12  | POST   | `/api/Invoice/invoiceDraftSendToGib`          | `Invoice_InvoiceDraftSendToGib`          | GİB Portal'a Fatura Gönderme             |
| 13  | POST   | `/api/Invoice/invoiceDraftSendToGibUblXml`    | `Invoice_InvoiceDraftSendToGibUblXml`    | GİB Portal'a Fatura Gönderme (XML)       |
| 14  | POST   | `/api/Invoice/invoiceDraftReSendToGib`        | `Invoice_InvoiceDraftReSendToGib`        | GİB Portal'a Fatura Gönderme (Tekrar)    |
| 15  | POST   | `/api/Invoice/requestSmsConfimCodeFromGib`    | `Invoice_requestSmsConfimCodeFromGib`    | GİB Portal SMS Onay Kodu Talebi          |
| 16  | POST   | `/api/Invoice/sendSmsConfirmForInvoiceToGib`  | `Invoice_SendSmsConfirmForInvoiceToGib`  | GİB Portal SMS Onayı ile İmza            |
| 17  | POST   | `/api/Invoice/removeInvoiceFromGib`           | `Invoice_RemoveInvoiceFromGib`           | GİB Portal'dan Onaylanmamış Faturayı Sil |
| 18  | POST   | `/api/Invoice/createCancellationRequestToGib` | `Invoice_CreateCancellationRequestToGib` | GİB Portal İptal Talebi Oluşturma        |

---

## 1. Portal Fatura Ekleme (Yeni) — `invoiceDraftNew`

```
POST /api/Invoice/invoiceDraftNew
```

Portal Fatura ekranına kayıt gönderir. Gönderilen kayıt **taslak** olarak kaydedilir; gerekli düzenlemelerden sonra Portal'dan İmzala/Gönder yapılmalıdır.

`invoiceDraft` metodu ile aynıdır, tek fark geri dönüş değeridir: bu metod `InvoiceOutboxResultModel` döner (fatura ID, ETTN ve belge numarası).

### Request Body — `InvoiceDraftModel`

#### Zorunlu Alanlar

| Alan           | Tip                | Açıklama                                                                                                                      |
| -------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer            | Fatura Id değeri                                                                                                              |
| `currencyCode` | string (max 3)     | Döviz tipi (örn. `TRY`, `USD`, `EUR`)                                                                                         |
| `currencyRate` | number(18,6)       | Döviz kuru                                                                                                                    |
| `docDate`      | string (date-time) | Fatura tarihi                                                                                                                 |
| `docTime`      | string (date-time) | Fatura zamanı (sadece saat kısmı kullanılır)                                                                                  |
| `invoiceType`  | string (enum)      | Fatura tipi: `SATIŞ`, `İADE`, `TEVKİFAT`, `İSTİSNA`, `ÖZEL MATRAH`, `İHRAÇ KAYITLI`, `KONAKLAMA VERGİSİ`, `SARJ`, `SARJANLIK` |
| `prefix`       | string (max 3)     | Ön ek (örn. `MYF`)                                                                                                            |
| `profile`      | string (enum)      | Senaryo: `TEMEL FATURA`, `TİCARİ FATURA`, `EARSIVFATURA`, `EARSIVBELGE`, `ENERJİ`, `İLAÇ VE TIBBİ CİHAZ`                      |

#### Opsiyonel Alanlar

| Alan                                    | Tip                | Açıklama                                                                                    |
| --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| `invoiceETTN`                           | string \| null     | Fatura ETTN. Boş gönderilirse sistem üretir.                                                |
| `eDocumentType`                         | string \| null     | Belge tipi: `EFATURA`, `EARSIVFATURA`, `ESMM`, `EMM`, `EARSIVFATURA(GIB)`, `FATURA`         |
| `isThrowExceptionOnEDocumentTypeChange` | boolean            | Belge tipi değişiminde hata fırlatma                                                        |
| `connectorGuid`                         | string             | Belge gönderimini sağlayan aracı firmanın unique değeri (iş ortaklığı biriminden alınır)    |
| `tenantIdentifierNumber`                | string             | İşlem yapılacak müşterinin VKN/TCKN'si (birden fazla müşteri bağlıysa kullanılır)           |
| `xsltName`                              | string             | Özel fatura görünümü (xsltCode). Boş ise varsayılan/GİB standart dizayn kullanılır.         |
| `dueDate`                               | string (date-time) | Vade tarihi                                                                                 |
| `senderType`                            | string (enum)      | Gönderim tipi: `ELEKTRONIK`, `KAGIT`                                                        |
| `orderNo`                               | string (max 50)    | Sipariş numarası                                                                            |
| `orderDate`                             | string (date-time) | Sipariş tarihi                                                                              |
| `billingRefInvoiceNo`                   | string (max 50)    | İade fatura no (sadece `invoiceType = "İADE"`)                                              |
| `billingRefInvoiceDate`                 | string (date-time) | İade fatura tarihi (sadece `invoiceType = "İADE"`)                                          |
| `billingRefNote`                        | string (max 250)   | İade fatura açıklaması (sadece `invoiceType = "İADE"`)                                      |
| `categoryName`                          | string             | Portal'da tanımlı kategori adı                                                              |
| `folderName`                            | string             | Portal'da tanımlı klasör adı                                                                |
| `paymentAccount`                        | object             | [AccountModel](#ek-cari-hesap-modeli-accountmodel) — Alıcı cari hesap                       |
| `paymentMeans`                          | array              | Ödeme bilgileri listesi (bkz. aşağıda)                                                      |
| `isReplacesEDespatch`                   | boolean (0,1)      | Fatura irsaliye yerine geçiyor mu? Default: `false`                                         |
| `pkAlias`                               | string (max 100)   | Müşteri posta kutusu. Boş bırakılırsa EFATURA'da otomatik atanır.                           |
| `isNewAccount`                          | boolean (0,1)      | Yeni müşteri kartı açılıp açılmayacağı. Default: `false`                                    |
| `isNewAcc`                              | boolean (0,1)      | Yeni muhasebe hesabı açılıp açılmayacağı. Default: `false`                                  |
| `warehouse`                             | object             | Depo bilgisi (`id`, `warehouseCode`)                                                        |
| `invoiceAccount`                        | object             | [AccountModel](#ek-cari-hesap-modeli-accountmodel) — Fatura cari hesabı                     |
| `isInternetSales`                       | boolean (0,1)      | İnternet satışı mı? Default: `false`                                                        |
| `internetShipmentInfo`                  | object             | E-arşiv ek bilgiler (sadece `profile = "EARSIVFATURA"`)                                     |
| `invoiceDetail`                         | array              | [InvoiceDetailModel](#ek-fatura-kalem-modeli-invoicedetailmodel) listesi — Fatura kalemleri |
| `notes`                                 | array              | Not listesi (her eleman `{ "note": "..." }`)                                                |
| `periodStartDate`                       | string (date-time) | Periyot başlangıç tarihi                                                                    |
| `periodEndDate`                         | string (date-time) | Periyot bitiş tarihi                                                                        |
| `licencePlate`                          | string             | Plaka                                                                                       |
| `vehicleNumber`                         | string             | Araç numarası                                                                               |
| `esuReportInfo`                         | object             | ESU Rapor bilgisi (`eSUReportId`, `eSUReportDate`)                                          |
| `isGenerateDocNo`                       | boolean            | `true` ise belgeye sistem tarafından otomatik numara verilir                                |

#### `paymentMeans` Elemanı (`PaymentMeansForDraft`)

| Alan                 | Tip                | Açıklama                                                                                                              |
| -------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `paymentMeansCode`   | string             | Ödeme tipi: `1`-Muhtelif, `10`-Nakit, `20`-Çek, `23`-Banka Çeki, `42`-Havale/EFT, `48`-Kredi/Banka Kartı, `ZZZ`-Diğer |
| `paymentChannelCode` | string             | Ödeme kanalı                                                                                                          |
| `paymentDueDate`     | string (date-time) | Ödeme tarihi                                                                                                          |
| `iban`               | string             | IBAN                                                                                                                  |
| `currencyCode`       | string             | Para birimi                                                                                                           |
| `note`               | string             | Açıklama                                                                                                              |

#### `internetShipmentInfo` (`InternetShipmentInfoModel`)

| Alan                     | Tip                | Açıklama                                                                      |
| ------------------------ | ------------------ | ----------------------------------------------------------------------------- |
| `webSiteUrl`             | string             | İnternet satış adresi                                                         |
| `paymentType`            | string (enum)      | `KREDIKARTI/BANKAKARTI`, `EFT/HAVALE`, `KAPIDAODEME`, `ODEMEARACISI`, `DIGER` |
| `internetAccountName`    | string             | Ödeme aracısı                                                                 |
| `paymentDate`            | string (date-time) | Ödeme tarihi                                                                  |
| `paymentNote`            | string             | Ödeme şekli açıklaması                                                        |
| `shippingDate`           | string (date-time) | Gönderim tarihi                                                               |
| `shippingAccountName`    | string             | Taşıyıcı unvan/ad-soyad                                                       |
| `shippingAccountVknTckn` | string             | Taşıyıcı VKN/TCKN                                                             |

### Response — `InvoiceOutboxResultModelResultModel`

```json
{
    "data": {
        "invoiceId": 12345,
        "invoiceETTN": "C29150A2-F879-48C2-A447-1CB1FF2BA360",
        "docNo": "MYF2026000000001"
    },
    "succeed": true,
    "message": null,
    "errorCode": null,
    "afterValue": 0
}
```

| Alan               | Tip     | Açıklama              |
| ------------------ | ------- | --------------------- |
| `data.invoiceId`   | integer | Fatura ID             |
| `data.invoiceETTN` | string  | Fatura ETTN           |
| `data.docNo`       | string  | Fatura belge numarası |

### Örnek İstek

```json
{
    "id": 0,
    "invoiceETTN": "",
    "eDocumentType": "EARSIVFATURA",
    "profile": "EARSIVFATURA",
    "invoiceType": "SATIŞ",
    "prefix": "MYF",
    "docDate": "2026-08-06T10:00:00Z",
    "docTime": "2026-08-06T10:00:00Z",
    "currencyCode": "TRY",
    "currencyRate": 1,
    "invoiceAccount": {
        "accountName": "ÖRNEK TİCARET A.Ş.",
        "identifierNumber": "1234567890",
        "city": { "code": "34", "name": "İSTANBUL" },
        "country": { "code": "TR", "name": "TÜRKİYE" },
        "citySubdivision": "Kadıköy",
        "taxOffice": { "code": "123456", "name": "Kadıköy V.D." }
    },
    "invoiceDetail": [
        {
            "product": {
                "productType": "Stok",
                "productCode": "URUN001",
                "productName": "Örnek Ürün"
            },
            "unitCode": "C62",
            "unitName": "ADET",
            "qty": 2,
            "unitPriceTra": 100,
            "amtTra": 200,
            "vatRate": 20,
            "isKDVInclude": 0
        }
    ],
    "isGenerateDocNo": true
}
```

---

## 2. Portal Fatura Ekleme — `invoiceDraft`

```
POST /api/Invoice/invoiceDraft
```

`invoiceDraftNew` ile **tamamen aynı** request body'yi (`InvoiceDraftModel`) kullanır.

**Tek fark:** Geri dönüş değeri `Int32ResultModel`'dir — `data` alanı integer (fatura ID) döner.

### Response — `Int32ResultModel`

```json
{
    "data": 12345,
    "succeed": true,
    "message": null,
    "errorCode": null,
    "afterValue": 0
}
```

---

## 3. Fatura Not Ekleme — `invoiceNote`

```
POST /api/Invoice/invoiceNote
operationId: Invoice_SaveInvoiceNote
```

Mevcut bir faturaya not ekler. Toplu not ekleme desteklenir.

### Request Body — `InvoiceNoteRequestModel`

| Alan                     | Tip    | Zorunlu  | Açıklama                                                  |
| ------------------------ | ------ | -------- | --------------------------------------------------------- |
| `tenantIdentifierNumber` | string | Hayır    | İşlem yapılacak firmanın VKN/TCKN'si                      |
| `invoiceNoteList`        | array  | **Evet** | [InvoiceNoteForApiModel](#invoicenoteforapimodel) listesi |

#### `InvoiceNoteForApiModel`

| Alan          | Tip    | Zorunlu  | Açıklama                        |
| ------------- | ------ | -------- | ------------------------------- |
| `invoiceETTN` | string | **Evet** | Faturanın benzersiz ETTN değeri |
| `note`        | string | **Evet** | Faturaya eklenecek not bilgisi  |

### Örnek İstek

```json
{
    "invoiceNoteList": [
        {
            "invoiceETTN": "C29150A2-F879-48C2-A447-1CB1FF2BA360",
            "note": "Bu fatura için ödeme alındı."
        }
    ]
}
```

### Response — `Int32ListResultModel`

```json
{
    "data": [1, 2],
    "succeed": true,
    "message": null,
    "errorCode": null,
    "afterValue": 0
}
```

---

## 4. Fatura İlaç/Tıbbi Cihaz — `invoiceDrugAndMedical`

```
POST /api/Invoice/invoiceDrugAndMedical
```

İlaç veya tıbbi cihaz içeren faturalar için ek bilgi ekler.

### Request Body — `InvoiceDrugAndMedicalRequestModel`

| Alan                        | Tip    | Zorunlu  | Açıklama                             |
| --------------------------- | ------ | -------- | ------------------------------------ |
| `tenantIdentifierNumber`    | string | Hayır    | İşlem yapılacak firmanın VKN/TCKN'si |
| `invoiceDrugAndMedicalList` | array  | **Evet** | `InvoiceDrugAndMedicalModel` listesi |

#### `InvoiceDrugAndMedicalModel`

| Alan                 | Tip                | Zorunlu  | Açıklama                                                                   |
| -------------------- | ------------------ | -------- | -------------------------------------------------------------------------- |
| `invoiceETTN`        | string             | **Evet** | Faturanın ETTN değeri                                                      |
| `invoiceId`          | integer            | **Evet** | İlgili faturanın ID'si                                                     |
| `invoiceDetailId`    | integer            | **Evet** | Fatura detay (kalem) ID'si                                                 |
| `drugAndMedicalType` | integer            | **Evet** | `1` = İLAÇ, `2` = TIBBİ CİHAZ                                              |
| `productNumber`      | string             | **Evet** | İlaç ise GTIN (Küresel Ticari Ürün No), Tıbbi Cihaz ise Ürün Numarası      |
| `batchNumber`        | string             | **Evet** | Parti/Lot numarası                                                         |
| `serialNumber`       | string             | **Evet** | Seri/Sıra numarası                                                         |
| `baseDate`           | string (date-time) | **Evet** | İlaç ise Son Kullanma Tarihi, Tıbbi Cihaz ise Üretim Tarihi (`YYYY-MM-DD`) |

### Response — `Int32ListResultModel`

`data` integer listesi döner.

---

## 5. Taslak Fatura Silme — `deleteInvoiceDraft`

```
POST /api/Invoice/deleteInvoiceDraft
```

### Request Body — `DeleteInvoiceDraftModel`

| Alan                     | Tip     | Açıklama                                   |
| ------------------------ | ------- | ------------------------------------------ |
| `invoiceId`              | integer | Silinecek faturanın ID'si                  |
| `invoiceETTN`            | string  | Silinecek faturanın ETTN'si                |
| `tenantIdentifierNumber` | string  | Müşteri VKN/TCKN (çoklu müşteri durumunda) |

### Response — `BooleanResultModel`

```json
{
    "data": true,
    "succeed": true,
    "message": null,
    "errorCode": null,
    "afterValue": 0
}
```

---

## 6. Taslak Fatura İmzala & Gönder — `invoiceDraftSignAndSend`

```
GET /api/Invoice/invoiceDraftSignAndSend
```

### Query Parametreleri

| Parametre                | Tip    | Açıklama                      |
| ------------------------ | ------ | ----------------------------- |
| `invoiceETTN`            | string | İmzalanacak faturanın ETTN'si |
| `tenantIdentifierNumber` | string | Müşteri VKN/TCKN              |

### Response — `InvoiceOutboxResultModelResultModel`

`data` içinde `invoiceId`, `invoiceETTN`, `docNo` döner.

---

## 7. Fatura Sorgulama (Tekil) — `getInvoiceModel`

```
GET /api/Invoice/getInvoiceModel
```

### Query Parametreleri

| Parametre                | Tip    | Açıklama                       |
| ------------------------ | ------ | ------------------------------ |
| `invoiceETTN`            | string | Sorgulanacak faturanın ETTN'si |
| `tenantIdentifierNumber` | string | Müşteri VKN/TCKN               |

### Response — `InvoiceForApiModelResultModel`

`data` içinde tam fatura modeli döner.

---

## 8. Fatura Listesi — `getInvoiceModelList`

```
POST /api/Invoice/getInvoiceModelList
```

### Request Body — `InvoiceResultListRequestModel`

| Alan                     | Tip     | Açıklama                                                 |
| ------------------------ | ------- | -------------------------------------------------------- |
| `afterValue`             | integer | Sayfalama imleci (bu değerden itibaren kayıtlar dönülür) |
| `limit`                  | integer | Aynı anda dönülecek kayıt sayısı                         |
| `tenantIdentifierNumber` | string  | Müşteri VKN/TCKN                                         |
| `startDate`              | string  | Başlangıç tarihi (`YYYY-MM-DD`)                          |
| `endDate`                | string  | Bitiş tarihi (`YYYY-MM-DD`)                              |
| `invoiceETTN`            | string  | Belirli bir faturanın ETTN'si                            |
| `transactionTypeName`    | string  | İşlem türü (örn: `SATIŞ`, `ALIŞ`, `PROFORMA ALIŞ`)       |

### Response — `InvoiceResultModelListResultModel`

`data` içinde fatura listesi, `afterValue` ile sonraki sayfa imleci döner.

---

## 9. Fatura Listesi (Başlıklı) — `getInvoiceWithHeaderInfoList`

```
POST /api/Invoice/getInvoiceWithHeaderInfoList
```

### Request Body — `GetInvoiceListRequestModel`

| Alan                     | Tip     | Açıklama                                                      |
| ------------------------ | ------- | ------------------------------------------------------------- |
| `afterValue`             | integer | Sayfalama imleci                                              |
| `limit`                  | integer | Sayfa boyutu                                                  |
| `tenantIdentifierNumber` | string  | Müşteri VKN/TCKN                                              |
| `startDate`              | string  | Başlangıç tarihi                                              |
| `endDate`                | string  | Bitiş tarihi                                                  |
| `eDocumentType`          | string  | Belge tipi filtresi: `EFATURA`, `EARSIVFATURA`, `ESMM`, `EMM` |
| `vknTckn`                | string  | Fatura düzenlenen firmanın VKN/TCKN'si                        |
| `isUseDocDate`           | boolean | `true` ise oluşturma tarihi yerine belge tarihi kullanılır    |
| `isDraft`                | boolean | `true` ise sadece taslak kayıtlar                             |

### Response — `InvoiceHeaderInfoModelListResultModel`

`data` içinde fatura başlık bilgisi listesi döner.

---

## 10. Taslak Fatura PDF — `getInvoiceDraftPdfAsZip`

```
GET /api/Invoice/getInvoiceDraftPdfAsZip
```

### Query Parametreleri

| Parametre                | Tip    | Açıklama         |
| ------------------------ | ------ | ---------------- |
| `invoiceETTN`            | string | Fatura ETTN      |
| `tenantIdentifierNumber` | string | Müşteri VKN/TCKN |

### Response — `StringResultModel`

`data` alanında ZIP olarak paketlenmiş PDF'in base64 string'i döner.

> **İpucu:** Örnek JSON şablonu görmek için `GET /api/Invoice/createInvoiceDraftTestJson` endpoint'ini çağırabilirsiniz; `InvoiceDraftModel` örneği döner.

---

## 11. GİB Portal'a Fatura Gönderme — `invoiceDraftSendToGib`

```
POST /api/Invoice/invoiceDraftSendToGib
```

Taslak faturayı GİB Portal'a gönderir. Request body `InvoiceDraftModel` kullanır (fatura oluşturma ile aynı model).

### Response — `EArchiveSmsConfirmModelQueryResultModel`

E-arşiv SMS onayı gerekebilir; yanıtta SMS onay detayları döner.

---

## 12. GİB Portal'a Fatura Gönderme (XML) — `invoiceDraftSendToGibUblXml`

```
POST /api/Invoice/invoiceDraftSendToGibUblXml
```

UBL XML formatında faturayı GİB Portal'a gönderir.

### Request Body — `InvoiceDraftForUblXmlModel`

Model, `InvoiceDraftModel` ile benzerdir ancak fatura içeriği UBL XML (base64) olarak `invoiceTypeUblString` alanında gönderilir.

| Alan                     | Tip            | Açıklama                                    |
| ------------------------ | -------------- | ------------------------------------------- |
| `invoiceTypeUblString`   | string         | UBL XML'in base64 (zip'li) değeri           |
| `eDocumentType`          | string         | Belge tipi (`EFATURA`, `EARSIVFATURA`, ...) |
| `prefix`                 | string         | Ön ek                                       |
| `pkAlias`                | string         | Posta kutusu alias                          |
| `gbAlias`                | string         | GB posta kutusu alias                       |
| `xsltName`               | string \| null | XSLT görünüm adı                            |
| `tenantIdentifierNumber` | string \| null | Müşteri VKN/TCKN                            |

### Response — `EArchiveSmsConfirmModelQueryResultModel`

---

## 13–18. GİB Portal Diğer İşlemler

### 14. GİB Portal'a Tekrar Gönderme

```
POST /api/Invoice/invoiceDraftReSendToGib
```

**Request:** `GibInvoiceOperationModel` (fatura ETTN/ID içerir)
**Response:** `EArchiveSmsConfirmModelQueryResultModel`

### 15. GİB Portal SMS Onay Kodu Talebi

```
POST /api/Invoice/requestSmsConfimCodeFromGib
```

**Request:** `GibInvoiceSmsRequestModel`
**Response:** `StringResultModel`

### 16. GİB Portal SMS Onayı ile İmza

```
POST /api/Invoice/sendSmsConfirmForInvoiceToGib
```

**Request:** `GibInvoiceSmsConfirmModel` (SMS onay kodu içerir)
**Response:** `EArchiveSmsConfirmModelQueryResultModel`

### 17. GİB Portal'dan Onaylanmamış Faturayı Silme

```
POST /api/Invoice/removeInvoiceFromGib
```

**Request:** `GibInvoiceOperationModel`
**Response:** `EArchiveSmsConfirmModelQueryResultModel`

### 18. GİB Portal İptal Talebi Oluşturma

```
POST /api/Invoice/createCancellationRequestToGib
```

**Request:** `GibInvoiceCancellationModel`
**Response:** `EArchiveSmsConfirmModelQueryResultModel`

---

## Ek: Cari Hesap Modeli (AccountModel)

`paymentAccount` ve `invoiceAccount` alanlarında kullanılır.

| Alan                     | Tip     | Zorunlu  | Açıklama                                                        |
| ------------------------ | ------- | -------- | --------------------------------------------------------------- |
| `id`                     | integer | **Evet** | Cari hesap tekil anahtarı                                       |
| `accountName`            | string  | **Evet** | Unvan/ad-soyad                                                  |
| `identifierNumber`       | string  | Hayır    | TCKN/VKN                                                        |
| `city`                   | object  | **Evet** | `{ code, name }` — İl                                           |
| `country`                | object  | **Evet** | `{ code, name }` — Ülke                                         |
| `citySubdivision`        | string  | **Evet** | İlçe                                                            |
| `accountCode`            | string  | Hayır    | Cari hesap kodu                                                 |
| `shortName`              | string  | Hayır    | Kısa ad                                                         |
| `taxOffice`              | object  | Hayır    | `{ code, name }` — Vergi dairesi                                |
| `telephone1`             | string  | Hayır    | Telefon                                                         |
| `email1`                 | string  | Hayır    | E-posta                                                         |
| `fax1`                   | string  | Hayır    | Fax                                                             |
| `mobilePhone1`           | string  | Hayır    | Cep telefonu                                                    |
| `postalCode`             | string  | Hayır    | Posta kodu                                                      |
| `streetName`             | string  | Hayır    | Cadde/sokak                                                     |
| `buildingNumber`         | string  | Hayır    | Bina no                                                         |
| `blockName`              | string  | Hayır    | Blok adı                                                        |
| `buildingName`           | string  | Hayır    | Bina adı                                                        |
| `room`                   | string  | Hayır    | Kapı no                                                         |
| `district`               | string  | Hayır    | Mahalle                                                         |
| `region`                 | string  | Hayır    | Kasaba/köy                                                      |
| `webSiteUrl`             | string  | Hayır    | Web sitesi                                                      |
| `naceCode`               | string  | Hayır    | NACE kodu                                                       |
| `mersisNo`               | string  | Hayır    | MERSIS no                                                       |
| `dueDay`                 | integer | Hayır    | Vade gün                                                        |
| `accountCardType`        | integer | Hayır    | `1` Müşteri-Tedarikçi, `2` Personel, `3` Müşteri, `4` Tedarikçi |
| `category1Name`          | string  | Hayır    | Grup seviyesi 1                                                 |
| `category2Name`          | string  | Hayır    | Grup seviyesi 2                                                 |
| `category3Name`          | string  | Hayır    | Grup seviyesi 3                                                 |
| `note`                   | string  | Hayır    | Not                                                             |
| `isCheckWithAccountCode` | string  | Hayır    | Kod ile kontrol: `EVET` / `HAYIR` (Default: `HAYIR`)            |
| `isPassive`              | string  | Hayır    | Pasif: `EVET` / `HAYIR` (Default: `HAYIR`)                      |

---

## Ek: Fatura Kalem Modeli (InvoiceDetailModel)

`invoiceDetail` array'inin her bir elemanı.

| Alan                                | Tip           | Zorunlu  | Açıklama                                                                                                                |
| ----------------------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `product`                           | object        | **Evet** | `ProductBaseModel` (bkz. aşağıda)                                                                                       |
| `isNewProduct`                      | boolean (0,1) | Hayır    | Yeni stok kartı açılsın mı? Default: `false`                                                                            |
| `unitCode`                          | string        | Hayır    | ISO birim kodu (Adet için `C62`, Kg için `KGM`)                                                                         |
| `unitName`                          | string        | Hayır    | Birim adı                                                                                                               |
| `qty`                               | number(18,6)  | Hayır    | Miktar                                                                                                                  |
| `unitPriceTra`                      | number(18,6)  | Hayır    | Birim fiyat                                                                                                             |
| `amtTra`                            | number(18,2)  | Hayır    | Tutar (qty × unitPrice)                                                                                                 |
| `discRate`                          | number(18,2)  | Hayır    | İskonto oranı (%)                                                                                                       |
| `discAmtTra`                        | number(18,2)  | Hayır    | İskonto tutarı                                                                                                          |
| `vatRate`                           | number(18,2)  | Hayır    | KDV oranı (%)                                                                                                           |
| `amtVatTra`                         | number(18,2)  | Hayır    | KDV tutarı (gönderilirse Tax sınıfına ayrıca eklenmez)                                                                  |
| `isKDVInclude`                      | boolean (0,1) | Hayır    | Birim fiyata KDV dahil mi? `1` DAHİL, `0` HARİÇ. Default: `false`                                                       |
| `note`                              | string        | Hayır    | Kalem notu                                                                                                              |
| `taxExemptionReasonCode`            | string        | Koşullu  | Vergi muafiyet kodu (`invoiceType="İSTİSNA"` veya KDV `0` ise zorunlu)                                                  |
| `taxExemptionReasonName`            | string        | Koşullu  | Vergi muafiyet adı (aynı koşulda zorunlu)                                                                               |
| `withholdingTaxTypeCode`            | string        | Hayır    | Tevkifat kodu                                                                                                           |
| `withholdingTaxPercentage`          | number(18,2)  | Hayır    | Tevkifat oranı (sadece kod `650` iken)                                                                                  |
| `oivRate`                           | number(18,2)  | Hayır    | ÖİV oranı                                                                                                               |
| `oivAmtTra`                         | number(18,2)  | Hayır    | ÖİV tutarı                                                                                                              |
| `otvCode`                           | string        | Hayır    | ÖTV kodu                                                                                                                |
| `otvRate`                           | number(18,2)  | Hayır    | ÖTV oranı                                                                                                               |
| `otvAmtTra`                         | number(18,2)  | Hayır    | ÖTV tutarı                                                                                                              |
| `otvTaxExemptionReasonCode`         | string        | Hayır    | ÖTV muafiyet kodu                                                                                                       |
| `sellerLineCode`                    | string        | Hayır    | Satıcı satır kodu                                                                                                       |
| `lineCode`                          | string        | Hayır    | Alıcı satır kodu                                                                                                        |
| `gTipCode`                          | string        | Hayır    | GTIP kodu                                                                                                               |
| `tax`                               | array         | Hayır    | Ek vergiler (`{ taxName, taxCode, taxRate, taxAmount, taxableAmount, taxExemptionReasonCode, taxExemptionReasonName }`) |
| `serialNumber`                      | string        | Hayır    | Ürün seri no                                                                                                            |
| `drugMedicalDeviceType`             | string        | Hayır    | `ILAC` / `TIBBICIHAZ`                                                                                                   |
| `invoiceDetailOrderLineReference`   | array         | Hayır    | Sipariş referansları (`{ purchaseOrderNo, purchaseOrderDate, salesOrderNo, salesOrderDate }`)                           |
| `invoiceDetailReceiptLineReference` | array         | Hayır    | İrsaliye referansları (`{ despatchNo, despatchDate }`)                                                                  |

### `ProductBaseModel`

| Alan          | Tip     | Zorunlu  | Açıklama                       |
| ------------- | ------- | -------- | ------------------------------ |
| `id`          | integer | **Evet** | Stok tekil anahtarı (0 = yeni) |
| `productType` | string  | **Evet** | `Stok`, `Gelir`, `Gider`       |
| `productCode` | string  | **Evet** | Stok kodu                      |
| `productName` | string  | **Evet** | Stok adı                       |

---

## Ek: PHP (Laravel) Örnek

### Token Alma

```php
use Illuminate\Support\Facades\Http;

$tokenResponse = Http::asForm()->post('https://edocumentapi.mysoft.com.tr/oauth/token', [
    'grant_type'    => 'client_credentials',
    'client_id'     => config('services.mysoft.client_id'),
    'client_secret' => config('services.mysoft.client_secret'),
]);

$accessToken = $tokenResponse->json('access_token');
```

### Taslak Fatura Oluşturma (`invoiceDraftNew`)

```php
$response = Http::withToken($accessToken)
    ->withHeaders(['Content-Type' => 'application/json'])
    ->post('https://edocumentapi.mysoft.com.tr/api/Invoice/invoiceDraftNew', [
        'id'             => 0,
        'eDocumentType'  => 'EARSIVFATURA',
        'profile'        => 'EARSIVFATURA',
        'invoiceType'    => 'SATIŞ',
        'prefix'         => 'MYF',
        'docDate'        => now()->format('Y-m-d\TH:i:s\Z'),
        'docTime'        => now()->format('Y-m-d\TH:i:s\Z'),
        'currencyCode'   => 'TRY',
        'currencyRate'   => 1,
        'isGenerateDocNo'=> true,
        'invoiceAccount' => [
            'accountName'      => 'ÖRNEK TİCARET A.Ş.',
            'identifierNumber' => '1234567890',
            'city'             => ['code' => '34', 'name' => 'İSTANBUL'],
            'country'          => ['code' => 'TR', 'name' => 'TÜRKİYE'],
            'citySubdivision'  => 'Kadıköy',
        ],
        'invoiceDetail' => [
            [
                'product'      => [
                    'productType'  => 'Stok',
                    'productCode'  => 'URUN001',
                    'productName'  => 'Örnek Ürün',
                ],
                'unitCode'     => 'C62',
                'qty'          => 2,
                'unitPriceTra' => 100,
                'vatRate'      => 20,
            ],
        ],
    ]);

if ($response->json('succeed')) {
    $invoiceId  = $response->json('data.invoiceId');
    $invoiceEtt = $response->json('data.invoiceETTN');
    $docNo      = $response->json('data.docNo');
}
```

### Faturaya Not Eklema (`invoiceNote`)

```php
$response = Http::withToken($accessToken)->post(
    'https://edocumentapi.mysoft.com.tr/api/Invoice/invoiceNote',
    [
        'invoiceNoteList' => [
            [
                'invoiceETTN' => $invoiceEtt,
                'note'        => 'Ödeme alındı.',
            ],
        ],
    ]
);
```

### Taslağı İmzala & Gönder

```php
$response = Http::withToken($accessToken)->get(
    'https://edocumentapi.mysoft.com.tr/api/Invoice/invoiceDraftSignAndSend',
    [
        'invoiceETTN'           => $invoiceEtt,
        'tenantIdentifierNumber' => $tenantVkn,
    ]
);
```