JSON Feed (özel entegrasyon)

Kendi sisteminizi, tek bir JSON adresi vererek pazaryeri gibi entegre etmek için bu yöntem kullanılır. Siparişlerinizi belirli bir URL'de yayınlarsınız; Fatura Entegratör bu adresi saatte bir çağırıp yeni ve güncellenen siparişleri panele aktarır. API'ye tek tek sipariş göndermeniz (POST /api/orders) gerekmez.

Panel tarafındaki kurulum adımları için yardım merkezindeki anlatıma bakabilirsiniz; bu sayfa yazılımcı tarafında feed'in ne döndürmesi gerektiğini anlatır.

Nasıl çalışır?

Siz, siparişlerinizi JSON olarak yayınlayan bir uç nokta (feed) yazarsınız.
Panelde Ayarlar → Entegrasyonlar → Satış Kanalları → Kanal Ekle → JSON Feed (Özel Entegrasyon) ile kanalı oluşturur, feed adresini ve varsa yetkilendirme bilgilerini girersiniz.
Bağlantıyı Test Et ile adres doğrulanır (page=1 ile bir istek atılır; 200 ve orders dizisi bekleniyor).
Saatte bir feed çağrılır; gelen siparişler panele yazılır, ayarlarınıza göre faturaları tek tıkla veya otomatik oluşturulur.
Bildirim adresi tanımladıysanız fatura oluştuğunda/silindiğinde sisteminize POST ile haber verilir.

Denemek için hazır feed

Kendi feed'inizi yazmadan akışı görmek isterseniz kanal eklerken adres olarak https://feed-example.faturaentegrator.com/orders girip yetkilendirmeyi Yok bırakabilirsiniz. Bu sayfadaki örnek yanıt da bu adresten alınmıştır.

Platformun feed'e attığı istek

GET {feed_url}?updated_after=2026-07-24T09:00:00+03:00&page=1
Accept: application/json

Parametre	Açıklama
`page`	Sayfa numarası. İlk çağrıda `1`, sonraki çağrılarda bir artırılarak gönderilir.
`updated_after`	ISO-8601 tarih; son 7 gün içinde değişen siparişler istenir. Feed'inizin bu parametreye göre filtrelemesi önerilir, zorunlu değildir.

Bağlantı testinde yalnızca page=1 gönderilir.

Yetkilendirme

Feed'iniz açık olmak zorunda değildir. Kanal ayarındaki Yetkilendirme Türü seçimine göre platform şu başlığı ekler:

Tür	Gönderilen başlık
Yok	—
Bearer Token	`Authorization: Bearer {token}`
Basic Auth	`Authorization: Basic base64(kullanıcı:şifre)`
Özel Header	`{header adı}: {değer}` — örn. `X-Api-Key: abc123`

Feed'in döndürmesi gereken yanıt

200 durum kodu ve kök seviyede bir orders dizisi zorunludur. Bu iki koşul sağlanmazsa bağlantı testi ve senkronizasyon başarısız olur, panelde “Sipariş Senkronizasyon Hatası” bildirimi oluşur.

{
  "orders": [ /* ... */ ],
  "pagination": { "page": 1, "per_page": 50, "total_pages": 3 }
}

`pagination`

Alan	Zorunlu	Açıklama
`page`	Hayır	Bu yanıtın sayfa numarası (varsayılan `1`).
`total_pages`	Hayır	Toplam sayfa sayısı (varsayılan `1`).
`per_page`	Hayır	Bilgi amaçlıdır; platform tarafından kullanılmaz.

page < total_pages ise platform bir sonraki sayfayı otomatik olarak ister. Tek sayfada dönüyorsanız pagination alanını hiç göndermeyebilirsiniz.

`orders[]` alanları

id alanı boş olan siparişler sessizce atlanır; her siparişin sizde benzersiz bir kimliği olmalıdır.

