Satış Oluştur

POST /v1/integrations/orders

Siparişi Finans Fatura tarafında bir satış kaydına dönüştürür. Ürünler barkod veya stok koduyla eşlenir, alıcı bilgileri satışın üzerine yazılır, satış mükellefin ciro ve stok raporlarına girer.

Bu, entegrasyonun ilk ve zorunlu adımıdır.

İstek

POST /v1/integrations/orders

{
  "provider": "ECOMSOFT",
  "external_id": "ORD-2026-00184",
  "order_number": "184",
  "ordered_at": "2026-08-16T11:20:00Z",
  "payment_status": "PAID",
  "currency": "TRY",
  "total_price": 1200,
  "buyer": {
    "title": "Test Müşteri",
    "tckn": "11111111111",
    "email": "[email protected]",
    "phone": "5551112233",
    "address": "Kadıköy / İstanbul"
  },
  "lines": [
    {
      "external_line_id": "L1",
      "sku": "SRV-001",
      "barcode": "8690000000001",
      "title": "Danışmanlık hizmeti",
      "quantity": 1,
      "unit_price": 1200,
      "total_price": 1200,
      "vat_rate": 20,
      "discount": 0
    }
  ]
}

Gövde alanları

Alan	Tip	Zorunlu	Açıklama
external_id	string	✅	Sizin sisteminizdeki sipariş kimliği. Tekrarlı gönderimi engelleyen anahtar.
lines	dizi	✅	En az bir satır.
provider	string	—	Kaynak markası. Bkz. Kaynak etiketi.
order_number	string	—	Mükellefin gördüğü sipariş numarası.
customer_name	string	—	Alıcı adı (görüntüleme için).
ordered_at	RFC 3339	—	Sipariş tarihi. Boşsa istek anı.
status	string	—	Sizdeki sipariş durumu (bilgi amaçlı).
payment_status	string	—	PAID | PENDING. Boşsa PAID.
currency	string	—	Boşsa TRY. TRY dışıysa bkz. Döviz ve kur.
exchange_rate	sayı	—	1 birim currency kaç TL. Boş ya da 0 gönderirseniz bizim kurumuzu kullanırız. Bkz. Döviz ve kur.
exchange_rate_source	string	—	TCMB | MANUAL. Boşsa MANUAL.
exchange_rate_date	string	—	Kurun ait olduğu gün (27.09.2026).
total_price	sayı	—	Sipariş toplamı.
invoice_exemption_code	string	—	KDV istisna kodu (GİB 2xx/3xx). %0 KDV'li satır varsa gerekli — bkz. KDV istisnası.
invoice_exemption_reason	string	—	İstisna kodunun metni. Kodla birlikte gönderilir.
buyer	nesne	✅	Fatura alıcısı. Satışın üzerine yazılır. Bkz. Alıcı.

Satır alanları (lines[])

Alan	Tip	Zorunlu	Açıklama
title	string	✅	Ürün adı. Faturada bu isim görünür.
quantity	sayı	✅	Miktar.
sku	string	—	Stok kodu. Ürün eşlemede kullanılır.
barcode	string	—	Barkod. Eşlemede önceliklidir.
external_line_id	string	—	Sizdeki satır kimliği.
unit_price	sayı	—	Birim fiyat (KDV dahil).
total_price	sayı	—	Satır toplamı (KDV dahil). Boşsa unit_price × quantity.
vat_rate	sayı	—	KDV oranı, yüzde olarak (20).
discount	sayı	—	Satır indirimi.

Fiyatlar KDV dahil gönderilir

Bu uçta unit_price ve total_price KDV dahil tutarlardır. KDV, orana göre bu tutarın içinden ayrıştırılır.

Fatura kesme ucundaki canonical gövdesi ise KDV hariç çalışır. İki ucu karıştırmayın — en sık yapılan hata budur.

Alıcı

{
  "title": "Örnek Ticaret A.Ş.",
  "contact_name": "Ayşe Yılmaz",
  "email": "[email protected]",
  "phone": "5551112233",
  "tckn": "",
  "tax_number": "1234567890",
  "tax_office": "Kadıköy",
  "address": "Caferağa Mah. ... Kadıköy / İstanbul"
}

