Değişiklik günlüğü ve kullanımdan kaldırma politikası

Neye güvenebileceğinizi önceden bilmeden entegrasyon inşa edilmez. Politika sözleşmenin parçasıdır.

Kullanımdan kaldırma politikası

  • 12 ay bildirim. Kırıcı bir değişiklik, ilanından en az on iki ay sonra yürürlüğe girer. Kırıcı sayılanlar: bir ucun ya da alanın kaldırılması, bir alanın tipinin ya da anlamının değişmesi, yeni bir zorunlu parametre, mevcut bir isteğin artık hata döndürmesi.
  • Deprecation ve Sunset başlıkları. Kullanımdan kaldırılan bir yüzey, o günden itibaren her yanıtında Deprecation: true ve Sunset (RFC 8594 biçiminde kapanış tarihi, örn. Mon, 04 Jan 2027 00:00:00 GMT) başlıklarını taşır. Deprecation bir TARİH DEĞİLDİR, yalnız bayraktır. Bugün bu ikili yalnız panelin emekli yetki kodları için basılıyor; /v1’de uç ya da alan emekliliğinde aynı biçim kullanılacaktır. Kapanışı öğrenmek için bu sayfayı izlemek zorunda değilsiniz — istemciniz kendi loglarından görür.
  • Sessiz davranış değişikliği asla. Yanıtın anlamını değiştiren hiçbir şey duyurusuz yapılmaz. Bu, kırıcı bir değişiklikten sonra verilen bir söz değildir; yayımlanmış olmasının sebebi de budur.
  • Bunlar kırıcı DEĞİLDİR ve istemciniz bunlara dayanıklı olmalıdır: yanıta yeni bir alan eklenmesi, yeni bir uç ya da yeni bir opsiyonel parametre, mevcut bir sözlüğe (örn. status_detail) yeni bir değerin girmesi, hata mesajı metninin değişmesi. Bilinmeyen alanları yok sayın, bilinmeyen kodlara “diğer” deyin.
  • Yol versiyonlanır. Uyumsuz bir sözleşme /v1’i değiştirmez, /v2 olarak doğar.

Günlük

1.0.2 — Yayın öncesi uyum düzeltmeleri (2026-09-28)

  • Bu sürümdeki değişiklikler, henüz bu API’yi kullanan bir entegrasyon bulunmadığı için 12 aylık bildirim süresi beklenmeden hemen yürürlüğe girdi. Aşağıdaki her madde, önceden farklı davranan bir isteğin bugünkü davranışını anlatır.
  • Sayfalama: son sayfada `meta.next_cursor` artık `null` gelir. Önceden tam dolu son sayfa, boş bir sayfaya götüren bir imleç döndürüyordu.
  • 2 MiB’ı aşan istek gövdesi `400 validation_failed` alır.
  • `GET /v1/openapi.yaml` `include`, `filter` ve `sort` parametrelerini `400 validation_failed` ile reddeder.
  • Sözleşme artık kimlik doğrulama başlıklarını, her operasyonun hata yanıtlarını ve oran sınırı başlıklarını tanımlar. Yazma uçlarında 409 `conflict` ve 422 `invalid_state` yanıtları operasyon bazında listelenir.
  • Anahtarsız istek, diğer kimlik hatalarıyla aynı standart `401 unauthorized` gövdesini alır.
  • `/v1` altında tanımlı olmayan bir yol ya da metot, düz metin yerine JSON gövdeli `404 not_found` alır.
  • Doğrulama hatalarında `details.field` her zaman istek gövdesindeki alanın adını taşır (ör. `items[1].product_id`).
  • Sözlük dışı değerler alan adıyla reddedilir: cari `type` ve `person_type`, ürün `type`, fatura `invoice_type` ve `scenario`. Fatura oluştururken `invoice_type` ve `scenario` artık zorunludur.
  • Fatura `currency` büyük harfli bir ISO 4217 kodu olmalıdır ve taslak oluşturulurken denetlenir.
  • Fatura kalemi: UUID olmayan `product_id`, boş `name`, sıfır ya da negatif `quantity` ve negatif `unit_price` 400 alır.
  • Cari kartı: PATCH ile kartın tipinden farklı bir `type` göndermek 400 alır. Silinmiş bir carinin kişisi üzerindeki PATCH ve DELETE 404 döner.
  • Ürün: UUID olmayan `category_id` 400 alır; PATCH `code`, `name` ve `unit` alanlarını boşaltamaz.
  • Etiket: başka bir firmaya ait `group_id` 400 alır.
  • Ödeme: iki ondalıktan fazla basamaklı `amount` 400 alır; başka bir firmanın banka hesabı artık 500 yerine `400 validation_failed` (`field: bank_account_id`) döner.
  • İptal edilmiş (`status: cancelled`) ya da alıcının reddettiği (`status: rejected`) faturaya yeni ödeme işlenmez, `409 conflict` döner. Önceden ödeme kabul ediliyordu. Daha önce işlenmiş bir ödeme yine geri alınabilir.
  • Cari kartında adres: `Contact` yanıtına ve cari oluşturma/güncelleme gövdesine `address` nesnesi eklendi (`line`, `neighborhood`, `district`, `city`, `postal_code`, `country`). Güncellemede adres alan alan birleştirilir, boş dize o alanı siler. e-Fatura ve e-Arşiv gönderimi alıcının il ve ilçesini ister; artık bu bilgi API üzerinden de girilebilir.
  • Cari kartında `tax_number` 10 haneli, `national_id` 11 haneli olmalı ve kontrol basamağı tutmalıdır; tutmayan değer 400 alır. Nihai tüketici kimliği `11111111111` ve yurt dışındaki alıcının VKN’si `2222222222` bu kuralın istisnasıdır.
  • İletişim kişisinde `email` biçimi denetlenir; geçersiz değer 400 alır, boş dize alanı temizler.
  • Ürün: `unit` sözleşmedeki birim kodlarından biri ya da firmanın panelde tanımladığı aktif bir birim olmalıdır; `currency` büyük harfli ISO 4217 kodu, `vat_rate` 0, 1, 8, 10, 18 ya da 20 olmalıdır. Negatif `unit_price` 400 alır; saklanamayacak kadar büyük ya da ikiden fazla ondalık haneli `unit_price` de `field: unit_price` ile 400 alır; önceden fazla haneler sessizce yuvarlanıyordu.
  • Fatura kaleminde `vat_rate` de aynı listeden olmalıdır (0, 1, 8, 10, 18, 20).
  • Stok kategorisi: aynı adla ikinci bir kategori `400 validation_failed` yerine `409 conflict` (`field: name`) alır. Etiketlerde aynı ad serbest kalır.
  • Stok hareketi: bilinmeyen bir ürün `404 not_found` yerine `400 validation_failed` (`field: items[i].product_id`) alır. Hizmet tipi ürün içeren kalem aynı alanla reddedilir ve mesaj hareketin türünü söyler (önceden her türde transfer mesajı dönüyordu).
  • Sözleşme metni: `invoice_type` ve `scenario` kabul edilen değerleriyle yayımlandı, `Product.unit` gerçek birim sözlüğünü anlatır, açıklamalardaki iç sistem adları kaldırıldı.