Alan	Tip	Zorunlu	Açıklama
`id`	string	Evet	Siparişin sizdeki benzersiz numarası. Panelde `platform_id` olarak saklanır ve tekrar aktarımlarda eşleştirme anahtarıdır.
`number`	string	Hayır	Müşteriye gösterilen kısa sipariş numarası. Gönderilmezse `id` kullanılır.
`status`	string	Hayır	Siparişin sizdeki durumu (serbest metin).
`order_date`	string	Evet	Sipariş tarihi (ISO-8601 veya `Y-m-d H:i:s`).
`url`	string	Hayır	Siparişin kendi panelinizdeki adresi. Doluysa fatura internet satışı olarak işaretlenir ve bu adres web adresi olur.
`currency`	string	Hayır	Para birimi. Boş veya tanınmayan değerlerde `TRY` kabul edilir.
`total`	number	Evet	Sipariş genel toplamı.
`note`	string	Hayır	Müşteri notu.
`customer`	object	Hayır	`id` ve `email` alanlarını taşır; fatura üretilirken müşteri eşleştirmesinde kullanılır.
`payment`	object	Hayır	Ödeme bilgisi — aşağıya bakın.
`billing_address`	object	Evet	Fatura adresi — aşağıya bakın.
`shipping_address`	object	Hayır	Teslimat adresi. Gönderilmezse fatura adresi kopyalanır.
`shipment`	object	Hayır	Kargo bilgisi — aşağıya bakın.
`lines`	array	Evet	Sipariş satırları — aşağıya bakın.

`payment`

Alan	Varsayılan	Açıklama
`method`	`other`	`credit_or_debit`, `direct_transfer`, `cash_on_delivery`, `payment_agent` değerlerinden biri; tanınmayan değerler `other` sayılır — bkz. Sabitler.
`platform`	`custom_feed`	Ödeme altyapısının adı (örn. `iyzico`).
`status`	`paid`	Boş bırakılırsa ödendi kabul edilir; tanınmayan bir değer gönderilirse `failed` olur — bkz. Sabitler.
`date`	—	Ödeme tarihi.

`billing_address`

Fatura bu adresle kesilir; eksik bilgi doğrudan faturaya yansır.

Alan	Varsayılan / kural	Açıklama
`type`	`person`	`person` veya `company`.
`tax_number`	`11111111111`	Boş gönderilirse nihai tüketici kabul edilir ve fatura e-Arşiv olarak kesilir.
`tax_office`	—	Vergi dairesi.
`title`	—	Tüzel kişilerde ünvan. `type: "company"` gönderiyorsanız doldurun.
`name`, `surname`	—	Gerçek kişilerde ad/soyad.
`address`, `city`, `district`	—	Açık adres, il, ilçe.
`country`	`TÜRKİYE`	Ülke.
`phone`	—	Telefon.

`shipping_address`

name, surname, title, address, city, district, country, phone alanlarını alır. Gönderilmezse fatura adresi teslimat adresi olarak kullanılır.

`shipment`

Alan	Kural
`company_title`	Kargo firması ünvanı. Boşsa `courier_name` değeri kullanılır.
`company_tax_number`	Verilmezse firma adı, platformun kargo firması listesinde aranır; orada da bulunamazsa `11111111111` yazılır.
`courier_name`	Kurye adı (firma yerine kurye ile gönderiyorsanız).
`delivery_date`	Teslim tarihi.

shipment nesnesi hiç gönderilmezse fatura, sevkiyat bilgisi olmadan üretilir.

`lines[]`

Alan	Tip	Zorunlu	Açıklama
`id`	string	Hayır	Satırın sizdeki ID’si. Faturaya `lines[].id` olarak taşınır.
`sku`	string	Hayır	Stok kodu.
`name`	string	Evet	Ürün/hizmet adı.
`quantity`	number	Evet	Miktar.
`unit`	string	Hayır	Ölçü birimi kodu. Boş veya tanınmayan değerlerde `C62` (adet) kullanılır — bkz. Sabitler.
`unit_price`	number	Evet	Birim fiyat (KDV hariç).
`tax_rate`	number	Evet	KDV oranı.
`discount`	number	Hayır	İndirim; gönderilmezse `0`.
`discount_type`	string	Hayır	`amount` veya `percentage`. Gönderilmezse indirim varsa `amount` kabul edilir.
`description`	string	Hayır	Satır açıklaması.

