İrsaliye oluşturma

Giden e-İrsaliye oluşturmak için bu endpoint kullanılır. Gövde; irsaliye başlık alanları, alıcı (parties.delivery) ve en az bir kalemden (lines) oluşur. İrsaliye asenkron olarak sağlayıcıya iletilir; alanlara özel notlar ilgili bölümlerin başında verilmiştir.

İstek

POST /api/waybills
Accept: application/json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Üst düzey alanlar

İrsaliye hesabı ve hak kullanımı

invoice_integration_id, hesabınıza ait ve giden irsaliyeyi destekleyen bir fatura hesabı olmalıdır. Desteklemeyen bir hesap seçilirse Seçilen entegrasyon giden irsaliyeyi desteklemiyor. hatası döner.
Her irsaliye planınızdan 1 hak düşer. Hakkınız bittiyse istek İrsaliye oluşturma haklarınız tükenmiştir. mesajıyla, planınızın süresi dolduysa abonelik yenileme mesajıyla 422 döner.
İrsaliye hatalı duruma düşerse ya da taslak irsaliye silinirse hak otomatik iade edilir.

Alan	Tip	Zorunlu	Açıklama
`invoice_integration_id`	number	Evet	İrsaliyenin gönderileceği fatura hesabının ID'si — bkz. fatura hesabı listeleme.
`profile`	string	Evet	İrsaliye profili: `TEMELIRSALIYE`, `IDISIRSALIYE`, `HKSIRSALIYE` — bkz. Sabitler.
`type`	string	Evet	İrsaliye tipi: `SEVK` veya `MATBUDAN` — bkz. Sabitler.
`issue_date`	string	Evet	Düzenlenme tarihi, `Y-m-d`.
`issue_time`	string	Evet	Düzenlenme saati, `H:i`.
`actual_dispatch_date`	string	Evet	Fiili sevk tarihi, `Y-m-d`.
`actual_dispatch_time`	string	Evet	Fiili sevk saati, `H:i`.
`currency`	string	Evet	Para birimi (örn. `TRY`) — bkz. Sabitler.
`currency_rate`	number	Evet	Kur; `0`'dan büyük olmalıdır. `TRY` için `1`.
`ettn`	string	Hayır	İrsaliyenin UUID'si. Gönderilmezse platform üretir.
`document_number`	string	Hayır	İrsaliye numarası. Genellikle boş bırakılır; numara sağlayıcı tarafından atanır.
`is_draft`	boolean	Hayır	`true` ise irsaliye sağlayıcıda taslak olarak kaydedilir ve gönderilmez. Varsayılan `false`.
`sender_alias` / `receiver_alias`	string	Hayır	Gönderici ve alıcı posta kutusu etiketleri (GB/PK).
`shipment_number`	string	Hayır	Sevkiyat numarası.
`transport_mode_code`	string	Hayır	Taşıma şekli kodu.
`license_plate`	string	Hayır	Araç plakası.
`trailer_number`	string	Hayır	Dorse plakası.
`driver_name` / `driver_surname`	string	Hayır	Şoför adı ve soyadı.
`driver_identifier_number`	string	Hayır	Şoför TCKN'si; tam 11 hane.
`notes`	string[]	Hayır	İrsaliye notları.
`callback_url`	string	Hayır	Geçerli URL. İrsaliye durumu değiştikçe bu adrese bildirim gönderilir — bkz. Callback bildirimi.
`customer.id`	number	Hayır	Paneldeki müşteri kaydının ID'si. İrsaliyeyi müşteri kartına bağlar; irsaliye panelden faturalandırılırken müşteri bilgileri bu karttan alınır.
`parties`	object	Evet	İrsaliye tarafları; aşağıya bakın.
`lines`	array	Evet	En az bir kalem; aşağıya bakın.

`parties.delivery` alanları (alıcı)

Alıcı bilgisi parties.delivery altında gönderilir

