DehaSoft E-Fatura & e-Arşiv API Portalı

DehaSoft yüksek performanslı bulut altyapısı ile GİB mevzuatlarına %100 uyumlu e-Fatura oluşturma, iptal etme ve süresiz önizleme mikroservis entegrasyon kılavuzu.

API Durumu: Aktif

Altyapı: DehaSoft Cloud

Base URL: https://api.invoice.deha360.com

Güvenlik: HTTPS Mandatory

Limit: 60 istek / dk

Versiyon: 2.0.0

Kimlik Doğrulama (Authentication)

API isteklerinizi güvenli bir şekilde sunucumuza iletmek için kullanmanız gereken başlıklar.

Tüm API isteklerinde HTTP Başlıkları (Headers) içerisinde size özel tanımlanan X-API-KEY bilgisini iletmeniz zorunludur:

HEADERS Content-Type: application/json | Accept: application/json | X-API-KEY: <YOUR_API_KEY>

Güvenlik Uyarısı: API Anahtarınızı tarayıcı (Frontend / React / Vue) kodlarında yayınlamayın. Tüm istekleri kendi backend sunucunuz üzerinden (Server-to-Server) gerçekleştirin.

Fatura Oluşturma

Alıcının mükellefiyet durumuna göre otomatik e-Fatura veya e-Arşiv faturası üretir.

POST /api/invoice/create

Otomatik Mükellef Tespiti: Vergi numarasını (VKN/TCKN) arka planda sorgular. Alıcı e-Fatura mükellefi ise e-Fatura (TICARIFATURA), değilse e-Arşiv Fatura (EARSIVFATURA) olarak otomatik düzenler.

Örnek JSON İsteği (Payload):

{
  "order": {
    "id": 21,
    "doc_date": "2026-07-30",
    "customer_name": "Genesis Teknoloji A.Ş.",
    "invoice_address": {
      "tax_number": "3941069153",
      "city": "Denizli",
      "district": "Bekilli",
      "address": "Atatürk Mah. Sanayi Cad. No:15"
    },
    "items": [
      {
        "product_name": "Yazılım Danışmanlık Hizmeti",
        "quantity": 1,
        "price": 1000.0,
        "vat_rate": 20.0
      }
    ],
    "note": "Ödeme havale ile alınmıştır."
  }
}

Başarılı Yanıt (200 OK):

{
  "success": true,
  "invoice": {
    "success": true,
    "uuid": "c29c0b93-a962-470e-9fc8-85d0d2c17d76",
    "invoice_number": "ODC2026000000032",
    "ettn": "d0125ebd-147e-436e-aaac-3bfc8e9f5bc3",
    "refNo": "c29c0b93-a962-470e-9fc8-85d0d2c17d76",
    "message": "İşlem Başarılı!"
  },
  "base64Pdf": {
    "success": true,
    "preview": "JVBERi0xLjQK..."
  },
  "preview_url": "https://api.invoice.deha360.com/api/invoice/preview/cCnhSqsw1GjzUUnWYj..."
}

Fatura İptal Etme

Oluşturulmuş e-Fatura / e-Arşiv faturasını GİB portalında iptal eder.

POST /api/invoice/cancel

Faturayı iptal etmek için ettn, invoice_number veya external_id alanlarından herhangi birini belirtmeniz yeterlidir:

{
  "ettn": "d0125ebd-147e-436e-aaac-3bfc8e9f5bc3",
  "reason": "Müşteri sipariş iptal talebi"
}

Başarılı İptal Yanıtı (200 OK):

{
  "success": true,
  "message": "Fatura başarıyla iptal edildi.",
  "invoice": {
    "success": true,
    "ettn": "d0125ebd-147e-436e-aaac-3bfc8e9f5bc3",
    "invoice_number": "ODC2026000000032",
    "external_id": "21",
    "reason": "Müşteri sipariş iptal talebi"
  }
}

Fatura Önizleme (Süresiz)

Müşterilerin veya dış sistemlerin faturayı doğrudan görüntülemesini sağlar.

GET /api/invoice/preview/{token}

Yanıtta dönen preview_url bağlantısı **süresizdir** ve API Key başlığı gerektirmez. Müşterileriniz tıklayıp doğrudan faturayı görebilir.

Format	URL Parametresi	Açıklama
HTML Görünüm	Varsayılan (Parametresiz)	Tarayıcıda faturanın şık HTML şablonunu açar.
PDF İndirme	`?format=pdf`	Faturanın orijinal PDF dosyasını indirir veya tarayıcıda görüntüler.

E-İrsaliye Oluşturma

GİB mevzuatına uygun olarak otomatik e-İrsaliye düzenler, sıra numarası ve ETTN üretir.

POST /api/despatch/create

Otomatik Etiket Tespiti & Mevzuat Uyumu: Alıcının e-İrsaliye mükellefiyet durumunu GİB'den (DespatchAdvice) sorgular, posta kutusunu (alias) çözer, TEMELIRSALIYE senaryosu ile geçerli sıra numarası üretir.

