> ## Documentation Index
> Fetch the complete documentation index at: https://docs.muhasip.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Fatura işlemini yürüt

> invoiceInfo, view, invoiceapproval ve invoicecancel işlem türlerini destekler.

<Note>
  Mali işlem sonucunu ve varsa `operationId` değerini saklayın. Zaman aşımında veya `review_required` durumunda otomatik
  tekrar yapmayın. Tamamlanmış tekrar cevabı ilk cevabın bütün gövdesini yeniden sunmaz. [İşlem
  takibi](/rehberler/islem-takibi)
</Note>

## Ne yapar?

invoiceInfo, view, invoiceapproval ve invoicecancel işlem türlerini destekler. invoiceInfo, read izniyle seri ve belge şablonu seçeneklerini getirir. view taslak oluşturur ve Idempotency-Key gerektirir. Onay ve silme isteklerinde body, 1–100 benzersiz UUID veya \{UUID} öğesi içermelidir; moduleType eInvoice veya eArchive olmalıdır. Gönderim sonucu doğrulanmadan belge gönderilmiş sayılmaz. Sonuç belirsizse 502, retryable=false ve işlem makbuzu dönebilir; yeni istek göndermeden mevcut işlemi inceleyin. replayed=true cevabı ilk yanıtın bütün içeriğini tekrarlamaz.

## Ön koşullar ve izin

`type=invoiceInfo` için `muhasip:invoice:read`; diğer belgelenmiş türler için `muhasip:invoice:write` gerekir. `type=view` için `Idempotency-Key` zorunludur. **view gerçek taslak oluşturur.**

İlişkili kayıtlar aynı firmaya ait olmalıdır. Erişim ayarları için [kimlik ve izinler](/baslangic/kimlik-ve-izinler) rehberini inceleyin.

**İşlem anahtarı:** Yalnız type=view için zorunlu. Aynı işlem için aynı anahtarı kullanın; örnekler `MUHASIP_IDEMPOTENCY_KEY` ortam değişkenini kullanır.

[İstek ve cevap şemalarını indirin](/openapi.json).

## İstek örnekleri

Örnekler temsilîdir. Kimlikleri, belge tarihlerini ve iş verisini kendi yetkili kayıtlarınızla değiştirin. Node.js örnekleri **Node.js 20 veya üzeri** içindir; PHP örnekleri cURL uzantısını kullanır. Hiçbiri otomatik tekrar yapmaz.