parties, rol adlarını anahtar olarak kullanan bir nesnedir. Giden irsaliyede sağlayıcıya yalnızca delivery (alıcı) tarafı iletilir ve bu anahtar zorunludur. Gelen irsaliyelerde görebileceğiniz diğer roller için bkz. Sabitler.

VKN/TCKN uzunluğu, hangi ad alanının zorunlu olduğunu belirler:

10 hane (VKN, tüzel kişi) → title zorunlu.
11 hane (TCKN, gerçek kişi) → name ve surname zorunlu.

Alan	Tip	Zorunlu	Açıklama
`identifier_number`	string	Evet	VKN (10 hane) veya TCKN (11 hane).
`title`	string	Koşullu	Ünvan; VKN ile gönderildiğinde zorunlu.
`name`	string	Koşullu	Ad; TCKN ile gönderildiğinde zorunlu.
`surname`	string	Koşullu	Soyad; TCKN ile gönderildiğinde zorunlu.
`tax_office`	string	Hayır	Vergi dairesi.
`country`	string	Evet	Ülke.
`city`	string	Evet	İl.
`district`	string	Evet	İlçe.
`address`	string	Evet	Açık adres.
`postal_code`	string	Hayır	Posta kodu; en fazla 20 karakter.
`phone`	string	Hayır	Telefon; en fazla 20 karakter.
`email`	string	Hayır	Geçerli e-posta adresi.

`lines[]` kalem alanları

Ürünü önce oluşturmanız gerekmez

Kalemdeki ad, miktar, birim, birim fiyat ve KDV oranı doğrudan gövdeden alınır. Kalemi paneldeki bir ürün kartına bağlamak isterseniz product_id gönderin. Sayısal bir id gönderirseniz o da ürün kartı ID'si olarak kullanılır.

Fiyat ve vergi alanları irsaliyede bilgi amaçlıdır. İrsaliyeyi sonradan faturalandırırken fatura gövdesini ayrıca gönderirsiniz.

Alan	Tip	Zorunlu	Açıklama
`name`	string	Evet	Mal/hizmet adı.
`quantity`	number	Evet	Sevk edilen miktar; `0`'dan büyük olmalıdır.
`unit`	string	Evet	Birim kodu (örn. `C62`) — bkz. birim kodları.
`unit_price`	number	Evet	Birim fiyat, `≥ 0`.
`tax_rate`	number	Evet	KDV oranı: `0`, `1`, `2`, `8`, `10`, `18`, `20`.
`product_id`	number	Hayır	Paneldeki ürün kartı ID'si; hesabınıza ait olmalıdır.
`sku` / `seller_product_code`	string	Hayır	Satıcı ürün kodu (`sku` öncelikli).
`buyer_product_code`	string	Hayır	Alıcı ürün kodu.
`manufacturer_product_code`	string	Hayır	Üretici ürün kodu.
`description`	string	Hayır	Kalem açıklaması.
`brand_name` / `model_name`	string	Hayır	Marka ve model.
`notes`	string[]	Hayır	Kalem notları.
`discount_type`	string	Hayır	`amount` veya `percentage`.
`discount`, `discount_total`	number	Hayır	İndirim oranı/tutarı ve toplam indirim.
`tax_total`, `tax_excluded_total`, `grand_total`, `extra_tax_total`	number	Hayır	Hesaplanmış tutarlar (bilgi amaçlı).
`exemption_code` / `exemption_reason`	string	Hayır	KDV istisna kodu ve gerekçesi.
`withholding_tax_code` / `withholding_tax_reason`	string	Hayır	Tevkifat kodu ve gerekçesi — bkz. Sabitler.
`extra_taxes`	array	Hayır	Ek vergiler; her eleman için `tax_code` ve `tax_rate` zorunludur.

Örnek istekler

💻 cURL
🐘 PHP
🟢 Node.js
🐍 Python