1.0.1 — Kırıcı değişiklik: e-Arşiv iptali (2026-09-28)

  • `POST /v1/invoices/{id}/cancel`, GİB’e ulaşmış e-Arşiv faturası: `objection_type` artık yalnız `GIB` olabilir. `KEP`, `NOTER`, `TAAHHUTLU_MEKTUP`, `MYSOFT_PORTAL` ve `YOK` `400 validation_failed` (`field: objection_type`) döner ve fatura iptal edilmez. Önceden bu istekler 200 dönüyor, iptal yalnız bizim kaydımızda kalıyordu.
  • Aynı uçta GİB’e ulaşmış e-Arşiv iptali artık GİB’e iptal raporuyla bildiriliyor. Bu yüzden iki istek daha hata döndürür: belge tarihinden 8 gün sonra yapılan iptal `invalid_state`, bugünden farklı bir `cancel_date` `validation_failed` alır.
  • Neden 12 aylık bildirim beklenmedi: GİB’e ulaşmış bir e-Arşiv faturası dış kanaldaki bir itirazla GİB’de iptal olmaz. Eski davranış GİB’de geçerli kalan faturayı iptal edilmiş gösteriyordu.
  • e-Fatura ve GİB’e ulaşmamış e-Arşiv için kabul edilen değerler değişmedi.

1.0.0 — İlk yayın (2026-09)

  • `/v1` okuma yüzeyi: me, contacts (+ ledger, people), products (+ inventory-levels), stock-movements, warehouses, item-categories, tags, invoices (+ payments), inbox-invoices, receipts, despatches, e-invoice-inboxes, accounts (+ transactions), exchange-rates, units.
  • `/v1` yazma yüzeyi: cari, carinin iletişim kişisi, stok kartı, kategori ve etiket için oluşturma/güncelleme/silme; stok hareketi yalnız oluşturma; fatura oluşturma/güncelleme/silme, gönderim (202, asenkron) ve iptal; faturaya ödeme işleme ve geri alma.
  • Anahtar başına kapsam seçimi: anahtar yalnız kendisine verilen yetkileri taşır. Belge silme ve iptal varsayılan kümede yoktur, açıkça istenir.
  • Anahtar başına dakikada 60 istek, `X-RateLimit-*` ve 429’da `Retry-After` başlıklarıyla.
  • Sözleşmenin kendisi uçtan yayımlanır: `GET /v1/openapi.yaml`.

Bugüne kadar kullanımdan kaldırılmış bir uç ya da alan yoktur. Olduğunda burada, kaldırma tarihiyle birlikte durur ve kayıt silinmez.