<Tabs>
  <Tab title="invoiceInfo">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST 'https://api.muhasip.pro/apps/invoice/api' \
        --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
        --header 'Accept: */*' \
        --header 'Content-Type: application/json' \
        --data-binary @- <<'JSON'
      {
        "type": "invoiceInfo",
        "vkn": "0000000000",
        "countriesCode": "TR"
      }
      JSON
      ```

      ```php PHP theme={null}
      <?php
      $apiUserId = getenv('MUHASIP_API_USER_ID');
      $secretKey = getenv('MUHASIP_API_SECRET');
      if (!$apiUserId || !$secretKey) {
          throw new RuntimeException('API kimlik bilgileri eksik.');
      }
      $headers = ['Accept: */*', 'Content-Type: application/json'];
      $body = <<<'JSON'
      {
        "type": "invoiceInfo",
        "vkn": "0000000000",
        "countriesCode": "TR"
      }
      JSON;
      $handle = curl_init('https://api.muhasip.pro/apps/invoice/api');
      curl_setopt_array($handle, [
          CURLOPT_CUSTOMREQUEST => 'POST',
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_FOLLOWLOCATION => false,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_CONNECTTIMEOUT => 10,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
          CURLOPT_USERPWD => $apiUserId . ':' . $secretKey,
          CURLOPT_POSTFIELDS => $body,
      ]);
      $response = curl_exec($handle);
      $httpStatus = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
      curl_close($handle);
      if ($response === false) {
          throw new RuntimeException('Bağlantı tamamlanamadı; mali işlemi otomatik tekrarlamayın.');
      }
      if ($httpStatus < 200 || $httpStatus >= 300) {
          throw new RuntimeException('HTTP ' . $httpStatus . '; kaynak hata açıklamasını değerlendirin.');
      }
      // $response gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
      echo 'HTTP ' . $httpStatus . PHP_EOL;
      ```

      ```javascript Node.js theme={null}
      async function main() {
        const apiUserId = process.env.MUHASIP_API_USER_ID
        const secretKey = process.env.MUHASIP_API_SECRET
        if (!apiUserId || !secretKey) throw new Error("API kimlik bilgileri eksik.")
        const response = await fetch("https://api.muhasip.pro/apps/invoice/api", {
          method: "POST",
          redirect: "manual",
          headers: {
            Accept: "*/*",
            Authorization: "Basic " + Buffer.from(`${apiUserId}:${secretKey}`).toString("base64"),
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            type: "invoiceInfo",
            vkn: "0000000000",
            countriesCode: "TR"
          }),
          signal: AbortSignal.timeout(30000)
        })
        const data = await response.arrayBuffer()
        if (!response.ok) throw new Error(`HTTP ${response.status}; kaynak hata açıklamasını değerlendirin.`)
        // data gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
        console.log("HTTP", response.status)
      }

      main().catch(() => {
        console.error("İstek tamamlanamadı; mali işlemi otomatik tekrarlamayın.")
        process.exitCode = 1
      })
      ```
    </CodeGroup>
  </Tab>

  <Tab title="view">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST 'https://api.muhasip.pro/apps/invoice/api' \
        --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
        --header 'Accept: */*' \
        --header "Idempotency-Key: $MUHASIP_IDEMPOTENCY_KEY" \
        --header 'Content-Type: application/json' \
        --data-binary @- <<'JSON'
      {
        "type": "view",
        "data": {
          "CustomerInfo": {
            "Name": "Örnek İşletme",
            "TaxNumber": "0000000000",
            "Address": "Örnek adres",
            "District": "Çankaya",
            "City": "Ankara",
            "Country": "TÜRKİYE"
          },
          "InvoiceProfile": "EARSIVFATURA",
          "InvoiceType": "SATIS",
          "InvoiceSerieOrNumber": "ABC",
          "TemplateUUID": "00000000-0000-4000-8000-000000000001",
          "issueDate": "2026-10-18",
          "currencyCode": "TRY",
          "exchangeRate": 1,
          "lines": [
            {
              "name": "Örnek hizmet",
              "quantity": 1,
              "price": 100,
              "total": 100,
              "taxes": [
                {
                  "taxCode": "0015",
                  "percent": 20,
                  "total": 20
                }
              ]
            }
          ],
          "total": {
            "linesTotal": 100,
            "linesAllowanceTotal": 0,
            "taxesTotals": [
              {
                "taxCode": "0015",
                "percent": 20,
                "total": 20
              }
            ],
            "payableAmount": 120
          }
        }
      }
      JSON
      ```

      ```php PHP theme={null}
      <?php
      $apiUserId = getenv('MUHASIP_API_USER_ID');
      $secretKey = getenv('MUHASIP_API_SECRET');
      if (!$apiUserId || !$secretKey) {
          throw new RuntimeException('API kimlik bilgileri eksik.');
      }
      $operationKey = getenv('MUHASIP_IDEMPOTENCY_KEY');
      if (!$operationKey) {
          throw new RuntimeException('Kalıcı işleme ait tekrar anahtarı eksik.');
      }
      $headers = ['Accept: */*', 'Content-Type: application/json', 'Idempotency-Key: ' . $operationKey];
      $body = <<<'JSON'
      {
        "type": "view",
        "data": {
          "CustomerInfo": {
            "Name": "Örnek İşletme",
            "TaxNumber": "0000000000",
            "Address": "Örnek adres",
            "District": "Çankaya",
            "City": "Ankara",
            "Country": "TÜRKİYE"
          },
          "InvoiceProfile": "EARSIVFATURA",
          "InvoiceType": "SATIS",
          "InvoiceSerieOrNumber": "ABC",
          "TemplateUUID": "00000000-0000-4000-8000-000000000001",
          "issueDate": "2026-10-18",
          "currencyCode": "TRY",
          "exchangeRate": 1,
          "lines": [
            {
              "name": "Örnek hizmet",
              "quantity": 1,
              "price": 100,
              "total": 100,
              "taxes": [
                {
                  "taxCode": "0015",
                  "percent": 20,
                  "total": 20
                }
              ]
            }
          ],
          "total": {
            "linesTotal": 100,
            "linesAllowanceTotal": 0,
            "taxesTotals": [
              {
                "taxCode": "0015",
                "percent": 20,
                "total": 20
              }
            ],
            "payableAmount": 120
          }
        }
      }
      JSON;
      $handle = curl_init('https://api.muhasip.pro/apps/invoice/api');
      curl_setopt_array($handle, [
          CURLOPT_CUSTOMREQUEST => 'POST',
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_FOLLOWLOCATION => false,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_CONNECTTIMEOUT => 10,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
          CURLOPT_USERPWD => $apiUserId . ':' . $secretKey,
          CURLOPT_POSTFIELDS => $body,
      ]);
      $response = curl_exec($handle);
      $httpStatus = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
      curl_close($handle);
      if ($response === false) {
          throw new RuntimeException('Bağlantı tamamlanamadı; mali işlemi otomatik tekrarlamayın.');
      }
      if ($httpStatus < 200 || $httpStatus >= 300) {
          throw new RuntimeException('HTTP ' . $httpStatus . '; kaynak hata açıklamasını değerlendirin.');
      }
      // $response gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
      echo 'HTTP ' . $httpStatus . PHP_EOL;
      ```

      ```javascript Node.js theme={null}
      async function main() {
        const apiUserId = process.env.MUHASIP_API_USER_ID
        const secretKey = process.env.MUHASIP_API_SECRET
        if (!apiUserId || !secretKey) throw new Error("API kimlik bilgileri eksik.")
        const operationKey = process.env.MUHASIP_IDEMPOTENCY_KEY
        if (!operationKey) throw new Error("Kalıcı işleme ait tekrar anahtarı eksik.")
        const response = await fetch("https://api.muhasip.pro/apps/invoice/api", {
          method: "POST",
          redirect: "manual",
          headers: {
            Accept: "*/*",
            Authorization: "Basic " + Buffer.from(`${apiUserId}:${secretKey}`).toString("base64"),
            "Idempotency-Key": operationKey,
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            type: "view",
            data: {
              CustomerInfo: {
                Name: "Örnek İşletme",
                TaxNumber: "0000000000",
                Address: "Örnek adres",
                District: "Çankaya",
                City: "Ankara",
                Country: "TÜRKİYE"
              },
              InvoiceProfile: "EARSIVFATURA",
              InvoiceType: "SATIS",
              InvoiceSerieOrNumber: "ABC",
              TemplateUUID: "00000000-0000-4000-8000-000000000001",
              issueDate: "2026-10-18",
              currencyCode: "TRY",
              exchangeRate: 1,
              lines: [
                {
                  name: "Örnek hizmet",
                  quantity: 1,
                  price: 100,
                  total: 100,
                  taxes: [
                    {
                      taxCode: "0015",
                      percent: 20,
                      total: 20
                    }
                  ]
                }
              ],
              total: {
                linesTotal: 100,
                linesAllowanceTotal: 0,
                taxesTotals: [
                  {
                    taxCode: "0015",
                    percent: 20,
                    total: 20
                  }
                ],
                payableAmount: 120
              }
            }
          }),
          signal: AbortSignal.timeout(30000)
        })
        const data = await response.arrayBuffer()
        if (!response.ok) throw new Error(`HTTP ${response.status}; kaynak hata açıklamasını değerlendirin.`)
        // data gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
        console.log("HTTP", response.status)
      }

      main().catch(() => {
        console.error("İstek tamamlanamadı; mali işlemi otomatik tekrarlamayın.")
        process.exitCode = 1
      })
      ```
    </CodeGroup>
  </Tab>

  <Tab title="invoiceapproval">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST 'https://api.muhasip.pro/apps/invoice/api' \
        --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
        --header 'Accept: */*' \
        --header 'Content-Type: application/json' \
        --data-binary @- <<'JSON'
      {
        "type": "invoiceapproval",
        "moduleType": "eArchive",
        "body": [
          {
            "UUID": "00000000-0000-4000-8000-000000000001"
          }
        ]
      }
      JSON
      ```

      ```php PHP theme={null}
      <?php
      $apiUserId = getenv('MUHASIP_API_USER_ID');
      $secretKey = getenv('MUHASIP_API_SECRET');
      if (!$apiUserId || !$secretKey) {
          throw new RuntimeException('API kimlik bilgileri eksik.');
      }
      $headers = ['Accept: */*', 'Content-Type: application/json'];
      $body = <<<'JSON'
      {
        "type": "invoiceapproval",
        "moduleType": "eArchive",
        "body": [
          {
            "UUID": "00000000-0000-4000-8000-000000000001"
          }
        ]
      }
      JSON;
      $handle = curl_init('https://api.muhasip.pro/apps/invoice/api');
      curl_setopt_array($handle, [
          CURLOPT_CUSTOMREQUEST => 'POST',
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_FOLLOWLOCATION => false,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_CONNECTTIMEOUT => 10,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
          CURLOPT_USERPWD => $apiUserId . ':' . $secretKey,
          CURLOPT_POSTFIELDS => $body,
      ]);
      $response = curl_exec($handle);
      $httpStatus = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
      curl_close($handle);
      if ($response === false) {
          throw new RuntimeException('Bağlantı tamamlanamadı; mali işlemi otomatik tekrarlamayın.');
      }
      if ($httpStatus < 200 || $httpStatus >= 300) {
          throw new RuntimeException('HTTP ' . $httpStatus . '; kaynak hata açıklamasını değerlendirin.');
      }
      // $response gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
      echo 'HTTP ' . $httpStatus . PHP_EOL;
      ```

      ```javascript Node.js theme={null}
      async function main() {
        const apiUserId = process.env.MUHASIP_API_USER_ID
        const secretKey = process.env.MUHASIP_API_SECRET
        if (!apiUserId || !secretKey) throw new Error("API kimlik bilgileri eksik.")
        const response = await fetch("https://api.muhasip.pro/apps/invoice/api", {
          method: "POST",
          redirect: "manual",
          headers: {
            Accept: "*/*",
            Authorization: "Basic " + Buffer.from(`${apiUserId}:${secretKey}`).toString("base64"),
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            type: "invoiceapproval",
            moduleType: "eArchive",
            body: [
              {
                UUID: "00000000-0000-4000-8000-000000000001"
              }
            ]
          }),
          signal: AbortSignal.timeout(30000)
        })
        const data = await response.arrayBuffer()
        if (!response.ok) throw new Error(`HTTP ${response.status}; kaynak hata açıklamasını değerlendirin.`)
        // data gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
        console.log("HTTP", response.status)
      }

      main().catch(() => {
        console.error("İstek tamamlanamadı; mali işlemi otomatik tekrarlamayın.")
        process.exitCode = 1
      })
      ```
    </CodeGroup>
  </Tab>

  <Tab title="invoicecancel">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST 'https://api.muhasip.pro/apps/invoice/api' \
        --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
        --header 'Accept: */*' \
        --header 'Content-Type: application/json' \
        --data-binary @- <<'JSON'
      {
        "type": "invoicecancel",
        "moduleType": "eArchive",
        "body": [
          "00000000-0000-4000-8000-000000000001"
        ]
      }
      JSON
      ```

      ```php PHP theme={null}
      <?php
      $apiUserId = getenv('MUHASIP_API_USER_ID');
      $secretKey = getenv('MUHASIP_API_SECRET');
      if (!$apiUserId || !$secretKey) {
          throw new RuntimeException('API kimlik bilgileri eksik.');
      }
      $headers = ['Accept: */*', 'Content-Type: application/json'];
      $body = <<<'JSON'
      {
        "type": "invoicecancel",
        "moduleType": "eArchive",
        "body": [
          "00000000-0000-4000-8000-000000000001"
        ]
      }
      JSON;
      $handle = curl_init('https://api.muhasip.pro/apps/invoice/api');
      curl_setopt_array($handle, [
          CURLOPT_CUSTOMREQUEST => 'POST',
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_FOLLOWLOCATION => false,
          CURLOPT_HTTPHEADER => $headers,
          CURLOPT_CONNECTTIMEOUT => 10,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
          CURLOPT_USERPWD => $apiUserId . ':' . $secretKey,
          CURLOPT_POSTFIELDS => $body,
      ]);
      $response = curl_exec($handle);
      $httpStatus = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
      curl_close($handle);
      if ($response === false) {
          throw new RuntimeException('Bağlantı tamamlanamadı; mali işlemi otomatik tekrarlamayın.');
      }
      if ($httpStatus < 200 || $httpStatus >= 300) {
          throw new RuntimeException('HTTP ' . $httpStatus . '; kaynak hata açıklamasını değerlendirin.');
      }
      // $response gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
      echo 'HTTP ' . $httpStatus . PHP_EOL;
      ```

      ```javascript Node.js theme={null}
      async function main() {
        const apiUserId = process.env.MUHASIP_API_USER_ID
        const secretKey = process.env.MUHASIP_API_SECRET
        if (!apiUserId || !secretKey) throw new Error("API kimlik bilgileri eksik.")
        const response = await fetch("https://api.muhasip.pro/apps/invoice/api", {
          method: "POST",
          redirect: "manual",
          headers: {
            Accept: "*/*",
            Authorization: "Basic " + Buffer.from(`${apiUserId}:${secretKey}`).toString("base64"),
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            type: "invoicecancel",
            moduleType: "eArchive",
            body: ["00000000-0000-4000-8000-000000000001"]
          }),
          signal: AbortSignal.timeout(30000)
        })
        const data = await response.arrayBuffer()
        if (!response.ok) throw new Error(`HTTP ${response.status}; kaynak hata açıklamasını değerlendirin.`)
        // data gövdesini bu işlemin cevap biçimine göre işleyin; ham cevabı loglamayın.
        console.log("HTTP", response.status)
      }

      main().catch(() => {
        console.error("İstek tamamlanamadı; mali işlemi otomatik tekrarlamayın.")
        process.exitCode = 1
      })
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Cevabı değerlendirin

Önce HTTP durumunu, ardından bu kaynağın `status` ve sonuç alanlarını değerlendirin. Bütün uçlar aynı sonuç zarfını veya oluşturma için `201` kodunu kullanmaz.

Temsilî başarılı cevap; gerçek hizmet çağrısından alınmamıştır:

```json theme={null}
{
  "status": true,
  "result": {
    "status": true,
    "series": [
      {
        "label": "ABC",
        "value": "ABC",
        "isDefault": true
      }
    ],
    "templates": [
      {
        "label": "Örnek şablon",
        "value": "123e4567-e89b-42d3-a456-426614174000",
        "isDefault": true
      }
    ],
    "info": {
      "aliases": [],
      "moduleType": "eArchive"
    }
  }
}
```

`replayed:true` varsa cevap güvenli makbuz ve sonuç kimlikleriyle sınırlı olabilir. İlk HTML/PDF veya mali gövdeyi tekrar beklemeyin. `reviewRequired:true` veya `retryable:false` yeni bir mali çağrı izni değildir.

## Hata durumunda

| HTTP | Bu işlemde anlamı | İzlenecek adım |
| - | - | - |
| 400 | Tür, UUID listesi veya alan geçersiz. | Alan adını, türünü ve zorunluluğunu kontrol edin; değişmeyen hatalı isteği tekrar göndermeyin. |
| 401 | API kimliği/parolası, erişim süresi veya firma doğrulanamadı. | Anahtar kimliğini, gizli değeri, erişim süresini ve firma erişimini kontrol edin. |
| 403 | API izni, IP kısıtı veya kayıt erişimi uygun değil. | Anahtarın izinlerini, IP kısıtını ve kayıt kimliğini kontrol edin. |
| 409 | İstek, devam eden işlemle veya kayıt durumuyla çakışıyor. | Mevcut işlem ve hedefi inceleyin. Kilit veya içerik çatışmasını yeni anahtarla aşmaya çalışmayın. |
| 422 | İstek iş kuralına uymuyor veya işlem reddedildi. | Ret nedenini kontrol edin. Alanlar hatalıysa düzeltin; desteklenmeyen işlemi yeniden göndermeyin. |
| 429 | Ortak istek sınırı aşıldı; sayısal status alanı kullanılır. | Varsa Retry-After bilgisini değerlendirin. Mali çağrıyı otomatik yeniden göndermeyin. |
| 500 | İşlem gerçekleştirilemedi. | İşlem sonucunu inceleyin; bağlantı/hata oluşması mali etkinin hiç başlamadığını kanıtlamaz. |
| 502 | Hizmet yanıtı alınamadı veya mali sonuç kesinleşmedi. | İşlem makbuzunu ve ilgili belge/ödemeyi inceleyin. Belirsiz mali sonucu yeniden göndermeyin. |
| 503 | İşlem kaydına veya gerekli hizmete erişilemiyor. | Varsa işlem kimliğiyle durumu okuyun; kayıt veya hizmet hatasından otomatik tekrar sonucu çıkarmayın. |

Ağ kesintisi, zaman aşımı veya JSON olmayan cevap mali etkinin oluşmadığını kanıtlamaz. Ham istek/cevapları genel loglara yazmayın. [Hata yönetimi](/rehberler/hata-yonetimi)

## Sonraki adım

İşlem makbuzunu saklayın; durum adresinden kontrol edin ve sonuç kimliklerini ilgili belge/tahsilat/siparişle eşleştirin. reviewRequired=true ise yeniden göndermeden manuel inceleyin.

[Kaynak akışı](/rehberler/kaynaklar/fatura) · [İşlem takibi](/rehberler/islem-takibi) · [Kapsam ve sınırlamalar](/rehberler/kapsam-ve-sinirlamalar)


## OpenAPI

````yaml openapi.json POST /apps/invoice/api
openapi: 3.0.3
info:
  title: Muhasip API
  version: 2026-10-18.1
  description: >-
    Fatura, banka, POS ve tahsilat, GİB e-Arşiv, pazaryeri, online işlemler,
    görevler, ajanda ve takvim entegrasyonları. İşlem alanları, izinler, istek
    ve cevap örnekleri ile hata yönetimi.
servers:
  - url: https://api.muhasip.pro
    description: Muhasip API
security:
  - BasicAuth: []
tags:
  - name: Uygulamalar
  - name: Görev yönetimi
  - name: Ajanda ve takvim
  - name: Fatura
    description: Fatura bağlantısı, belge işlemleri ve muhasebeye aktarım.
  - name: Banka
    description: >-
      Banka hesapları, hareketler, mahsup ve mevcut çalışma alanı alt
      kaynakları.
  - name: POS ve tahsilat
    description: POS hesapları, komisyonlar ve tahsilat bağlantıları.
  - name: GİB e-Arşiv
    description: GİB hesabı, sorgu, taslak ve SMS imzalama.
  - name: Pazaryeri
    description: Trendyol bağlantısı ve sipariş aktarımı.
  - name: Online işlemler
    description: Online işlem ekranı yapılandırması.
  - name: İşlem takibi
    description: Mali işlem durumu ve tekrar çağrı makbuzları.
paths:
  /apps/invoice/api:
    post:
      tags:
        - Fatura
      summary: Fatura işlemini yürüt
      description: >-
        invoiceInfo, view, invoiceapproval ve invoicecancel işlem türlerini
        destekler. invoiceInfo, read izniyle seri ve belge şablonu seçeneklerini
        getirir. view taslak oluşturur ve Idempotency-Key gerektirir. Onay ve
        silme isteklerinde body, 1–100 benzersiz UUID veya {UUID} öğesi
        içermelidir; moduleType eInvoice veya eArchive olmalıdır. Gönderim
        sonucu doğrulanmadan belge gönderilmiş sayılmaz. Sonuç belirsizse 502,
        retryable=false ve işlem makbuzu dönebilir; yeni istek göndermeden
        mevcut işlemi inceleyin. replayed=true cevabı ilk yanıtın bütün
        içeriğini tekrarlamaz.
      operationId: financeInvoiceAction
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]+$
          description: Yalnız type=view için zorunlu.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinanceInvoiceApiRequest'
            examples:
              invoiceInfo:
                summary: Mükellef, seri ve şablon sorgusu
                value:
                  type: invoiceInfo
                  vkn: '0000000000'
                  countriesCode: TR
              view:
                summary: Yeni e-belge taslağı
                value:
                  type: view
                  data:
                    CustomerInfo:
                      Name: Örnek İşletme
                      TaxNumber: '0000000000'
                      Address: Örnek adres
                      District: Çankaya
                      City: Ankara
                      Country: TÜRKİYE
                    InvoiceProfile: EARSIVFATURA
                    InvoiceType: SATIS
                    InvoiceSerieOrNumber: ABC
                    TemplateUUID: 00000000-0000-4000-8000-000000000001
                    issueDate: '2026-10-18'
                    currencyCode: TRY
                    exchangeRate: 1
                    lines:
                      - name: Örnek hizmet
                        quantity: 1
                        price: 100
                        total: 100
                        taxes:
                          - taxCode: '0015'
                            percent: 20
                            total: 20
                    total:
                      linesTotal: 100
                      linesAllowanceTotal: 0
                      taxesTotals:
                        - taxCode: '0015'
                          percent: 20
                          total: 20
                      payableAmount: 120
              invoiceapproval:
                summary: Mevcut taslağı gönder
                value:
                  type: invoiceapproval
                  moduleType: eArchive
                  body:
                    - UUID: 00000000-0000-4000-8000-000000000001
              invoicecancel:
                summary: Mevcut taslağı sil
                value:
                  type: invoicecancel
                  moduleType: eArchive
                  body:
                    - 00000000-0000-4000-8000-000000000001
      responses:
        '200':
          description: İşlem tamamlandı. Örnek değerler temsilîdir.
          content:
            application/json:
              schema:
                anyOf:
                  - allOf:
                      - type: object
                        properties:
                          status:
                            type: boolean
                          result:
                            $ref: '#/components/schemas/FinanceInvoiceApiResult'
                        required:
                          - status
                          - result
                        additionalProperties: true
                      - type: object
                        properties:
                          operation:
                            $ref: '#/components/schemas/ApiOperation'
                          operations:
                            type: array
                            items:
                              $ref: '#/components/schemas/ApiOperation'
                          replayed:
                            type: boolean
                  - $ref: '#/components/schemas/ApiOperationReplay'
                description: >-
                  İlk çağrı kaynağa özgü yanıtı ve işlem makbuzunu; tamamlanmış
                  tekrar yalnız güvenli makbuzu ve uygun sonuç kimliklerini
                  döndürür.
              example:
                status: true
                result:
                  status: true
                  series:
                    - label: ABC
                      value: ABC
                      isDefault: true
                  templates:
                    - label: Örnek şablon
                      value: 123e4567-e89b-42d3-a456-426614174000
                      isDefault: true
                  info:
                    aliases: []
                    moduleType: eArchive
        '400':
          description: Tür, UUID listesi veya alan geçersiz.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: false
                message: Tür, UUID listesi veya alan geçersiz.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: >-
            İşlem koruması veya mali sonuç; kaynak varyantının koşullarını
            değerlendirin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiOperationError'
              example:
                status: false
                code: OPERATION_IN_PROGRESS
                message: İşlem sonucunu durum adresinden kontrol ediniz.
                retryable: false
        '422':
          description: >-
            İşlem koruması veya mali sonuç; kaynak varyantının koşullarını
            değerlendirin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiOperationError'
              example:
                status: false
                code: OPERATION_REJECTED
                message: İşlem sonucunu durum adresinden kontrol ediniz.
                retryable: false
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: İşlem gerçekleştirilemedi.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: false
                message: İşlem gerçekleştirilemedi.
        '502':
          description: >-
            İşlem koruması veya mali sonuç; kaynak varyantının koşullarını
            değerlendirin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiOperationError'
              example:
                status: false
                code: UPSTREAM_RESULT_UNCERTAIN
                message: İşlem sonucunu durum adresinden kontrol ediniz.
                retryable: false
        '503':
          description: >-
            İşlem koruması veya mali sonuç; kaynak varyantının koşullarını
            değerlendirin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiOperationError'
              example:
                status: false
                code: OPERATION_RECORD_UNAVAILABLE
                message: İşlem sonucunu durum adresinden kontrol ediniz.
                retryable: false
components:
  schemas:
    FinanceInvoiceApiRequest:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - invoiceInfo
            vkn:
              type: string
              description: Sorgulanacak vergi/kimlik numarası.
              pattern: ^\d{10,11}$
            countriesCode:
              type: string
              default: TR
              description: Ülke kodu; TR veya boş değer yurt içi sorgudur.
          required:
            - type
            - vkn
          additionalProperties: true
          description: Mükellef/seri/şablon sorgusu; read izni.
        - type: object
          properties:
            type:
              type: string
              enum:
                - view
            data:
              $ref: '#/components/schemas/FinanceInvoiceViewData'
          required:
            - type
            - data
          additionalProperties: true
        - type: object
          properties:
            type:
              type: string
              enum:
                - invoicecancel
            moduleType:
              type: string
              enum:
                - eInvoice
                - eArchive
            body:
              type: array
              minItems: 1
              maxItems: 100
              uniqueItems: true
              items:
                oneOf:
                  - type: string
                    format: uuid
                  - type: object
                    properties:
                      UUID:
                        type: string
                        format: uuid
                      Alias:
                        type: string
                        maxLength: 500
                        nullable: true
                    required:
                      - UUID
                    additionalProperties: false
          required:
            - type
            - moduleType
            - body
          additionalProperties: true
          description: Hedef UUID listesiyle işlem korumalı taslak silme.
        - type: object
          properties:
            type:
              type: string
              enum:
                - invoiceapproval
            moduleType:
              type: string
              enum:
                - eInvoice
                - eArchive
            body:
              type: array
              minItems: 1
              maxItems: 100
              uniqueItems: true
              items:
                oneOf:
                  - type: string
                    format: uuid
                  - type: object
                    properties:
                      UUID:
                        type: string
                        format: uuid
                      Alias:
                        type: string
                        maxLength: 500
                        nullable: true
                    required:
                      - UUID
                    additionalProperties: false
              description: >-
                1–100 benzersiz UUID. Nesne biçiminde yalnız UUID ve isteğe
                bağlı Alias kabul edilir; Alias işlem içeriğine dahildir.
          required:
            - type
            - moduleType
            - body
          additionalProperties: true
          description: Hedef UUID listesiyle işlem korumalı gönderim.
      description: >-
        İşlem türünü invoiceInfo, view, invoiceapproval veya invoicecancel
        olarak gönderin. Her türün gerekli alanları aşağıda tanımlanır.
    FinanceInvoiceApiResult:
      anyOf:
        - type: object
          properties:
            status:
              type: boolean
            series:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  value:
                    type: string
                  isDefault:
                    type: boolean
                additionalProperties: true
            templates:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  value:
                    type: string
                  isDefault:
                    type: boolean
                additionalProperties: true
            info:
              type: object
              properties:
                aliases:
                  type: array
                  items:
                    type: object
                    properties:
                      label:
                        type: string
                      value:
                        type: string
                    additionalProperties: true
                  nullable: true
                moduleType:
                  type: string
              additionalProperties: true
          additionalProperties: true
        - type: object
          properties:
            status:
              type: boolean
            UUID:
              type: string
              format: uuid
            html:
              type: string
              nullable: true
          additionalProperties: true
        - $ref: '#/components/schemas/FinanceInvoiceProviderResult'
    ApiOperation:
      type: object
      properties:
        operationId:
          type: string
          pattern: ^[a-f0-9]{64}$
        type:
          type: string
        state:
          type: string
          enum:
            - claimed
            - dispatching
            - provider_accepted
            - succeeded
            - rejected
            - failed_before_dispatch
            - review_required
        reviewRequired:
          type: boolean
        retryable:
          type: boolean
        result:
          $ref: '#/components/schemas/ApiOperationReceipt'
        statusUrl:
          type: string
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 tarih-saat.
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 tarih-saat.
      required:
        - operationId
        - type
        - state
        - reviewRequired
        - retryable
        - result
        - statusUrl
        - createdAt
        - updatedAt
    ApiOperationReplay:
      type: object
      properties:
        status:
          type: boolean
        replayed:
          type: boolean
          enum:
            - true
        operation:
          $ref: '#/components/schemas/ApiOperation'
        operations:
          type: array
          items:
            $ref: '#/components/schemas/ApiOperation'
        resultId:
          type: string
        transactionId:
          type: string
        uuid:
          type: string
        id:
          type: string
        providerId:
          type: string
        documentId:
          type: string
        paymentId:
          type: string
        orderId:
          type: string
        uuids:
          type: array
          items:
            type: string
      required:
        - status
        - replayed
        - operation
        - operations
      additionalProperties: false
    Error:
      type: object
      properties:
        status:
          type: boolean
        code:
          type: string
        message:
          type: string
        description:
          type: string
        retryable:
          type: boolean
        reviewRequired:
          type: boolean
        operationId:
          type: string
      required:
        - status
      additionalProperties: true
    ApiOperationError:
      type: object
      properties:
        status:
          type: boolean
        code:
          type: string
        message:
          type: string
        retryable:
          type: boolean
        reviewRequired:
          type: boolean
        operation:
          $ref: '#/components/schemas/ApiOperation'
        operationId:
          type: string
      required:
        - status
      additionalProperties: true
    FinanceInvoiceViewData:
      type: object
      properties:
        CustomerInfo:
          type: object
          properties:
            Name:
              type: string
              description: Alıcı unvanı veya ad soyadı.
            TaxNumber:
              type: string
              description: Alıcı vergi veya kimlik numarası.
            Address:
              type: string
              description: Alıcı açık adresi.
            District:
              type: string
              description: İlçe bilgisi.
            City:
              type: string
              description: İl bilgisi.
            Country:
              type: string
              description: Ülke adı.
            Mail:
              type: string
              description: E-posta adresi.
          required:
            - Name
          additionalProperties: true
          description: Alıcının kimlik ve adres bilgileri.
        lines:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Mal veya hizmet adı.
              quantity:
                type: number
                description: Miktar.
              price:
                type: number
                description: Birim fiyat.
              total:
                type: number
                description: Kalem toplamı.
              amount:
                type: number
                description: Kalem tutarı.
              unitType:
                type: string
                default: C62
                description: Birim kodu; boşsa önce unit alanı, o da yoksa C62 kullanılır.
              taxes:
                type: array
                items:
                  type: object
                  properties:
                    taxCode:
                      type: string
                      description: Vergi kodu.
                    percent:
                      type: number
                      description: Vergi oranı.
                    total:
                      type: number
                      description: Vergi tutarı.
                  additionalProperties: true
                description: >-
                  Vergi satırları; toplamı sıfır veya negatif olan vergi
                  satırları taslak dönüşümünde çıkarılır.
              withholdingTax:
                type: object
                properties:
                  taxCode:
                    type: string
                  percent:
                    type: number
                  total:
                    type: number
                additionalProperties: true
                description: Kalemin tevkifat bilgisi.
            required:
              - name
              - taxes
            additionalProperties: true
          description: Belge kalemleri; taxes her kalemde dizi olarak bulunmalıdır.
        InvoiceProfile:
          type: string
          description: >-
            E-arşiv için EARSIVFATURA; e-fatura için bağlı hesabın desteklediği
            profil.
        InvoiceType:
          type: string
          default: SATIS
        InvoiceSerieOrNumber:
          type: string
          description: invoiceInfo işleminden seçilen belge serisi veya numarası.
        TemplateUUID:
          type: string
          format: uuid
          description: invoiceInfo işleminden seçilen şablon UUID değeri.
        CustomerAlias:
          type: string
          description: Alıcının seçilen e-fatura posta kutusu.
        issueDate:
          type: string
          format: date
          description: Belge tarihi; tarih-saat sunucu tarafından düzenlenir.
        currencyCode:
          type: string
          description: Belgenin para birimi kodu.
        exchangeRate:
          type: number
          description: Belgede kullanılan döviz kuru.
        Notes:
          type: array
          items:
            type: string
          description: Belge notları.
        total:
          type: object
          additionalProperties: true
          description: >-
            İstemcinin hesapladığı toplamlar; bağlı hizmetin belge doğrulamasına
            tabidir.
      required:
        - CustomerInfo
        - lines
      additionalProperties: true
    FinanceInvoiceProviderResult:
      type: object
      properties:
        status:
          type: boolean
        statusCode:
          type: integer
          nullable: true
        statusText:
          type: string
        data: {}
        message: {}
        deliveryUncertain:
          type: boolean
        code:
          type: string
        requestId:
          type: string
      additionalProperties: true
      description: >-
        Fatura işleminin sonucu. Alanlar işlem türüne göre değişir; bağlantı
        anahtarları cevapta verilmez.
    ApiOperationReceipt:
      type: object
      properties:
        resultId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        transactionId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        uuid:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        id:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        providerId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        documentId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        paymentId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        orderId:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^[A-Za-z0-9_.:-]+$
        uuids:
          type: array
          items:
            type: string
            maxLength: 200
            pattern: ^[A-Za-z0-9_.:-]+$
          maxItems: 100
      additionalProperties: false
    RateLimitError:
      type: object
      properties:
        status:
          type: integer
          enum:
            - 429
        error:
          type: string
        message:
          type: string
      required:
        - status
        - error
        - message
  responses:
    Unauthorized:
      description: API kimliği/parolası, erişim süresi veya firma doğrulanamadı.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: Basic realm="Muhasip API", charset="UTF-8"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: false
            code: UNAUTHORIZED
            message: API kimlik bilgileri doğrulanamadı.
    Forbidden:
      description: Ürün, IP, modül izni veya kaynak kapsamı uygun değil.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: false
            message: Ürün, IP, modül izni veya kaynak kapsamı uygun değil.
    RateLimited:
      description: Ortak istek sınırı aşıldı; sayısal status alanı kullanılır.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            status: 429
            error: Too Many Requests
            message: Rate limit exceeded. Please try again later.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Kullanıcı adı apiUserId, parola secretKey. Aktif ve süresi geçmemiş API
        kullanıcısı ve uygun firma gerekir.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.