curl -X POST "https://app.faturaentegrator.com/api/waybills" \
  -H "Accept: application/json" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "invoice_integration_id": 9,
    "profile": "TEMELIRSALIYE",
    "type": "SEVK",
    "issue_date": "2026-09-30",
    "issue_time": "10:00",
    "actual_dispatch_date": "2026-09-30",
    "actual_dispatch_time": "10:30",
    "currency": "TRY",
    "currency_rate": 1,
    "license_plate": "34ABC123",
    "driver_identifier_number": "11111111111",
    "driver_name": "Ahmet",
    "driver_surname": "Yılmaz",
    "callback_url": "https://example.com/irsaliye-callback",
    "parties": {
      "delivery": {
        "identifier_number": "1234567890",
        "title": "Örnek Ticaret A.Ş.",
        "tax_office": "Kadıköy",
        "country": "Türkiye",
        "city": "İstanbul",
        "district": "Kadıköy",
        "address": "Örnek Mah. Örnek Sok. No:1"
      }
    },
    "lines": [
      { "name": "Örnek Ürün", "sku": "SKU-001", "quantity": 2, "unit": "C62", "unit_price": 100, "tax_rate": 20 }
    ]
  }'

<?php
$body = [
    'invoice_integration_id' => 9,
    'profile' => 'TEMELIRSALIYE',
    'type' => 'SEVK',
    'issue_date' => '2026-09-30',
    'issue_time' => '10:00',
    'actual_dispatch_date' => '2026-09-30',
    'actual_dispatch_time' => '10:30',
    'currency' => 'TRY',
    'currency_rate' => 1,
    'license_plate' => '34ABC123',
    'driver_identifier_number' => '11111111111',
    'driver_name' => 'Ahmet',
    'driver_surname' => 'Yılmaz',
    'callback_url' => 'https://example.com/irsaliye-callback',
    'parties' => [
        'delivery' => [
            'identifier_number' => '1234567890',
            'title' => 'Örnek Ticaret A.Ş.',
            'tax_office' => 'Kadıköy',
            'country' => 'Türkiye',
            'city' => 'İstanbul',
            'district' => 'Kadıköy',
            'address' => 'Örnek Mah. Örnek Sok. No:1',
        ],
    ],
    'lines' => [
        ['name' => 'Örnek Ürün', 'sku' => 'SKU-001', 'quantity' => 2, 'unit' => 'C62', 'unit_price' => 100, 'tax_rate' => 20],
    ],
];

$ch = curl_init('https://app.faturaentegrator.com/api/waybills');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => ['Accept: application/json', 'Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

const body = {
  invoice_integration_id: 9,
  profile: 'TEMELIRSALIYE',
  type: 'SEVK',
  issue_date: '2026-09-30',
  issue_time: '10:00',
  actual_dispatch_date: '2026-09-30',
  actual_dispatch_time: '10:30',
  currency: 'TRY',
  currency_rate: 1,
  license_plate: '34ABC123',
  driver_identifier_number: '11111111111',
  driver_name: 'Ahmet',
  driver_surname: 'Yılmaz',
  callback_url: 'https://example.com/irsaliye-callback',
  parties: {
    delivery: {
      identifier_number: '1234567890',
      title: 'Örnek Ticaret A.Ş.',
      tax_office: 'Kadıköy',
      country: 'Türkiye',
      city: 'İstanbul',
      district: 'Kadıköy',
      address: 'Örnek Mah. Örnek Sok. No:1',
    },
  },
  lines: [
    { name: 'Örnek Ürün', sku: 'SKU-001', quantity: 2, unit: 'C62', unit_price: 100, tax_rate: 20 },
  ],
};

const res = await fetch('https://app.faturaentegrator.com/api/waybills', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});
const data = await res.json();

import requests