Alan	Zorunlu	Belgedeki karşılığı
title	✅	Unvan / Ad Soyad. Boşsa contact_name kullanılır; ikisi de boşsa istek 400 döner.
contact_name	—	Yetkili kişi. title boşsa unvan yerine geçer.
tckn	—	VKN/TCKN — bireysel alıcı (11 hane).
tax_number	—	VKN/TCKN — kurumsal alıcı (10 hane). İkisi birden gelirse bu kazanır.
tax_office	—	Vergi dairesi. Kurumsal alıcıda tax_number ile birlikte gönderin.
address	—	Adres.
email	—	E-posta. e-Arşiv'de belgenin gönderim şeklini belirler, bkz. E-posta.
phone	—	Telefon.

Alıcı bilgisi nerede durur

Gönderdiğiniz alıcı, satış kaydının üzerine kopyalanır — belgenin fatura alıcısı odur. Fatura kesilirken alıcı bu bilgiden kurulur; mükellefin elle girmesi gerekmez.

Cari hesap açılmaz. Eskiden her alıcı için bir cari kartı aranır, yoksa oluşturulurdu; artık öyle değil. Tek seferlik e-ticaret alıcıları cari listesini şişiriyordu ve satışın kayda geçmesi için gereken şey zaten alıcının kendisiydi, bir kart değil. Borç/ödeme takibi istediğiniz alıcılar için cari kartı panelden açılır ve satışla ilişkilendirilir.

Kopya olması kasıtlıdır: belge, kesildiği andaki alıcıyı taşır. Alıcının bilgisi sonradan değişse de kesilmiş belgenin üzerindeki bilgi değişmez.

Kimlik: VKN ve TCKN tek alandır

İstekte ikisini ayrı gönderirsiniz (hangisi olduğunu bilen taraf sizsiniz), belgede tek bir kimlik alanı vardır. İkisi birden geldiyse tax_number kazanır — belge kuruma kesilir.

Kimlik zorunlu değildir; kanalınız tutmuyor olabilir (Shopify fatura adresinde VKN/TCKN tutmaz). Ama gönderebiliyorsanız gönderin: e-Fatura mükellefi olan bir alıcının belgesi ancak kimliği varken GİB'de sorgulanıp e-Faturaya yükseltilir, aksi hâlde mükellef VKN'yi fatura ekranında elle girer.

E-posta

email nezaket alanı değildir: e-Arşiv belgesinde GİB'in zorunlu tuttuğu gönderim şekli (EREPSENDT) bu alandan türetilir — e-posta varsa ELEKTRONIK, yoksa KAGIT olarak beyan edilir. Son tüketiciye belgeyi e-posta ile ulaştırmak istiyorsanız alıcının e-postasını göndermeniz gerekir.

Alıcı zorunlu

buyer göndermezseniz ya da unvan çıkmazsa satış oluşmaz, istek 400 döner: alan hiç yoksa ERROR_VALIDATION (errors[].field = "buyer"), varsa ama adlandıramıyorsa ERROR_BUYER_TITLE_REQUIRED. Kimlik (tckn / tax_number) zorunlu değildir — kanalınız tutmuyor olabilir — ama belgeyi taşıyacak bir title (ya da contact_name) şarttır: alıcısız bir belge kesilemez.

Yanıt

201 Created

{
  "imported": true,
  "already_imported": false,
  "integration_id": 42,
  "external_id": "ORD-2026-00184",
  "transaction_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "currency": "USD",
  "exchange_rate": 41.37,
  "exchange_rate_source": "TCMB",
  "exchange_rate_date": "27.09.2026"
}

Dövizli satışta hangi kuru kullandığımız yanıtta döner — kendi kurunuzu gönderdiyseniz o (MANUAL), göndermediyseniz bizimki (TCMB). TRY satışta bu alanlar hiç dönmez.

transaction_id, oluşan satışın kimliğidir. Faturayı hemen kesecekseniz bu değeri fatura ucuna transaction_header_id olarak geçirin.

Döviz ve kur

TRY dışı bir satışın faturası, TL karşılığının türetildiği kur olmadan kesilemez: mevzuat yurt içi alıcıda TL karşılığını şart koşuyor ve GİB görüntüleyicisi TL tutarları bu kurdan hesaplıyor.