Örnek JSON İsteği (Payload):

{
  "customer": {
    "vkn_tckn": "3941069153",
    "name": "GAİ TEST A.Ş.",
    "tax_office": "DENİZLİ",
    "city": "İSTANBUL",
    "district": "KADIKÖY",
    "address": "Atatürk Mah. Sanayi Cad. No:15",
    "zip_code": "34700"
  },
  "items": [
    {
      "productName": "Laptop Computer",
      "quantity": 2,
      "unitPrice": 50000.00,
      "unitCode": "C62"
    }
  ],
  "license_plate": "34ABC123",
  "driver": {
    "tckn": "11111111111",
    "name": "Ahmet",
    "surname": "Yılmaz"
  },
  "docDate": "2026-08-03",
  "isDraft": true
}

Başarılı İrsaliye Yanıtı (200 OK):

{
  "status": true,
  "message": "İrsaliye başarıyla eklendi.",
  "exceptionMessage": null,
  "data": [
    {
      "ettn": "76735e5d-b6a0-4561-aa9f-8029b5abf42b",
      "documentNo": "IRS2026000000151",
      "refNo": "6299d149-8c05-4f0b-91e6-565d41a7e864",
      "status": true,
      "message": "İşlem Başarılı!",
      "exceptionMessage": null
    }
  ],
  "errorList": []
}

E-İrsaliye Görüntüleme & Önizleme

Sisteme kaydedilmiş veya gönderilmiş irsaliyenin görsel çıktısını (HTML/PDF) alır.

POST /api/despatch/preview

Oluşturulan e-İrsaliyenin ettn veya refNo parametresi ile HTML / PDF / XML çıktısını Base64 olarak almanızı sağlar.

Örnek İstek (Payload):

{
  "ettn": "76735e5d-b6a0-4561-aa9f-8029b5abf42b",
  "refNo": "6299d149-8c05-4f0b-91e6-565d41a7e864",
  "fileType": "html"
}

Başarılı Önizleme Yanıtı (200 OK):

{
  "status": true,
  "message": "İşlem Başarılı!",
  "exceptionMessage": null,
  "data": "PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0MvL0RURCBIVE1MIDQuMDE..."
}

Kod Örnekleri

Farklı yazılım dillerinde fatura oluşturma entegrasyonu.

curl -X POST https://api.invoice.deha360.com/api/invoice/create \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "order": {
      "id": "ORDER-101",
      "customer_name": "Ahmet Yılmaz",
      "invoice_address": {
        "tax_number": "12345678901",
        "city": "İstanbul"
      },
      "items": [
        {
          "product_name": "Yazılım Lisansı",
          "quantity": 1,
          "price": 500,
          "vat_rate": 20
        }
      ]
    }
  }'

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-KEY' => 'YOUR_API_KEY',
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
])->post('https://api.invoice.deha360.com/api/invoice/create', [
    'order' => [
        'id' => 'ORDER-101',
        'customer_name' => 'Ahmet Yılmaz',
        'invoice_address' => [
            'tax_number' => '12345678901',
            'city' => 'İstanbul',
            'address' => 'Test Mah. No:1'
        ],
        'items' => [
            [
                'product_name' => 'Yazılım Lisansı',
                'quantity' => 1,
                'price' => 500.0,
                'vat_rate' => 20
            ]
        ]
    ]
]);

$data = $response->json();
$previewUrl = $data['preview_url'];

const response = await fetch('https://api.invoice.deha360.com/api/invoice/create', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    order: {
      id: 'ORDER-101',
      customer_name: 'Ahmet Yılmaz',
      invoice_address: {
        tax_number: '12345678901',
        city: 'İstanbul'
      },
      items: [
        {
          product_name: 'Yazılım Lisansı',
          quantity: 1,
          price: 500.0,
          vat_rate: 20
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Preview Link:', data.preview_url);

İş Kuralları ve Hata Kodları

Entegrasyon sırasında dikkat edilmesi gereken kurallar.

Kural / Hata	Açıklama	Çözüm
`7 Gün Kuralı`	GİB mevzuatı gereği fatura tarihi (`doc_date`) bugünden en fazla 7 gün öncesi olabilir.	`doc_date` alanını boş bırakın veya son 7 gün içinde bir tarih gönderin.
`VKN / TCKN Regex`	Vergi numarası tam 10 hane (VKN) veya 11 hane (TCKN) rakamlardan oluşmalıdır.	Müşteri vergi kimlik numarasını kontrol edin.
`HTTP 401`	API Key eksik veya geçersizdir.	`X-API-KEY` header bilgisini kontrol edin.
`HTTP 422`	Gönderilen veri formatı doğrulanamadı.	Zorunlu alanları (`order.id`, `items`, `price` vb.) kontrol edin.

Postman Koleksiyonu

API'yi doğrudan Postman üzerinde test etmek için hazırdır.

Postman Collection V2.0

Fatura Oluşturma, Önizleme ve İptal isteklerini içeren hazır Postman dosyasını kopyalayabilirsiniz.