body = {
    'invoice_integration_id': 9,
    'profile': 'TEMELIRSALIYE',
    'type': 'SEVK',
    'issue_date': '2026-09-30',
    'issue_time': '10:00',
    'actual_dispatch_date': '2026-09-30',
    'actual_dispatch_time': '10:30',
    'currency': 'TRY',
    'currency_rate': 1,
    'license_plate': '34ABC123',
    'driver_identifier_number': '11111111111',
    'driver_name': 'Ahmet',
    'driver_surname': 'Yılmaz',
    'callback_url': 'https://example.com/irsaliye-callback',
    'parties': {
        'delivery': {
            'identifier_number': '1234567890',
            'title': 'Örnek Ticaret A.Ş.',
            'tax_office': 'Kadıköy',
            'country': 'Türkiye',
            'city': 'İstanbul',
            'district': 'Kadıköy',
            'address': 'Örnek Mah. Örnek Sok. No:1',
        }
    },
    'lines': [
        {'name': 'Örnek Ürün', 'sku': 'SKU-001', 'quantity': 2, 'unit': 'C62', 'unit_price': 100, 'tax_rate': 20}
    ],
}

r = requests.post(
    'https://app.faturaentegrator.com/api/waybills',
    json=body,
    headers={'Accept': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY'},
)
data = r.json()

Örnek yanıt

{
  "data": {
    "id": 214,
    "invoice_integration_id": 9,
    "direction": "outgoing",
    "ettn": "b7e3a0c2-5d41-4f8e-9a1b-2c3d4e5f6a7b",
    "document_number": null,
    "profile": "TEMELIRSALIYE",
    "type": "SEVK",
    "issue_date": "2026-09-30",
    "status": "pending",
    "callback_url": "https://example.com/irsaliye-callback",
    "invoice_integration": { "id": 9, "invoice_integration": "mysoft", "...": "..." },
    "parties": [
      { "id": 530, "role": "delivery", "identifier_number": "1234567890", "title": "Örnek Ticaret A.Ş.", "...": "..." }
    ],
    "lines": [
      { "id": 811, "line_number": 1, "name": "Örnek Ürün", "seller_product_code": "SKU-001", "quantity": "2.000000", "...": "..." }
    ],
    "...": "..."
  }
}

İrsaliye numarası ve PDF bu yanıtta yoktur

İrsaliye kuyruğa alınır ve sağlayıcıya arka planda iletilir. document_number ve PDF, işlem tamamlandıktan sonra oluşur. Durumu izlemek için callback_url tanımlayın veya irsaliye detayını sorgulayın.

Durum akışı

is_draft gönderilmediyse irsaliye pending → processing → completed sırasıyla ilerler. Sağlayıcı veya GİB hata verirse failed olur ve hata ayrıntısı kaydın errors[] dizisine yazılır. is_draft: true ile oluşturulan irsaliye sağlayıcıya iletildikten sonra draft durumunda kalır. Tüm değerler için bkz. Sabitler.

Callback bildirimi

callback_url gönderirseniz irsaliyenin durumu her güncellendiğinde bu adrese POST isteği yapılır. Bildirim şu anlarda gelir:

İrsaliye sağlayıcıya iletildiğinde
İrsaliye hataya düştüğünde
processing durumundaki irsaliyenin durumu arka planda her sorgulandığında

Durum sorgusu irsaliye tamamlanana kadar tekrarlandığından aynı durum için birden fazla bildirim alabilirsiniz; alıcınızı idempotent tasarlayın.

{
  "waybill_id": 214,
  "team_id": 45,
  "time": "2026-09-30 10:31:15",
  "hash": "b3f1c9a4e8d2..."
}

İmza, fatura callback'i ile aynı yöntemle üretilir; tek fark ilk değerin waybill_id olmasıdır:

hash = HMAC-SHA512( waybill_id + team_id + time , API_ANAHTARINIZ )

Bildirim gövdesinde durum bilgisi bulunmaz. Bildirimi aldıktan sonra güncel kaydı GET /api/waybills/{waybill_id} ile çekin. İsteğin zaman aşımı 10 saniyedir.

İstek​

Üst düzey alanlar​

parties.delivery alanları (alıcı)​

lines[] kalem alanları​

Örnek istekler​

Örnek yanıt​

Durum akışı​

Callback bildirimi​