Kuru siz belirleyebilirsiniz, belirlemek zorunda da değilsiniz:

Gönderdiğiniz exchange_rate	Ne olur
yok ya da 0	Bizim kurumuzu kullanırız (TCMB döviz alış). Yanıtta exchange_rate_source: "TCMB" döner.
> 0	Sizin kurunuz aynen kullanılır, MANUAL olarak işaretlenir. TCMB ile karşılaştırılmaz.

Kur uydurulmaz: TCMB bülteni o para birimini taşımıyorsa istek ERROR_EXCHANGE_RATE_REQUIRED ile döner ve kuru sizden ister. Kimsenin seçmediği bir rakamla belge çıkmasındansa satış beklemede kalır.

TCMB bülteninin takvimi

Bülten hafta içi ~15:30'da yayımlanır, hafta sonu yayımlanmaz. Pazartesi sabahı kesilen bir belge cumanın bültenini taşır — yanıtta dönen exchange_rate_date bunu açık eder. Satır tutarları sipariş para biriminde kalır; çevrilmez.

İadede kur TCMB'den alınmaz: iade asıl satışın kurunu tekrar eder, yeni bir kur belirlemez. exchange_rate göndermezseniz asıl satışın kurunu kendimiz buluruz — aylar önceki bir satışı bugünün kuruyla iade etmek yanlış beyandır.

KDV istisnası

%0 KDV'li bir satır, istisna sebebi olmadan faturalanamaz. GİB şematronu sebebi olmayan %0 KDV'li satırı reddediyor.

İstisna belge genelinde tek koddur, satır bazında değil — bir mükellef pratikte tek istisna türüyle çalışır (ihracatçı hep "11/1-a mal ihracatı"). Kod yalnız %0 KDV'li satırlara iliştirilir; KDV'li satıra dokunulmaz, yoksa karışık belgede istisna beyanı vergili satırı da kapsamış görünürdü.

{
  "currency": "USD",
  "invoice_exemption_code": "301",
  "invoice_exemption_reason": "11/1-a Mal ihracatı",
  "lines": [
    { "title": "Danışmanlık", "quantity": 1, "unit_price": 1000, "vat_rate": 0 }
  ]
}

Kod 2xx (kısmi istisna, KDVK md. 17) ya da 3xx (tam istisna, iade hakkı doğurur) olmalıdır. Listede olmayan bir kod reddedilmez — GİB'in tam kod listesi geniştir ve son söz şematronundur.

Göndermezseniz istek kabul edilir, satış oluşur, ama faturası kesilemez: belge ERROR_INVOICE_ZERO_VAT_NEEDS_EXEMPTION ile durur ve mükellef kodu panelden seçerek kesebilir. Kanalınız GİB istisna kodunu tutmuyorsa bu kasıtlı çıkış yoludur — satışı kaybetmemek için.

Fatura tipini göndermeyin: sunucu satırlardan türetir (%0 KDV → ISTISNA).

Tekrarlı gönderim

Aynı external_id ikinci kez gönderilirse yeni satış oluşmaz:

200 OK

{
  "imported": false,
  "already_imported": true,
  "integration_id": 42,
  "external_id": "ORD-2026-00184",
  "transaction_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
}

Bu bir hata değildir. Webhook tekrarları ve retry'lar için güvenle kullanabilirsiniz — 201 yerine 200 alırsanız kayıt zaten bizde demektir.

Kaynak etiketi

provider alanı, satışın nereden geldiğini işaretler. Mükellef, panelindeki satış listesinde kaynağı görür.

• Finans Fatura mağazasında kayıtlı bir markaysa, satış sizin logonuzla listelenir
• Tanınmayan bir değer gönderilirse kaynak FINANSFATURA olarak görünür — istek reddedilmez

Markanızın kayıtlı hâle gelmesi için Partner Programı'na bakın.

Sınırlar

• Satırlarda para birimi karışımı desteklenmez; tüm satırlar currency ile aynı para biriminde olmalıdır
• Tevkifat ve özel matrah bu uçta gönderilmez: ikisi de satır bazındadır ve satışın değil belgenin özelliğidir — fatura ucunda gönderilir
• Sipariş iptali ve iade bu uçta ele alınmaz; oluşmuş satış panelden düzenlenir