KDV oranı 0 olan satırlar için varsayılan istisna kodunu tanımlayın

Feed satırlarında istisna kodu alanı yoktur. tax_rate: 0 gönderdiğiniz satırlar faturaya dönüştürülürken Ayarlar → Varsayılanlar altındaki istisna kodu ve gerekçesi uygulanır. Bu varsayılan boşsa fatura oluşturma adımı KDV oranı 0 olan ürünlerde istisna kodu zorunludur. hatasıyla durur.

Satır bazında farklı istisna kodları kullanmanız gerekiyorsa feed yerine sipariş oluşturma + siparişten fatura oluşturma akışını tercih edin; orada exemption_code ve exemption_reason alanlarını satır satır gönderebilirsiniz. Kod listesi: Sabitler.

Tam örnek yanıt

{
  "orders": [
    {
      "id": "ORD-2026-0001",
      "number": "1001",
      "status": "completed",
      "order_date": "2026-07-30T12:30:00.000Z",
      "url": "https://ornek-magaza.com/siparis/ORD-2026-0001",
      "currency": "TRY",
      "total": 1150,
      "customer": {
        "id": "CUST-42",
        "email": "ahmet@example.com"
      },
      "payment": {
        "method": "credit_or_debit",
        "platform": "iyzico",
        "status": "paid",
        "date": "2026-07-30T13:30:00.000Z"
      },
      "note": "Teslimattan önce arayın.",
      "billing_address": {
        "type": "person",
        "name": "Ahmet",
        "surname": "Yılmaz",
        "title": null,
        "tax_number": "",
        "tax_office": null,
        "address": "Örnek Mah. Deneme Sok. No:1 D:2",
        "district": "Kadıköy",
        "city": "İstanbul",
        "country": "TÜRKİYE",
        "phone": "+905551112233"
      },
      "shipping_address": {
        "name": "Ahmet",
        "surname": "Yılmaz",
        "title": null,
        "address": "Örnek Mah. Deneme Sok. No:1 D:2",
        "district": "Kadıköy",
        "city": "İstanbul",
        "country": "TÜRKİYE",
        "phone": "+905551112233"
      },
      "shipment": {
        "company_title": "Yurtiçi Kargo",
        "company_tax_number": "9860008925",
        "delivery_date": "2026-07-31T12:30:00.000Z"
      },
      "lines": [
        {
          "id": "LINE-1",
          "sku": "SKU-001",
          "name": "Kablosuz Kulaklık",
          "quantity": 1,
          "unit": "C62",
          "unit_price": 1000,
          "tax_rate": 20,
          "discount": 50,
          "discount_type": "amount",
          "description": null
        },
        {
          "id": "LINE-2",
          "sku": "SKU-002",
          "name": "Kulaklık Kılıfı",
          "quantity": 1,
          "unit": "C62",
          "unit_price": 200,
          "tax_rate": 20,
          "discount": 0,
          "discount_type": null,
          "description": "Hediye paketi yapılacak"
        }
      ]
    },
    {
      "id": "ORD-2026-0002",
      "number": "1002",
      "status": "processing",
      "order_date": "2026-07-29T12:30:00.000Z",
      "url": "https://ornek-magaza.com/siparis/ORD-2026-0002",
      "currency": "TRY",
      "total": 5400,
      "customer": {
        "id": "CUST-77",
        "email": "satinalma@ornekas.com.tr"
      },
      "payment": {
        "method": "direct_transfer",
        "platform": null,
        "status": "pending",
        "date": null
      },
      "note": null,
      "billing_address": {
        "type": "company",
        "name": "Zeynep",
        "surname": "Kaya",
        "title": "Örnek Bilişim A.Ş.",
        "tax_number": "1234567890",
        "tax_office": "Maslak",
        "address": "Teknokent Blok B No:12",
        "district": "Sarıyer",
        "city": "İstanbul",
        "country": "TÜRKİYE",
        "phone": "+902121234567"
      },
      "shipment": {
        "company_title": "MNG Kargo",
        "company_tax_number": "6080712084",
        "delivery_date": null
      },
      "lines": [
        {
          "id": "LINE-3",
          "sku": "SKU-100",
          "name": "Mekanik Klavye",
          "quantity": 3,
          "unit": "C62",
          "unit_price": 1800,
          "tax_rate": 20,
          "discount": 0,
          "discount_type": null,
          "description": null
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total_pages": 3
  }
}

Tekrar aktarım ve güncelleme

Siparişler id (panelde platform_id) değerine göre eşleştirilir:

Yeni id → yeni sipariş oluşturulur. Otomatik faturalama açıksa fatura bu anda kuyruğa alınır.
Var olan id → sipariş güncellenir; satırlar silinip yeniden yazılır, adres ve kargo bilgileri üzerine yazılır. Otomatik faturalama yeniden tetiklenmez.

Bu yüzden feed'inizin bir siparişi her seferinde tam (bütün satırlarıyla) döndürmesi gerekir; kısmi güncelleme desteklenmez.

Bildirim adresi (webhook)

Kanal ayarında Bildirim Adresi doldurduysanız, fatura oluşturulduğunda ve silindiğinde bu adrese POST ile JSON gönderilir. Gövde şu şekildedir:

Fatura oluşturuldu

{
  "event": "invoice.created",
  "order_id": "ORD-2026-0001",
  "invoice": {
    "id": 812,
    "ettn": "3f2a9c14-77b1-4d2e-9a55-0c1b8e6d2f10",
    "serial_number": "GIB2026000000812",
    "formal_status": "completed",
    "pdf_url": "https://app.faturaentegrator.com/storage/pdf/812.pdf"
  }
}

Fatura silindi

{
  "event": "invoice.removed",
  "order_id": "ORD-2026-0001"
}

order_id, feed'de gönderdiğiniz sipariş id değeridir. Uç noktanızın 2xx döndürmesi beklenir; aksi hâlde panelde bildirim hatası kaydedilir.

Faturanın kendisini takip etmek için callback da kullanabilirsiniz

Bildirim adresi, sipariş bazlı ve JSON Feed kanalına özeldir. Fatura durumunun her değişiminde bildirim almak isterseniz fatura gövdesindeki callback_url alanını kullanın.

Sorun giderme

Belirti	Olası neden
“Feed bağlantısı doğrulanamadı”	Adres `200` dönmüyor ya da yanıtın kökünde `orders` dizisi yok. Yetkilendirme bilgilerini ve `Content-Type: application/json` başlığını kontrol edin.
Siparişler panele düşmüyor	`orders[].id` boş olabilir — bu kayıtlar atlanır. `total_pages` değerini yanlış verdiyseniz sonraki sayfalar hiç istenmez.
Sipariş var, fatura oluşmuyor	Otomatik faturalama kapalı olabilir; ya da KDV `0` satırlarda varsayılan istisna kodu tanımlı değildir.
Ödeme durumu hep “Hatalı” görünüyor	`payment.status` tanınmayan bir değer taşıyor; geçerli değerler için bkz. Sabitler.
Fatura yanlış adrese kesiliyor	`billing_address` eksik gönderilmiş olabilir; teslimat adresi değil fatura adresi kullanılır.

Nasıl çalışır?​

Platformun feed'e attığı istek​

Yetkilendirme​

Feed'in döndürmesi gereken yanıt​

pagination​

orders[] alanları​

payment​

billing_address​

shipping_address​

shipment​

lines[]​

Tam örnek yanıt​

Tekrar aktarım ve güncelleme​

Bildirim adresi (webhook)​

Sorun giderme​