openapi: 3.0.3 info: title: 'ON Muhasebe Genel API Dokümantasyonu' description: 'ON Muhasebe genel REST API (v1): cariler, ürünler, faturalar (e-Fatura dahil) ve siparişler için programatik erişim.' version: 1.0.0 servers: - url: 'http://localhost:18000' tags: - name: Cariler description: "\nMüşteri ve tedarikçi (cari) kayıtlarının listelenmesi, görüntülenmesi,\noluşturulması, güncellenmesi ve hesap hareketlerinin sorgulanması." - name: Faturalar description: "\nFatura (e-Fatura/e-Arşiv dahil) listeleme, görüntüleme, taslak oluşturma,\ne-Fatura sağlayıcısına kaydetme/gönderme ve durum sorgulama işlemleri." - name: Giderler description: "\nGider kayıtlarının listelenmesi, görüntülenmesi, oluşturulması, güncellenmesi\nve onay/ret durum geçişlerinin yönetilmesi." - name: Kasa/Banka description: "\nKasa ve banka hesaplarının listelenmesi, görüntülenmesi, oluşturulması,\ngüncellenmesi; hesap hareketlerinin (giriş/çıkış) ve hesaplar arası\ntransferlerin yönetimi." - name: Makbuzlar description: "\nSerbest Meslek Makbuzu (SMM) ve Müstahsil Makbuzu (MM) kayıtlarının\nlistelenmesi, görüntülenmesi, oluşturulması, güncellenmesi, gönderilmesi\nve iptal edilmesi. Stopaj/KDV/net/ödenecek tutarları servis hesaplar." - name: Siparişler description: "\nPazaryeri ve doğrudan siparişlerin listelenmesi, görüntülenmesi, oluşturulması,\ngüncellenmesi ve durum geçişlerinin yönetilmesi." - name: Çekler description: "\nÇek ve senet kayıtlarının listelenmesi, oluşturulması, güncellenmesi ve\ntahsilat/ödeme/ciro/karşılıksız gibi durum geçişlerinin yönetilmesi." - name: Ürünler description: "\nÜrün ve hizmet kataloğunun listelenmesi, görüntülenmesi, oluşturulması ve güncellenmesi." components: securitySchemes: default: type: apiKey name: X-Api-Key in: header description: 'Her istekte **iki başlık** birlikte gönderilmelidir: `X-Api-Key` (API anahtarınız) ve `X-Api-Secret` (API gizli anahtarınız). `X-Api-Secret` başlığı da zorunludur ancak yukarıdaki örneklerde yalnızca `X-Api-Key` gösterilir; isteğinize `X-Api-Secret: {API_GIZLI_ANAHTARINIZ}` başlığını da eklemeyi unutmayın. Anahtar çiftinizi panelinizden API Anahtarı Oluştur ile edinebilirsiniz. Erişebileceğiniz uç noktalar anahtarınıza tanımlı scope (yetki kapsamı) ile sınırlıdır.' security: - default: [] paths: /api/public/v1/parties: get: summary: 'Carileri listele' operationId: carileriListele description: 'Cari kayıtlarını sayfalı olarak döner. Ad, kod veya VKN üzerinden arama yapılabilir.' parameters: - in: query name: query description: 'Ad, kod veya VKN içinde arama terimi.' example: 'Örnek Ltd' required: false schema: type: string description: 'Ad, kod veya VKN içinde arama terimi.' example: 'Örnek Ltd' - in: query name: status description: 'Duruma göre filtre (aktif, pasif).' example: aktif required: false schema: type: string description: 'Duruma göre filtre (aktif, pasif).' example: aktif - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Başarılı liste' content: application/json: schema: type: object example: data: - id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: 'Örnek Yazılım Ltd. Şti.' code: MUS-AB12CD34 type: kurumsal kind: musteri status: aktif vkn: '1234567890' tckn: null taxOffice: Kadıköy isEfaturaUser: true email: muhasebe@ornek.com phone: '+902161234567' currentBalance: '1500.00' createdAt: '2026-01-15T09:30:00+00:00' meta: currentPage: 1 lastPage: 5 perPage: 20 total: 92 properties: data: type: array example: - id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: 'Örnek Yazılım Ltd. Şti.' code: MUS-AB12CD34 type: kurumsal kind: musteri status: aktif vkn: '1234567890' tckn: null taxOffice: Kadıköy isEfaturaUser: true email: muhasebe@ornek.com phone: '+902161234567' currentBalance: '1500.00' createdAt: '2026-01-15T09:30:00+00:00' items: type: object properties: id: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: type: string example: 'Örnek Yazılım Ltd. Şti.' code: type: string example: MUS-AB12CD34 type: type: string example: kurumsal kind: type: string example: musteri status: type: string example: aktif vkn: type: string example: '1234567890' tckn: type: string example: null nullable: true taxOffice: type: string example: Kadıköy isEfaturaUser: type: boolean example: true email: type: string example: muhasebe@ornek.com phone: type: string example: '+902161234567' currentBalance: type: string example: '1500.00' createdAt: type: string example: '2026-01-15T09:30:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 5 perPage: type: integer example: 20 total: type: integer example: 92 tags: - Cariler post: summary: 'Cari oluştur' operationId: cariOlutur description: "Yeni bir müşteri veya tedarikçi kaydı oluşturur. `code` gönderilmezse\ncari türüne göre otomatik üretilir. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: 'Örnek Yazılım Ltd. Şti.' code: MUS-AB12CD34 type: kurumsal kind: musteri status: aktif vkn: '1234567890' tckn: null taxOffice: Kadıköy isEfaturaUser: true email: muhasebe@ornek.com phone: '+902161234567' currentBalance: '0.00' createdAt: '2026-01-15T09:30:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: type: string example: 'Örnek Yazılım Ltd. Şti.' code: type: string example: MUS-AB12CD34 type: type: string example: kurumsal kind: type: string example: musteri status: type: string example: aktif vkn: type: string example: '1234567890' tckn: type: string example: null nullable: true taxOffice: type: string example: Kadıköy isEfaturaUser: type: boolean example: true email: type: string example: muhasebe@ornek.com phone: type: string example: '+902161234567' currentBalance: type: string example: '0.00' createdAt: type: string example: '2026-01-15T09:30:00+00:00' 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: name: - 'Ad alanı zorunludur.' properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: name: type: array example: - 'Ad alanı zorunludur.' items: type: string tags: - Cariler requestBody: required: true content: application/json: schema: type: object properties: kind: type: string description: 'Cari türü (musteri, tedarikci).' example: musteri code: type: string description: 'Tenant içinde benzersiz kod (boş bırakılırsa otomatik).' example: MUS-AB12CD34 name: type: string description: 'Cari ünvanı/adı (2-190 karakter).' example: 'Örnek Yazılım Ltd. Şti.' type: type: string description: 'Tüzel yapı (kurumsal, bireysel).' example: kurumsal vkn: type: string description: 'Vergi kimlik numarası (10 hane).' example: '1234567890' nullable: true tckn: type: string description: 'TC kimlik numarası (11 hane).' example: '12345678901' nullable: true taxOffice: type: string description: 'Vergi dairesi.' example: Kadıköy nullable: true email: type: string description: 'E-posta adresi.' example: muhasebe@ornek.com nullable: true phone: type: string description: 'Telefon numarası.' example: '+902161234567' nullable: true mobile: type: string description: 'Cep telefonu.' example: '+905321234567' nullable: true contactPerson: type: string description: 'Must not be greater than 120 characters.' example: j nullable: true address: type: string description: 'Açık adres.' example: 'Bağdat Cad. No:1' nullable: true city: type: string description: İl. example: İstanbul nullable: true district: type: string description: İlçe. example: Kadıköy nullable: true postalCode: type: string description: 'Must not be greater than 10 characters.' example: hwaykc nullable: true country: type: string description: 'ISO 3166-1 alpha-2 ülke kodu.' example: TR nullable: true paymentTerm: type: string description: 'Must not be greater than 80 characters.' example: u nullable: true category: type: string description: 'Must not be greater than 80 characters.' example: w nullable: true status: type: string description: 'Durum (aktif, pasif).' example: aktif nullable: true riskLimit: type: number description: 'Must be at least 0.' example: 67 nullable: true currency: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true notes: type: string description: 'Must not be greater than 5000 characters.' example: q nullable: true customFields: type: object description: '' example: null properties: iban: type: string description: 'Must not be greater than 34 characters.' example: w nullable: true kepEmail: type: string description: 'Must not be greater than 190 characters.' example: imclaughlin@example.org nullable: true website: type: string description: 'Must be a valid URL. Must not be greater than 255 characters.' example: c nullable: true nullable: true isEfaturaUser: type: boolean description: 'Cari e-Fatura mükellefi mi.' example: true nullable: true required: - kind - name - type '/api/public/v1/parties/{party_id}': get: summary: 'Cari görüntüle' operationId: cariGrntle description: 'Tek bir cari kaydının ayrıntılarını döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: 'Örnek Yazılım Ltd. Şti.' code: MUS-AB12CD34 type: kurumsal kind: musteri status: aktif vkn: '1234567890' tckn: null taxOffice: Kadıköy isEfaturaUser: true email: muhasebe@ornek.com phone: '+902161234567' currentBalance: '1500.00' createdAt: '2026-01-15T09:30:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: type: string example: 'Örnek Yazılım Ltd. Şti.' code: type: string example: MUS-AB12CD34 type: type: string example: kurumsal kind: type: string example: musteri status: type: string example: aktif vkn: type: string example: '1234567890' tckn: type: string example: null nullable: true taxOffice: type: string example: Kadıköy isEfaturaUser: type: boolean example: true email: type: string example: muhasebe@ornek.com phone: type: string example: '+902161234567' currentBalance: type: string example: '1500.00' createdAt: type: string example: '2026-01-15T09:30:00+00:00' 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Cariler patch: summary: 'Cari güncelle' operationId: cariGncelle description: 'Var olan bir cari kaydını kısmi olarak günceller. Yalnızca gönderilen alanlar değişir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Güncellendi content: application/json: schema: type: object example: data: id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: 'Örnek Yazılım A.Ş.' code: MUS-AB12CD34 type: kurumsal kind: musteri status: pasif vkn: '1234567890' tckn: null taxOffice: Kadıköy isEfaturaUser: true email: yeni@ornek.com phone: '+902169998877' currentBalance: '1500.00' createdAt: '2026-01-15T09:30:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W name: type: string example: 'Örnek Yazılım A.Ş.' code: type: string example: MUS-AB12CD34 type: type: string example: kurumsal kind: type: string example: musteri status: type: string example: pasif vkn: type: string example: '1234567890' tckn: type: string example: null nullable: true taxOffice: type: string example: Kadıköy isEfaturaUser: type: boolean example: true email: type: string example: yeni@ornek.com phone: type: string example: '+902169998877' currentBalance: type: string example: '1500.00' createdAt: type: string example: '2026-01-15T09:30:00+00:00' tags: - Cariler requestBody: required: false content: application/json: schema: type: object properties: kind: type: string description: '' example: tedarikci enum: - musteri - tedarikci code: type: string description: 'Must be at least 1 character. Must not be greater than 32 characters.' example: b name: type: string description: 'Cari ünvanı/adı.' example: 'Örnek Yazılım A.Ş.' type: type: string description: 'Tüzel yapı (kurumsal, bireysel).' example: kurumsal vkn: type: string description: 'Must be 10 digits.' example: '8225697751' nullable: true tckn: type: string description: 'Must be 11 digits.' example: '82256977571' nullable: true taxOffice: type: string description: 'Must not be greater than 120 characters.' example: g nullable: true email: type: string description: 'E-posta adresi.' example: yeni@ornek.com nullable: true phone: type: string description: 'Telefon numarası.' example: '+902169998877' nullable: true mobile: type: string description: 'Must not be greater than 32 characters.' example: l nullable: true contactPerson: type: string description: 'Must not be greater than 120 characters.' example: j nullable: true address: type: string description: 'Must not be greater than 500 characters.' example: 'n' nullable: true city: type: string description: 'Must not be greater than 80 characters.' example: i nullable: true district: type: string description: 'Must not be greater than 80 characters.' example: k nullable: true postalCode: type: string description: 'Must not be greater than 10 characters.' example: hwaykc nullable: true country: type: string description: 'Must be 2 characters.' example: my nullable: true paymentTerm: type: string description: 'Must not be greater than 80 characters.' example: u nullable: true category: type: string description: 'Must not be greater than 80 characters.' example: w nullable: true status: type: string description: 'Durum (aktif, pasif).' example: pasif riskLimit: type: number description: 'Must be at least 0.' example: 67 nullable: true currency: type: string description: 'Must be 3 characters.' example: wlv nullable: true notes: type: string description: 'Must not be greater than 5000 characters.' example: q nullable: true customFields: type: object description: '' example: null properties: iban: type: string description: 'Must not be greater than 34 characters.' example: w nullable: true kepEmail: type: string description: 'Must not be greater than 190 characters.' example: imclaughlin@example.org nullable: true website: type: string description: 'Must be a valid URL. Must not be greater than 255 characters.' example: c nullable: true nullable: true isEfaturaUser: type: boolean description: 'Cari e-Fatura mükellefi mi.' example: true nullable: true parameters: - in: path name: party_id description: 'The ID of the party.' example: architecto required: true schema: type: string - in: path name: party description: 'Cari kaydının ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: true schema: type: string '/api/public/v1/parties/{party_id}/transactions': get: summary: 'Cari hesap hareketleri' operationId: cariHesapHareketleri description: 'Bir cariye ait hesap hareketlerini (borç/alacak) tarihe göre azalan sırada, sayfalı döner.' parameters: - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: - id: 01JQ7ZBTX0000000000000000A partyId: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W date: '2026-01-20' type: borc refNo: SIP-2026-000045 refType: invoice refId: 01JQ7ZC000000000000000000B description: 'Satış faturası' debit: '1500.00' credit: '0.00' balanceAfter: '1500.00' createdAt: '2026-01-20T12:00:00+00:00' meta: currentPage: 1 lastPage: 3 perPage: 20 total: 47 properties: data: type: array example: - id: 01JQ7ZBTX0000000000000000A partyId: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W date: '2026-01-20' type: borc refNo: SIP-2026-000045 refType: invoice refId: 01JQ7ZC000000000000000000B description: 'Satış faturası' debit: '1500.00' credit: '0.00' balanceAfter: '1500.00' createdAt: '2026-01-20T12:00:00+00:00' items: type: object properties: id: type: string example: 01JQ7ZBTX0000000000000000A partyId: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W date: type: string example: '2026-01-20' type: type: string example: borc refNo: type: string example: SIP-2026-000045 refType: type: string example: invoice refId: type: string example: 01JQ7ZC000000000000000000B description: type: string example: 'Satış faturası' debit: type: string example: '1500.00' credit: type: string example: '0.00' balanceAfter: type: string example: '1500.00' createdAt: type: string example: '2026-01-20T12:00:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 3 perPage: type: integer example: 20 total: type: integer example: 47 tags: - Cariler parameters: - in: path name: party_id description: 'The ID of the party.' example: architecto required: true schema: type: string - in: path name: party description: 'Cari kaydının ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: true schema: type: string /api/public/v1/invoices: get: summary: 'Faturaları listele' operationId: faturalarListele description: 'Faturaları sayfalı olarak döner. Yön, durum, cari ve tarih aralığı ile filtrelenebilir.' parameters: - in: query name: direction description: 'Yön (satis, alis).' example: satis required: false schema: type: string description: 'Yön (satis, alis).' example: satis - in: query name: status description: 'Fatura durum kodu (ör. 0=taslak, 8=kaydedildi, 50=gönderildi).' example: 8 required: false schema: type: integer description: 'Fatura durum kodu (ör. 0=taslak, 8=kaydedildi, 50=gönderildi).' example: 8 - in: query name: partyId description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: false schema: type: string description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W - in: query name: from description: 'date Düzenleme tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' required: false schema: type: string description: 'date Düzenleme tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' - in: query name: to description: 'date Düzenleme tarihi üst sınırı (YYYY-AA-GG).' example: '2026-01-31' required: false schema: type: string description: 'date Düzenleme tarihi üst sınırı (YYYY-AA-GG).' example: '2026-01-31' - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Başarılı liste' content: application/json: schema: type: object example: data: - id: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: GIB2026000000123 direction: satis documentType: einvoice invoiceProfile: TICARIFATURA status: 8 statusLabel: Kaydedildi issueDate: '2026-01-20' dueDate: '2026-02-19' subtotal: '1000.00' vatTotal: '200.00' payableAmount: '1200.00' openBalance: '1200.00' envelopeId: null lastError: null syncedAt: null createdAt: '2026-01-20T10:00:00+00:00' meta: currentPage: 1 lastPage: 6 perPage: 20 total: 118 properties: data: type: array example: - id: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: GIB2026000000123 direction: satis documentType: einvoice invoiceProfile: TICARIFATURA status: 8 statusLabel: Kaydedildi issueDate: '2026-01-20' dueDate: '2026-02-19' subtotal: '1000.00' vatTotal: '200.00' payableAmount: '1200.00' openBalance: '1200.00' envelopeId: null lastError: null syncedAt: null createdAt: '2026-01-20T10:00:00+00:00' items: type: object properties: id: type: string example: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: type: string example: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: type: string example: GIB2026000000123 direction: type: string example: satis documentType: type: string example: einvoice invoiceProfile: type: string example: TICARIFATURA status: type: integer example: 8 statusLabel: type: string example: Kaydedildi issueDate: type: string example: '2026-01-20' dueDate: type: string example: '2026-02-19' subtotal: type: string example: '1000.00' vatTotal: type: string example: '200.00' payableAmount: type: string example: '1200.00' openBalance: type: string example: '1200.00' envelopeId: type: string example: null nullable: true lastError: type: string example: null nullable: true syncedAt: type: string example: null nullable: true createdAt: type: string example: '2026-01-20T10:00:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 6 perPage: type: integer example: 20 total: type: integer example: 118 tags: - Faturalar post: summary: 'Fatura oluştur (taslak)' operationId: faturaOluturtaslak description: "Yeni bir fatura taslağı oluşturur. `documentType=auto` ise alıcının VKN'sine göre\ne-Fatura/e-Arşiv otomatik seçilir. En az bir satır zorunludur. Oluşturulan fatura\ntaslak olarak kalır; e-Fatura sağlayıcısına iletmek için ayrıca save-to-provider ve\nsend uç noktaları kullanılır. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: 'Taslak oluşturuldu' content: application/json: schema: type: object example: data: id: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: null direction: satis documentType: einvoice invoiceProfile: TICARIFATURA status: 0 statusLabel: Taslak issueDate: '2026-01-20' dueDate: '2026-02-19' lines: - description: 'USB-C Kablo 1m' quantity: '10.0000' unitPrice: '100.00' vatRate: 20 subtotal: '1000.00' vatTotal: '200.00' payableAmount: '1200.00' openBalance: '1200.00' envelopeId: null lastError: null syncedAt: null createdAt: '2026-01-20T10:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: type: string example: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: type: string example: null nullable: true direction: type: string example: satis documentType: type: string example: einvoice invoiceProfile: type: string example: TICARIFATURA status: type: integer example: 0 statusLabel: type: string example: Taslak issueDate: type: string example: '2026-01-20' dueDate: type: string example: '2026-02-19' lines: type: array example: - description: 'USB-C Kablo 1m' quantity: '10.0000' unitPrice: '100.00' vatRate: 20 items: type: object properties: description: type: string example: 'USB-C Kablo 1m' quantity: type: string example: '10.0000' unitPrice: type: string example: '100.00' vatRate: type: integer example: 20 subtotal: type: string example: '1000.00' vatTotal: type: string example: '200.00' payableAmount: type: string example: '1200.00' openBalance: type: string example: '1200.00' envelopeId: type: string example: null nullable: true lastError: type: string example: null nullable: true syncedAt: type: string example: null nullable: true createdAt: type: string example: '2026-01-20T10:00:00+00:00' 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: lines: - 'En az bir fatura satırı gereklidir.' properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: lines: type: array example: - 'En az bir fatura satırı gereklidir.' items: type: string tags: - Faturalar requestBody: required: true content: application/json: schema: type: object properties: direction: type: string description: 'Yön (satis, alis).' example: satis documentType: type: string description: 'Belge türü (einvoice, earchive, manual, auto).' example: auto nullable: true invoiceTypeCode: type: integer description: 'Fatura tip kodu (1=Satış, 2=İade, 3=İstisna, 5=Tevkifat...).' example: 1 nullable: true invoiceProfile: type: string description: 'Fatura senaryosu (TEMELFATURA, TICARIFATURA, EARSIVFATURA, IHRACAT).' example: TICARIFATURA nullable: true partyId: type: string description: 'Kayıtlı cari ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W nullable: true receiverTaxNumber: type: string description: 'Alıcı VKN (10) veya TCKN (11).' example: '1234567890' nullable: true receiverName: type: string description: 'Alıcı ünvanı/adı.' example: 'Örnek Yazılım Ltd. Şti.' receiverEmail: type: string description: 'Alıcı e-posta adresi.' example: muhasebe@ornek.com nullable: true receiverAlias: type: string description: 'Must not be greater than 190 characters.' example: k nullable: true receiverAddress: type: string description: 'Must not be greater than 500 characters.' example: c nullable: true issueDate: type: date description: 'Düzenleme tarihi (YYYY-AA-GG).' example: '2026-01-20' dueDate: type: date description: "Vade tarihi (issueDate'ten önce olamaz)." example: '2026-02-19' nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true exchangeRate: type: number description: 'Döviz kuru.' example: 1.0 nullable: true notes: type: string description: 'Fatura notu.' example: 'Teşekkür ederiz.' nullable: true returnInvoiceNumber: type: string description: 'This field is required when invoiceTypeCode is 2 or 15. Must not be greater than 64 characters.' example: 'y' nullable: true returnInvoiceDate: type: string description: 'This field is required when invoiceTypeCode is 2 or 15. Must be a valid date.' example: '2026-07-02T15:35:16' nullable: true lines: type: array description: 'Fatura satırları (en az 1).' example: - [] items: type: object properties: description: type: string description: 'Satır açıklaması.' example: 'USB-C Kablo 1m' productId: type: string description: 'Ürün ULID kimliği.' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z nullable: true productVariantId: type: string description: 'Must be 26 characters.' example: tcpscqldzsnrwtujwvlxjklqpp nullable: true itemCode: type: string description: 'Must not be greater than 64 characters.' example: w nullable: true quantity: type: number description: 'Miktar (en fazla 4 ondalık).' example: 10.0 unitCode: type: string description: 'Birim kodu.' example: C62 nullable: true unitPrice: type: number description: 'Birim fiyat (KDV hariç).' example: 100.0 allowanceRate: type: number description: 'Must be at least 0. Must not be greater than 100.' example: 5 nullable: true allowanceAmount: type: number description: 'Must match the regex /^\d+(\.\d{1,2})?$/. Must be at least 0. Must not be greater than 99999999.99.' example: 14 nullable: true vatRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 vatExemptionCode: type: string description: 'This field is required when invoiceTypeCode is 3. Must not be greater than 10 characters.' example: ojsaus nullable: true vatExemptionReason: type: string description: 'This field is required when invoiceTypeCode is 3. Must not be greater than 255 characters.' example: g nullable: true withholdingRate: type: number description: 'This field is required when invoiceTypeCode is 5 or 15. Must be at least 0. Must not be greater than 100.' example: 25 nullable: true withholdingCode: type: string description: 'This field is required when invoiceTypeCode is 5 or 15. Must not be greater than 10 characters.' example: oglrbc nullable: true required: - description - quantity - unitPrice - vatRate required: - direction - receiverName - issueDate - lines '/api/public/v1/invoices/{invoice_id}': get: summary: 'Fatura görüntüle' operationId: faturaGrntle description: 'Tek bir faturayı satırları, ödemeleri ve cari bilgisiyle birlikte döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: id: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: GIB2026000000123 direction: satis documentType: einvoice invoiceProfile: TICARIFATURA status: 8 statusLabel: Kaydedildi issueDate: '2026-01-20' dueDate: '2026-02-19' lines: - description: 'USB-C Kablo 1m' quantity: '10.0000' unitPrice: '100.00' vatRate: 20 subtotal: '1000.00' vatTotal: '200.00' payableAmount: '1200.00' openBalance: '1200.00' envelopeId: null lastError: null syncedAt: null createdAt: '2026-01-20T10:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ9B1C2D3E4F5G6H7J8K9L0M uuid: type: string example: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f invoiceNumber: type: string example: GIB2026000000123 direction: type: string example: satis documentType: type: string example: einvoice invoiceProfile: type: string example: TICARIFATURA status: type: integer example: 8 statusLabel: type: string example: Kaydedildi issueDate: type: string example: '2026-01-20' dueDate: type: string example: '2026-02-19' lines: type: array example: - description: 'USB-C Kablo 1m' quantity: '10.0000' unitPrice: '100.00' vatRate: 20 items: type: object properties: description: type: string example: 'USB-C Kablo 1m' quantity: type: string example: '10.0000' unitPrice: type: string example: '100.00' vatRate: type: integer example: 20 subtotal: type: string example: '1000.00' vatTotal: type: string example: '200.00' payableAmount: type: string example: '1200.00' openBalance: type: string example: '1200.00' envelopeId: type: string example: null nullable: true lastError: type: string example: null nullable: true syncedAt: type: string example: null nullable: true createdAt: type: string example: '2026-01-20T10:00:00+00:00' 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Faturalar parameters: - in: path name: invoice_id description: 'The ID of the invoice.' example: architecto required: true schema: type: string - in: path name: invoice description: 'Faturanın ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string '/api/public/v1/invoices/{invoice_id}/status': get: summary: 'Fatura durumu' operationId: faturaDurumu description: 'Faturanın e-Fatura yaşam döngüsündeki güncel durumunu ve sağlayıcı kimliklerini döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: status: 50 statusLabel: Gönderildi envelopeId: f1e2d3c4-b5a6-7890-1234-567890abcdef uuid: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f lastError: null syncedAt: '2026-01-20T10:07:00+00:00' properties: data: type: object properties: status: type: integer example: 50 statusLabel: type: string example: Gönderildi envelopeId: type: string example: f1e2d3c4-b5a6-7890-1234-567890abcdef uuid: type: string example: b7f3c2a0-1e2d-4c3b-9a8f-0e1d2c3b4a5f lastError: type: string example: null nullable: true syncedAt: type: string example: '2026-01-20T10:07:00+00:00' tags: - Faturalar parameters: - in: path name: invoice_id description: 'The ID of the invoice.' example: architecto required: true schema: type: string - in: path name: invoice description: 'Faturanın ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string '/api/public/v1/invoices/{invoice_id}/save-to-provider': post: summary: 'Faturayı sağlayıcıya kaydet' operationId: faturaySalaycyaKaydet description: "Taslak faturayı e-Fatura/e-Arşiv sağlayıcısına kaydeder (henüz göndermez).\nSağlayıcı hatasında 502 ve hata ayrıntısı döner." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Kaydedildi content: application/json: schema: type: object example: data: id: 01JQ9B1C2D3E4F5G6H7J8K9L0M invoiceNumber: GIB2026000000123 status: 8 statusLabel: Kaydedildi envelopeId: null lastError: null syncedAt: '2026-01-20T10:05:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ9B1C2D3E4F5G6H7J8K9L0M invoiceNumber: type: string example: GIB2026000000123 status: type: integer example: 8 statusLabel: type: string example: Kaydedildi envelopeId: type: string example: null nullable: true lastError: type: string example: null nullable: true syncedAt: type: string example: '2026-01-20T10:05:00+00:00' 502: description: 'Sağlayıcı hatası' content: application/json: schema: type: object example: error: code: provider_error message: 'e-Fatura sağlayıcısına kayıt başarısız.' details: lastError: 'Bağlantı zaman aşımına uğradı.' properties: error: type: object properties: code: type: string example: provider_error message: type: string example: 'e-Fatura sağlayıcısına kayıt başarısız.' details: type: object properties: lastError: type: string example: 'Bağlantı zaman aşımına uğradı.' tags: - Faturalar parameters: - in: path name: invoice_id description: 'The ID of the invoice.' example: architecto required: true schema: type: string - in: path name: invoice description: 'Faturanın ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string '/api/public/v1/invoices/{invoice_id}/send': post: summary: 'Faturayı gönder' operationId: faturayGnder description: "Faturayı e-Fatura sağlayıcısı üzerinden alıcıya gönderir. Bu uç nokta\n`einvoice:send` scope'u gerektirir. Sağlayıcı hatasında 502 döner." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Gönderildi content: application/json: schema: type: object example: data: id: 01JQ9B1C2D3E4F5G6H7J8K9L0M invoiceNumber: GIB2026000000123 status: 50 statusLabel: Gönderildi envelopeId: f1e2d3c4-b5a6-7890-1234-567890abcdef lastError: null syncedAt: '2026-01-20T10:07:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ9B1C2D3E4F5G6H7J8K9L0M invoiceNumber: type: string example: GIB2026000000123 status: type: integer example: 50 statusLabel: type: string example: Gönderildi envelopeId: type: string example: f1e2d3c4-b5a6-7890-1234-567890abcdef lastError: type: string example: null nullable: true syncedAt: type: string example: '2026-01-20T10:07:00+00:00' 502: description: 'Sağlayıcı hatası' content: application/json: schema: type: object example: error: code: provider_error message: 'e-Fatura sağlayıcısına gönderim başarısız.' details: lastError: 'Alıcı e-Fatura mükellefi değil.' properties: error: type: object properties: code: type: string example: provider_error message: type: string example: 'e-Fatura sağlayıcısına gönderim başarısız.' details: type: object properties: lastError: type: string example: 'Alıcı e-Fatura mükellefi değil.' tags: - Faturalar parameters: - in: path name: invoice_id description: 'The ID of the invoice.' example: architecto required: true schema: type: string - in: path name: invoice description: 'Faturanın ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string /api/public/v1/expenses: get: summary: 'Giderleri listele' operationId: giderleriListele description: "Gider kayıtlarını sayfalı olarak döner. Kategori, durum, cari, tarih aralığı\nve arama terimiyle filtrelenebilir; tarih/tutar/kategori/güncelleme alanlarına göre sıralanabilir." parameters: - in: query name: category description: 'Kategoriye göre filtre.' example: kira required: false schema: type: string description: 'Kategoriye göre filtre.' example: kira - in: query name: status description: 'Duruma göre filtre (taslak, onaylandi, odendi, reddedildi).' example: null required: false schema: type: array description: 'Duruma göre filtre (taslak, onaylandi, odendi, reddedildi).' example: null items: type: string - in: query name: partyId description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: false schema: type: string description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W - in: query name: from description: 'date Tarih alt sınırı (YYYY-AA-GG).' example: '2026-01-01' required: false schema: type: string description: 'date Tarih alt sınırı (YYYY-AA-GG).' example: '2026-01-01' - in: query name: to description: 'date Tarih üst sınırı (YYYY-AA-GG).' example: '2026-01-31' required: false schema: type: string description: 'date Tarih üst sınırı (YYYY-AA-GG).' example: '2026-01-31' - in: query name: search description: 'Açıklama, tedarikçi, VKN veya gider no içinde arama.' example: kira required: false schema: type: string description: 'Açıklama, tedarikçi, VKN veya gider no içinde arama.' example: kira - in: query name: sort description: 'Sıralama alanı (date, amount, updated, category).' example: date required: false schema: type: string description: 'Sıralama alanı (date, amount, updated, category).' example: date - in: query name: dir description: 'Sıralama yönü (asc, desc).' example: desc required: false schema: type: string description: 'Sıralama yönü (asc, desc).' example: desc - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Başarılı liste' content: application/json: schema: type: object example: data: - id: 01JQAC3D4E5F6G7H8J9K0L1M2N expenseNo: GID-2026-000045 date: '2026-01-20' category: kira categoryLabel: Kira description: 'Ofis kirası' vendor: 'Örnek Emlak' vendorVkn: '1234567890' paymentMethod: havale subtotal: '10000.00' kdvRate: '20.00' kdvAmount: '2000.00' total: '12000.00' status: onaylandi statusLabel: Onaylandı createdAt: '2026-01-20T10:00:00+00:00' meta: currentPage: 1 lastPage: 5 perPage: 20 total: 92 properties: data: type: array example: - id: 01JQAC3D4E5F6G7H8J9K0L1M2N expenseNo: GID-2026-000045 date: '2026-01-20' category: kira categoryLabel: Kira description: 'Ofis kirası' vendor: 'Örnek Emlak' vendorVkn: '1234567890' paymentMethod: havale subtotal: '10000.00' kdvRate: '20.00' kdvAmount: '2000.00' total: '12000.00' status: onaylandi statusLabel: Onaylandı createdAt: '2026-01-20T10:00:00+00:00' items: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N expenseNo: type: string example: GID-2026-000045 date: type: string example: '2026-01-20' category: type: string example: kira categoryLabel: type: string example: Kira description: type: string example: 'Ofis kirası' vendor: type: string example: 'Örnek Emlak' vendorVkn: type: string example: '1234567890' paymentMethod: type: string example: havale subtotal: type: string example: '10000.00' kdvRate: type: string example: '20.00' kdvAmount: type: string example: '2000.00' total: type: string example: '12000.00' status: type: string example: onaylandi statusLabel: type: string example: Onaylandı createdAt: type: string example: '2026-01-20T10:00:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 5 perPage: type: integer example: 20 total: type: integer example: 92 tags: - Giderler post: summary: 'Gider oluştur' operationId: giderOlutur description: "Yeni bir gider kaydı oluşturur. `kdvAmount` ve `total`, `subtotal` ve `kdvRate`\nüzerinden hesaplanır. Gider no otomatik üretilir. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQAC3D4E5F6G7H8J9K0L1M2N expenseNo: GID-2026-000045 date: '2026-01-20' category: kira categoryLabel: Kira description: 'Ofis kirası' paymentMethod: havale subtotal: '10000.00' kdvRate: '20.00' kdvAmount: '2000.00' total: '12000.00' status: taslak statusLabel: Taslak createdAt: '2026-01-20T10:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N expenseNo: type: string example: GID-2026-000045 date: type: string example: '2026-01-20' category: type: string example: kira categoryLabel: type: string example: Kira description: type: string example: 'Ofis kirası' paymentMethod: type: string example: havale subtotal: type: string example: '10000.00' kdvRate: type: string example: '20.00' kdvAmount: type: string example: '2000.00' total: type: string example: '12000.00' status: type: string example: taslak statusLabel: type: string example: Taslak createdAt: type: string example: '2026-01-20T10:00:00+00:00' 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: date: - 'Gider tarihi gelecekte olamaz.' properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: date: type: array example: - 'Gider tarihi gelecekte olamaz.' items: type: string tags: - Giderler requestBody: required: true content: application/json: schema: type: object properties: date: type: date description: 'Gider tarihi (bugünden ileri olamaz).' example: '2026-01-20' category: type: string description: 'Kategori (kira, elektrik, personel, yakit, ...).' example: kira description: type: string description: Açıklama. example: 'Ofis kirası' vendor: type: string description: 'Tedarikçi adı.' example: 'Örnek Emlak' nullable: true vendorVkn: type: string description: 'Tedarikçi VKN (10) veya TCKN (11).' example: '1234567890' nullable: true paymentMethod: type: string description: 'Ödeme yöntemi (havale, nakit, kredi-karti, kasa, cek).' example: havale paymentAccountId: type: string description: 'Ödeme hesabı ULID kimliği.' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z nullable: true partyId: type: string description: 'Cari ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true exchangeRate: type: number description: 'Döviz kuru.' example: 1.0 nullable: true subtotal: type: number description: 'KDV hariç tutar.' example: 10000.0 kdvRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 nullable: true status: type: string description: 'Durum (taslak, onaylandi, odendi, reddedildi).' example: taslak nullable: true notes: type: string description: Not. example: 'Ocak ayı kirası.' nullable: true customFields: type: object description: '' example: null properties: { } nullable: true required: - date - category - description - paymentMethod - subtotal '/api/public/v1/expenses/{expense_id}': get: summary: 'Gider görüntüle' operationId: giderGrntle description: 'Tek bir gider kaydının ayrıntılarını döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Giderler patch: summary: 'Gider güncelle' operationId: giderGncelle description: "Var olan bir gider kaydını kısmi olarak günceller. `subtotal` veya `kdvRate`\ndeğişirse `kdvAmount` ve `total` yeniden hesaplanır." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Giderler requestBody: required: false content: application/json: schema: type: object properties: date: type: date description: 'Gider tarihi (bugünden ileri olamaz).' example: '2026-01-20' category: type: string description: Kategori. example: elektrik description: type: string description: Açıklama. example: 'Ocak elektrik faturası' vendor: type: string description: 'Must not be greater than 190 characters.' example: d nullable: true vendorVkn: type: string description: 'Must match the regex /^[0-9]{10,11}$/.' example: '5642559314' nullable: true paymentMethod: type: string description: '' example: kredi-karti enum: - havale - nakit - kredi-karti - kasa - cek paymentAccountId: type: string description: 'Must be 26 characters.' example: khwaykcmyuwpwlvqwrsitcpscq nullable: true partyId: type: string description: 'Must be 26 characters.' example: ldzsnrwtujwvlxjklqppwqbewt nullable: true currencyCode: type: string description: 'Must be 3 characters.' example: nno nullable: true exchangeRate: type: number description: 'Must be at least 0.0001.' example: 68 nullable: true subtotal: type: number description: 'KDV hariç tutar.' example: 500.0 kdvRate: type: number description: 'KDV oranı.' example: 20.0 nullable: true status: type: string description: Durum. example: onaylandi notes: type: string description: 'Must not be greater than 5000 characters.' example: p nullable: true customFields: type: object description: '' example: null properties: { } nullable: true parameters: - in: path name: expense_id description: 'The ID of the expense.' example: architecto required: true schema: type: string - in: path name: expense description: 'Gider kaydının ULID kimliği.' example: 01JQAC3D4E5F6G7H8J9K0L1M2N required: true schema: type: string '/api/public/v1/expenses/{expense_id}/approve': post: summary: 'Gideri onayla' operationId: gideriOnayla description: 'Gideri onaylanmış duruma geçirir. Zaten onaylı/ödenmiş giderler değişmeden döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Giderler parameters: - in: path name: expense_id description: 'The ID of the expense.' example: architecto required: true schema: type: string - in: path name: expense description: 'Gider kaydının ULID kimliği.' example: 01JQAC3D4E5F6G7H8J9K0L1M2N required: true schema: type: string '/api/public/v1/expenses/{expense_id}/reject': post: summary: 'Gideri reddet' operationId: gideriReddet description: 'Gideri reddedilmiş duruma geçirir. İsteğe bağlı bir gerekçe kaydedilir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Giderler requestBody: required: false content: application/json: schema: type: object properties: reason: type: string description: 'Red gerekçesi.' example: 'Belge eksik.' nullable: true parameters: - in: path name: expense_id description: 'The ID of the expense.' example: architecto required: true schema: type: string - in: path name: expense description: 'Gider kaydının ULID kimliği.' example: 01JQAC3D4E5F6G7H8J9K0L1M2N required: true schema: type: string /api/public/v1/cash-accounts: get: summary: 'Kasa/banka hesaplarını listele' operationId: kasabankaHesaplarnListele description: 'Hesapları sayfalı olarak döner. Tür, aktiflik ve ad/kod/banka/IBAN araması ile filtrelenebilir.' parameters: - in: query name: kind description: 'Tür filtresi (banka, kasa).' example: banka required: false schema: type: string description: 'Tür filtresi (banka, kasa).' example: banka - in: query name: activeOnly description: 'Sadece aktif hesaplar.' example: true required: false schema: type: boolean description: 'Sadece aktif hesaplar.' example: true - in: query name: search description: 'Ad, kod, banka adı veya IBAN içinde arama.' example: Garanti required: false schema: type: string description: 'Ad, kod, banka adı veya IBAN içinde arama.' example: Garanti - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Kasa/Banka post: summary: 'Kasa/banka hesabı oluştur' operationId: kasabankaHesabOlutur description: "Yeni bir kasa veya banka hesabı oluşturur. `openingBalance` hem açılış hem\ngüncel bakiye olarak ayarlanır. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W kind: banka code: BNK-001 name: 'Ana TL Hesabı' balance: '1000.00' properties: data: type: object properties: id: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W kind: type: string example: banka code: type: string example: BNK-001 name: type: string example: 'Ana TL Hesabı' balance: type: string example: '1000.00' tags: - Kasa/Banka requestBody: required: true content: application/json: schema: type: object properties: kind: type: string description: 'Tür (banka, kasa).' example: banka code: type: string description: 'Tenant içinde benzersiz hesap kodu.' example: BNK-001 name: type: string description: 'Hesap adı.' example: 'Ana TL Hesabı' bankName: type: string description: 'Banka adı.' example: 'Garanti BBVA' nullable: true iban: type: string description: IBAN. example: TR330006100519786457841326 nullable: true bic: type: string description: 'BIC/SWIFT kodu.' example: TGBATRIS nullable: true branchCode: type: string description: 'Şube kodu.' example: '519' nullable: true accountNo: type: string description: 'Hesap numarası.' example: 6457841-326 nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true openingBalance: type: number description: 'Açılış bakiyesi.' example: 1000.0 nullable: true active: type: boolean description: 'Aktif mi.' example: true nullable: true notes: type: string description: Notlar. example: architecto nullable: true required: - kind - code - name '/api/public/v1/cash-accounts/{cashAccount_id}': get: summary: 'Kasa/banka hesabı görüntüle' operationId: kasabankaHesabGrntle description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Kasa/Banka patch: summary: 'Kasa/banka hesabı güncelle' operationId: kasabankaHesabGncelle description: 'Var olan bir hesabı kısmi olarak günceller. Yalnızca gönderilen alanlar değişir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Kasa/Banka requestBody: required: false content: application/json: schema: type: object properties: kind: type: string description: '' example: banka enum: - banka - kasa code: type: string description: 'Must not be greater than 32 characters.' example: b name: type: string description: 'Must not be greater than 190 characters.' example: 'n' bankName: type: string description: 'Must not be greater than 190 characters.' example: g nullable: true iban: type: string description: 'Must not be greater than 34 characters.' example: z nullable: true bic: type: string description: 'Must match the regex /^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$/.' example: VDLJNIW1 nullable: true branchCode: type: string description: 'Must not be greater than 16 characters.' example: waykcmyuwpwlvqwr nullable: true accountNo: type: string description: 'Must not be greater than 64 characters.' example: s nullable: true currencyCode: type: string description: 'Must be 3 characters.' example: itc active: type: boolean description: '' example: true notes: type: string description: 'Must not be greater than 5000 characters.' example: p nullable: true parameters: - in: path name: cashAccount_id description: 'The ID of the cashAccount.' example: architecto required: true schema: type: string - in: path name: cashAccount description: 'Hesabın ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: true schema: type: string '/api/public/v1/cash-accounts/{cashAccount_id}/movements': get: summary: 'Hesap hareketlerini listele' operationId: hesapHareketleriniListele description: 'Bir hesaba ait para hareketlerini sayfalı döner. Tür, tarih aralığı ve arama ile filtrelenebilir.' parameters: - in: query name: type description: 'Hareket türü (giris, cikis, transfer-giris, transfer-cikis).' example: giris required: false schema: type: string description: 'Hareket türü (giris, cikis, transfer-giris, transfer-cikis).' example: giris - in: query name: from description: 'date Tarih alt sınırı (YYYY-AA-GG).' example: '2026-01-01' required: false schema: type: string description: 'date Tarih alt sınırı (YYYY-AA-GG).' example: '2026-01-01' - in: query name: to description: 'date Tarih üst sınırı (YYYY-AA-GG).' example: '2026-01-31' required: false schema: type: string description: 'date Tarih üst sınırı (YYYY-AA-GG).' example: '2026-01-31' - in: query name: search description: 'Açıklama, karşı taraf veya referansta arama.' example: Tahsilat required: false schema: type: string description: 'Açıklama, karşı taraf veya referansta arama.' example: Tahsilat - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Kasa/Banka post: summary: 'Hesap hareketi oluştur' operationId: hesapHareketiOlutur description: "Bir hesaba giriş (tahsilat) veya çıkış (ödeme) hareketi ekler ve hesabın güncel\nbakiyesini atomik olarak günceller. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQ7ZBTX0000000000000000A type: giris amount: '1500.00' balanceAfter: '2500.00' properties: data: type: object properties: id: type: string example: 01JQ7ZBTX0000000000000000A type: type: string example: giris amount: type: string example: '1500.00' balanceAfter: type: string example: '2500.00' tags: - Kasa/Banka requestBody: required: true content: application/json: schema: type: object properties: date: type: date description: 'Hareket tarihi (YYYY-AA-GG).' example: '2026-01-20' type: type: string description: 'Tür (giris, cikis).' example: giris category: type: string description: 'Hareket kategorisi.' example: tahsilat nullable: true description: type: string description: Açıklama. example: 'Peşin tahsilat' amount: type: number description: 'Tutar (>0).' example: 1500.0 reference: type: string description: 'Referans/dekont no.' example: DK-2026-000045 nullable: true counterparty: type: string description: 'Karşı taraf.' example: 'Örnek Ltd.' nullable: true partyId: type: string description: 'İlişkili cari ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W nullable: true invoiceId: type: string description: 'İlişkili fatura ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M nullable: true expenseId: type: string description: 'İlişkili masraf ULID kimliği.' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z nullable: true notes: type: string description: Notlar. example: architecto nullable: true required: - date - type - description - amount parameters: - in: path name: cashAccount_id description: 'The ID of the cashAccount.' example: architecto required: true schema: type: string - in: path name: cashAccount description: 'Hesabın ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: true schema: type: string /api/public/v1/cash-transfers: post: summary: 'Hesaplar arası transfer' operationId: hesaplarArasTransfer description: "Bir hesaptan diğerine para transferi yapar; kaynakta çıkış, hedefte giriş hareketi\nüretir ve her iki bakiyeyi atomik olarak günceller. Farklı para birimlerinde\n`exchangeRate` zorunludur. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQ7ZC000000000000000000B sourceAccountId: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W destinationAccountId: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z amount: '500.00' properties: data: type: object properties: id: type: string example: 01JQ7ZC000000000000000000B sourceAccountId: type: string example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W destinationAccountId: type: string example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z amount: type: string example: '500.00' tags: - Kasa/Banka requestBody: required: true content: application/json: schema: type: object properties: sourceAccountId: type: string description: 'Kaynak hesabın ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W destinationAccountId: type: string description: 'Hedef hesabın ULID kimliği (farklı).' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z date: type: date description: 'Transfer tarihi (YYYY-AA-GG).' example: '2026-01-20' amount: type: number description: 'Tutar (>0).' example: 500.0 exchangeRate: type: number description: 'Döviz kuru (farklı para birimlerinde zorunlu).' example: 1.0 nullable: true reference: type: string description: Referans. example: TRF-2026-000012 nullable: true description: type: string description: Açıklama. example: 'Kasa → Banka aktarımı' nullable: true required: - sourceAccountId - destinationAccountId - date - amount /api/public/v1/receipts: get: summary: 'Makbuzları listele' operationId: makbuzlarListele description: "Makbuzları sayfalı olarak döner. Tip, durum, tarih aralığı ile\nfiltrelenebilir; makbuz no, UUID, cari ad veya açıklama içinde aranabilir." parameters: - in: query name: type description: 'Makbuz tipi (smm, mm).' example: smm required: false schema: type: string description: 'Makbuz tipi (smm, mm).' example: smm - in: query name: status description: 'Duruma göre filtre (taslak, gonderildi, iptal).' example: taslak required: false schema: type: string description: 'Duruma göre filtre (taslak, gonderildi, iptal).' example: taslak - in: query name: from description: 'date Düzenleme tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' required: false schema: type: string description: 'date Düzenleme tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' - in: query name: to description: 'date Düzenleme tarihi üst sınırı (YYYY-AA-GG).' example: '2026-12-31' required: false schema: type: string description: 'date Düzenleme tarihi üst sınırı (YYYY-AA-GG).' example: '2026-12-31' - in: query name: search description: 'Makbuz no, UUID, cari ad veya açıklama içinde arama.' example: SMM-2026 required: false schema: type: string description: 'Makbuz no, UUID, cari ad veya açıklama içinde arama.' example: SMM-2026 - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Makbuzlar post: summary: 'Makbuz oluştur' operationId: makbuzOlutur description: "Yeni bir SMM veya MM makbuzu oluşturur. `receiptNumber` gönderilmezse\ntipe göre otomatik üretilir. KDV, stopajlar, net ve ödenecek tutarlar\nservis tarafından hesaplanır (girdide kabul edilmez). Idempotency-Key\nbaşlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_failed message: 'Gönderilen veriler geçersiz.' details: grossAmount: - 'Brüt tutar alanı zorunludur.' properties: error: type: object properties: code: type: string example: validation_failed message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: grossAmount: type: array example: - 'Brüt tutar alanı zorunludur.' items: type: string tags: - Makbuzlar requestBody: required: true content: application/json: schema: type: object properties: type: type: string description: 'Makbuz tipi (smm, mm).' example: smm receiptNumber: type: string description: 'Makbuz numarası (boş bırakılırsa otomatik).' example: SMM-2026-000001 nullable: true profile: type: string description: 'Makbuz profili.' example: STANDART nullable: true partyId: type: string description: 'Kayıtlı cari ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W nullable: true partyName: type: string description: 'Cari ünvanı/adı.' example: 'Av. Örnek Kişi' nullable: true partyTaxId: type: string description: 'Cari VKN (10) veya TCKN (11).' example: '1234567890' nullable: true partyAddress: type: string description: 'Cari adresi.' example: 'Bağdat Cad. No:1' nullable: true issueDate: type: date description: 'Düzenleme tarihi (YYYY-AA-GG).' example: '2026-07-01' nullable: true productCategory: type: string description: 'Ürün/hizmet kategorisi (bitkisel-mahsul, hayvansal-mahsul, hizmet).' example: hizmet nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true grossAmount: type: number description: 'Brüt tutar (0.01 - 99999999.99).' example: 1000.0 vatRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 nullable: true vatWithholdingCode: type: string description: 'KDV tevkifat kodu.' example: '601' nullable: true vatWithholdingRate: type: number description: 'KDV tevkifat oranı (0-1).' example: 0.5 nullable: true incomeTaxWithholdingRate: type: number description: 'Gelir vergisi stopaj oranı (0-1).' example: 0.2 nullable: true bagKurWithholdingRate: type: number description: 'BAĞ-KUR stopaj oranı (0-1, sadece MM).' example: 0.02 nullable: true paymentMethod: type: string description: 'Ödeme yöntemi (nakit, havale, cek, senet, kredi-karti, diger).' example: havale nullable: true description: type: string description: Açıklama. example: 'Danışmanlık hizmeti' nullable: true notes: type: string description: Not. example: 'Teşekkür ederiz.' nullable: true lines: type: array description: 'Makbuz satırları.' example: - [] items: type: object nullable: true properties: description: type: string description: 'Satır açıklaması.' example: Danışmanlık quantity: type: number description: Miktar. example: 1.0 nullable: true unitCode: type: string description: 'Birim kodu.' example: NIU nullable: true unitPrice: type: number description: 'Birim fiyat.' example: 1000.0 nullable: true required: - description required: - type - grossAmount '/api/public/v1/receipts/{receipt_id}': get: summary: 'Makbuz görüntüle' operationId: makbuzGrntle description: 'Tek bir makbuzu satırları ve cari bilgisiyle birlikte döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Makbuzlar patch: summary: 'Makbuz güncelle' operationId: makbuzGncelle description: "Var olan bir makbuzu kısmi olarak günceller. Yalnızca gönderilen alanlar\ndeğişir; tutarlar yeniden hesaplanır. Gönderilmiş/onaylanmış makbuz\ndüzenlenemez." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Makbuzlar requestBody: required: false content: application/json: schema: type: object properties: receiptNumber: type: string description: 'Must not be greater than 32 characters.' example: b nullable: true profile: type: string description: 'Must not be greater than 32 characters.' example: 'n' nullable: true partyId: type: string description: 'The id of an existing record in the parties table. Must be 26 characters.' example: gzmiyvdljnikhwaykcmyuwpwlv nullable: true partyName: type: string description: 'Must not be greater than 200 characters.' example: q nullable: true partyTaxId: type: string description: 'Must match the regex /^[0-9]{10,11}$/.' example: '5642559314' nullable: true partyAddress: type: string description: 'Must not be greater than 1000 characters.' example: k nullable: true issueDate: type: string description: 'Must be a valid date in the format Y-m-d. Must be a date before or equal to today.' example: '2022-07-27' productCategory: type: string description: '' example: hayvansal-mahsul enum: - bitkisel-mahsul - hayvansal-mahsul - hizmet currencyCode: type: string description: 'Must be 3 characters.' example: ngz grossAmount: type: number description: 'Must match the regex /^\d+(\.\d{1,2})?$/. Must be at least 0.01. Must not be greater than 99999999.99.' example: 17 vatRate: type: number description: 'Must be between 0 and 100.' example: 0 nullable: true vatWithholdingCode: type: string description: 'Must not be greater than 10 characters.' example: yvdljn nullable: true vatWithholdingRate: type: number description: 'Must be at least 0. Must not be greater than 1.' example: 1 nullable: true incomeTaxWithholdingRate: type: number description: 'Must be at least 0. Must not be greater than 1.' example: 1 nullable: true bagKurWithholdingRate: type: number description: 'Must be at least 0. Must not be greater than 1.' example: 1 nullable: true paymentMethod: type: string description: '' example: havale enum: - nakit - havale - cek - senet - kredi-karti - diger description: type: string description: 'Must not be greater than 500 characters.' example: 'Ab provident perspiciatis quo omnis nostrum aut adipisci.' nullable: true notes: type: string description: 'Must not be greater than 500 characters.' example: p nullable: true lines: type: array description: '' example: null items: type: object properties: description: type: string description: 'This field is required when lines is present. Must not be greater than 500 characters.' example: 'Qui commodi incidunt iure odit.' quantity: type: number description: 'Must match the regex /^\d+(\.\d{1,4})?$/. Must be at least 0. Must not be greater than 9999999.9999.' example: 10 nullable: true unitCode: type: string description: 'Must not be greater than 10 characters.' example: itcpsc nullable: true unitPrice: type: number description: 'Must match the regex /^\d+(\.\d{1,2})?$/. Must be at least 0. Must not be greater than 99999999.99.' example: 17 nullable: true parameters: - in: path name: receipt_id description: 'The ID of the receipt.' example: architecto required: true schema: type: string - in: path name: receipt description: 'Makbuzun ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string '/api/public/v1/receipts/{receipt_id}/send': post: summary: 'Makbuzu gönder' operationId: makbuzuGnder description: 'Taslak makbuzu gönderilmiş duruma taşır ve bir UUID atar.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Makbuzlar parameters: - in: path name: receipt_id description: 'The ID of the receipt.' example: architecto required: true schema: type: string - in: path name: receipt description: 'Makbuzun ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string '/api/public/v1/receipts/{receipt_id}/cancel': post: summary: 'Makbuzu iptal et' operationId: makbuzuIptalEt description: 'Taslak veya gönderilmiş makbuzu iptal eder. İptal nedeni opsiyoneldir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Makbuzlar requestBody: required: false content: application/json: schema: type: object properties: reason: type: string description: 'İptal nedeni.' example: 'Hatalı düzenlendi' nullable: true parameters: - in: path name: receipt_id description: 'The ID of the receipt.' example: architecto required: true schema: type: string - in: path name: receipt description: 'Makbuzun ULID kimliği.' example: 01JQ9B1C2D3E4F5G6H7J8K9L0M required: true schema: type: string /api/public/v1/orders: get: summary: 'Siparişleri listele' operationId: siparileriListele description: "Siparişleri sayfalı olarak döner. Kaynak, durum ve cari ile filtrelenebilir.\n`source` için `marketplace` (tüm pazaryerleri) veya `direct` özel değerleri de kullanılabilir." parameters: - in: query name: source description: 'Kaynak (marketplace, direct veya trendyol, hepsiburada, manual...).' example: trendyol required: false schema: type: string description: 'Kaynak (marketplace, direct veya trendyol, hepsiburada, manual...).' example: trendyol - in: query name: status description: 'Sipariş durumu (yeni, onaylandi, hazirlaniyor, kargoda, teslim, iptal, iade).' example: yeni required: false schema: type: string description: 'Sipariş durumu (yeni, onaylandi, hazirlaniyor, kargoda, teslim, iptal, iade).' example: yeni - in: query name: partyId description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: false schema: type: string description: 'Cari ULID kimliğine göre filtre.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Başarılı liste' content: application/json: schema: type: object example: data: - id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: trendyol status: yeni statusLabel: Yeni paymentStatus: odendi externalOrderId: TY-987654321 partyId: null customerName: 'Ayşe Yılmaz' customerEmail: ayse@example.com customerPhone: '+905321234567' orderDate: '2026-01-22' subtotal: '500.00' taxTotal: '100.00' shippingAmount: '29.90' total: '629.90' invoiceId: null createdAt: '2026-01-22T14:00:00+00:00' meta: currentPage: 1 lastPage: 8 perPage: 20 total: 156 properties: data: type: array example: - id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: trendyol status: yeni statusLabel: Yeni paymentStatus: odendi externalOrderId: TY-987654321 partyId: null customerName: 'Ayşe Yılmaz' customerEmail: ayse@example.com customerPhone: '+905321234567' orderDate: '2026-01-22' subtotal: '500.00' taxTotal: '100.00' shippingAmount: '29.90' total: '629.90' invoiceId: null createdAt: '2026-01-22T14:00:00+00:00' items: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: type: string example: SIP-2026-000045 source: type: string example: trendyol status: type: string example: yeni statusLabel: type: string example: Yeni paymentStatus: type: string example: odendi externalOrderId: type: string example: TY-987654321 partyId: type: string example: null nullable: true customerName: type: string example: 'Ayşe Yılmaz' customerEmail: type: string example: ayse@example.com customerPhone: type: string example: '+905321234567' orderDate: type: string example: '2026-01-22' subtotal: type: string example: '500.00' taxTotal: type: string example: '100.00' shippingAmount: type: string example: '29.90' total: type: string example: '629.90' invoiceId: type: string example: null nullable: true createdAt: type: string example: '2026-01-22T14:00:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 8 perPage: type: integer example: 20 total: type: integer example: 156 tags: - Siparişler post: summary: 'Sipariş oluştur' operationId: sipariOlutur description: "Yeni bir sipariş oluşturur. En az bir satır zorunludur. Tutarlar satırlardan\nhesaplanır. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: website status: yeni statusLabel: Yeni paymentStatus: odendi externalOrderId: TY-987654321 partyId: null customerName: 'Ayşe Yılmaz' customerEmail: ayse@example.com customerPhone: '+905321234567' orderDate: '2026-01-22' subtotal: '500.00' taxTotal: '100.00' shippingAmount: '29.90' total: '629.90' invoiceId: null lines: - description: 'USB-C Kablo 1m' quantity: '5.0000' unitPrice: '100.00' vatRate: 20 createdAt: '2026-01-22T14:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: type: string example: SIP-2026-000045 source: type: string example: website status: type: string example: yeni statusLabel: type: string example: Yeni paymentStatus: type: string example: odendi externalOrderId: type: string example: TY-987654321 partyId: type: string example: null nullable: true customerName: type: string example: 'Ayşe Yılmaz' customerEmail: type: string example: ayse@example.com customerPhone: type: string example: '+905321234567' orderDate: type: string example: '2026-01-22' subtotal: type: string example: '500.00' taxTotal: type: string example: '100.00' shippingAmount: type: string example: '29.90' total: type: string example: '629.90' invoiceId: type: string example: null nullable: true lines: type: array example: - description: 'USB-C Kablo 1m' quantity: '5.0000' unitPrice: '100.00' vatRate: 20 items: type: object properties: description: type: string example: 'USB-C Kablo 1m' quantity: type: string example: '5.0000' unitPrice: type: string example: '100.00' vatRate: type: integer example: 20 createdAt: type: string example: '2026-01-22T14:00:00+00:00' 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: customerName: - 'Müşteri adı zorunludur.' properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: customerName: type: array example: - 'Müşteri adı zorunludur.' items: type: string tags: - Siparişler requestBody: required: true content: application/json: schema: type: object properties: source: type: string description: 'Kaynak (manual, trendyol, hepsiburada, n11, amazon, website, phone, whatsapp, email, store, other).' example: website nullable: true externalOrderId: type: string description: 'Kaynaktaki dış sipariş kimliği.' example: TY-987654321 nullable: true channelData: type: object description: '' example: null properties: { } nullable: true partyId: type: string description: 'Kayıtlı cari ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W nullable: true customerName: type: string description: 'Müşteri adı.' example: 'Ayşe Yılmaz' customerEmail: type: string description: 'Müşteri e-posta adresi.' example: ayse@example.com nullable: true customerPhone: type: string description: 'Müşteri telefonu.' example: '+905321234567' nullable: true billingAddress: type: object description: '' example: null properties: { } nullable: true shippingAddress: type: object description: '' example: null properties: { } nullable: true orderDate: type: date description: 'Sipariş tarihi (YYYY-AA-GG).' example: '2026-01-22' deadlineDate: type: date description: "Termin tarihi (orderDate'ten önce olamaz)." example: '2026-01-25' nullable: true paymentStatus: type: string description: 'Ödeme durumu (beklemede, odendi, kismi, iade).' example: odendi nullable: true paymentMethod: type: string description: 'Must not be greater than 32 characters.' example: 'n' nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true exchangeRate: type: number description: 'Must be at least 0.0001.' example: 8 nullable: true shippingAmount: type: number description: 'Kargo tutarı.' example: 29.9 nullable: true cargoProvider: type: string description: 'Must not be greater than 64 characters.' example: v nullable: true cargoTrackingNo: type: string description: 'Must not be greater than 128 characters.' example: d nullable: true notes: type: string description: 'Sipariş notu.' example: 'Kapıda teslim.' nullable: true lines: type: array description: 'Sipariş satırları (en az 1).' example: - [] items: type: object properties: description: type: string description: 'Satır açıklaması.' example: 'USB-C Kablo 1m' productId: type: string description: 'Ürün ULID kimliği.' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z nullable: true variantId: type: string description: 'Must be 26 characters.' example: tcpscqldzsnrwtujwvlxjklqpp nullable: true sku: type: string description: "Ürün SKU'su." example: USB-C-1M nullable: true quantity: type: number description: 'Miktar (>0).' example: 5.0 unitCode: type: string description: 'Must not be greater than 16 characters.' example: miyvdljnikhwaykc nullable: true unitPrice: type: number description: 'Birim fiyat.' example: 100.0 discountAmount: type: number description: 'Must be at least 0.' example: 50 nullable: true vatRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 nullable: true required: - description - quantity - unitPrice required: - customerName - orderDate - lines '/api/public/v1/orders/{order_id}': get: summary: 'Sipariş görüntüle' operationId: sipariGrntle description: 'Tek bir siparişi satırları ve cari bilgisiyle birlikte döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: trendyol status: yeni statusLabel: Yeni paymentStatus: odendi externalOrderId: TY-987654321 partyId: null customerName: 'Ayşe Yılmaz' customerEmail: ayse@example.com customerPhone: '+905321234567' orderDate: '2026-01-22' subtotal: '500.00' taxTotal: '100.00' shippingAmount: '29.90' total: '629.90' invoiceId: null lines: - description: 'USB-C Kablo 1m' quantity: '5.0000' unitPrice: '100.00' vatRate: 20 createdAt: '2026-01-22T14:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: type: string example: SIP-2026-000045 source: type: string example: trendyol status: type: string example: yeni statusLabel: type: string example: Yeni paymentStatus: type: string example: odendi externalOrderId: type: string example: TY-987654321 partyId: type: string example: null nullable: true customerName: type: string example: 'Ayşe Yılmaz' customerEmail: type: string example: ayse@example.com customerPhone: type: string example: '+905321234567' orderDate: type: string example: '2026-01-22' subtotal: type: string example: '500.00' taxTotal: type: string example: '100.00' shippingAmount: type: string example: '29.90' total: type: string example: '629.90' invoiceId: type: string example: null nullable: true lines: type: array example: - description: 'USB-C Kablo 1m' quantity: '5.0000' unitPrice: '100.00' vatRate: 20 items: type: object properties: description: type: string example: 'USB-C Kablo 1m' quantity: type: string example: '5.0000' unitPrice: type: string example: '100.00' vatRate: type: integer example: 20 createdAt: type: string example: '2026-01-22T14:00:00+00:00' 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Siparişler patch: summary: 'Sipariş güncelle' operationId: sipariGncelle description: "Var olan bir siparişin müşteri/teslimat/ödeme bilgilerini kısmi olarak günceller.\nSatır kalemleri bu uç noktadan değiştirilmez." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Güncellendi content: application/json: schema: type: object example: data: id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: trendyol status: yeni statusLabel: Yeni paymentStatus: odendi customerName: 'Ayşe Yılmaz' customerPhone: '+905321234567' orderDate: '2026-01-22' subtotal: '500.00' taxTotal: '100.00' shippingAmount: '0.00' total: '600.00' createdAt: '2026-01-22T14:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: type: string example: SIP-2026-000045 source: type: string example: trendyol status: type: string example: yeni statusLabel: type: string example: Yeni paymentStatus: type: string example: odendi customerName: type: string example: 'Ayşe Yılmaz' customerPhone: type: string example: '+905321234567' orderDate: type: string example: '2026-01-22' subtotal: type: string example: '500.00' taxTotal: type: string example: '100.00' shippingAmount: type: string example: '0.00' total: type: string example: '600.00' createdAt: type: string example: '2026-01-22T14:00:00+00:00' tags: - Siparişler requestBody: required: false content: application/json: schema: type: object properties: customerName: type: string description: 'Müşteri adı.' example: 'Ayşe Yılmaz' customerEmail: type: string description: 'Müşteri e-posta adresi.' example: ayse@example.com nullable: true customerPhone: type: string description: 'Müşteri telefonu.' example: '+905321234567' nullable: true billingAddress: type: object description: '' example: null properties: { } nullable: true shippingAddress: type: object description: '' example: null properties: { } nullable: true deadlineDate: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' nullable: true paymentStatus: type: string description: 'Ödeme durumu (beklemede, odendi, kismi, iade).' example: odendi paymentMethod: type: string description: 'Must not be greater than 32 characters.' example: 'y' nullable: true shippingAmount: type: number description: 'Kargo tutarı.' example: 0.0 cargoProvider: type: string description: 'Kargo firması.' example: 'Yurtiçi Kargo' nullable: true cargoTrackingNo: type: string description: 'Kargo takip numarası.' example: YK1234567890 nullable: true notes: type: string description: 'Sipariş notu.' example: 'Adres güncellendi.' nullable: true parameters: - in: path name: order_id description: 'The ID of the order.' example: architecto required: true schema: type: string - in: path name: order description: 'Siparişin ULID kimliği.' example: 01JQAC3D4E5F6G7H8J9K0L1M2N required: true schema: type: string '/api/public/v1/orders/{order_id}/status': post: summary: 'Sipariş durumunu değiştir' operationId: sipariDurumunuDeitir description: 'Siparişi yeni bir duruma geçirir. Geçersiz durum geçişleri reddedilir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Durum güncellendi' content: application/json: schema: type: object example: data: id: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: SIP-2026-000045 source: trendyol status: onaylandi statusLabel: Onaylandı paymentStatus: odendi orderDate: '2026-01-22' total: '629.90' createdAt: '2026-01-22T14:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQAC3D4E5F6G7H8J9K0L1M2N orderNumber: type: string example: SIP-2026-000045 source: type: string example: trendyol status: type: string example: onaylandi statusLabel: type: string example: Onaylandı paymentStatus: type: string example: odendi orderDate: type: string example: '2026-01-22' total: type: string example: '629.90' createdAt: type: string example: '2026-01-22T14:00:00+00:00' 422: description: 'Geçersiz geçiş' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: status: - 'Seçilen durum geçersiz.' properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: status: type: array example: - 'Seçilen durum geçersiz.' items: type: string tags: - Siparişler requestBody: required: true content: application/json: schema: type: object properties: status: type: string description: 'Hedef durum (yeni, onaylandi, hazirlaniyor, kargoda, teslim, iptal, iade).' example: onaylandi required: - status parameters: - in: path name: order_id description: 'The ID of the order.' example: architecto required: true schema: type: string - in: path name: order description: 'Siparişin ULID kimliği.' example: 01JQAC3D4E5F6G7H8J9K0L1M2N required: true schema: type: string /api/public/v1/checks: get: summary: 'Çekleri listele' operationId: ekleriListele description: '' parameters: - in: query name: instrumentType description: 'Kıymet türü (cek, senet).' example: cek required: false schema: type: string description: 'Kıymet türü (cek, senet).' example: cek - in: query name: kind description: 'Çek yönü (alinan, verilen).' example: alinan required: false schema: type: string description: 'Çek yönü (alinan, verilen).' example: alinan - in: query name: status description: 'Duruma göre filtre.' example: portfoyde required: false schema: type: string description: 'Duruma göre filtre.' example: portfoyde - in: query name: from description: 'date Vade tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' required: false schema: type: string description: 'date Vade tarihi alt sınırı (YYYY-AA-GG).' example: '2026-01-01' - in: query name: to description: 'date Vade tarihi üst sınırı (YYYY-AA-GG).' example: '2026-12-31' required: false schema: type: string description: 'date Vade tarihi üst sınırı (YYYY-AA-GG).' example: '2026-12-31' - in: query name: search description: 'Çek no, keşideci, lehtar veya banka içinde arama.' example: '123456' required: false schema: type: string description: 'Çek no, keşideci, lehtar veya banka içinde arama.' example: '123456' - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler post: summary: 'Çek oluştur' operationId: ekOlutur description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: instrumentType: type: string description: 'Kıymet türü (cek, senet).' example: cek nullable: true kind: type: string description: 'Çek yönü (alinan, verilen).' example: alinan checkNumber: type: string description: 'Çek/senet numarası (6-12 hane).' example: '123456' serialNumber: type: string description: 'Must not be greater than 32 characters.' example: l nullable: true partyId: type: string description: 'The id of an existing record in the parties table. Must be 26 characters.' example: jnikhwaykcmyuwpwlvqwrsitcp nullable: true drawerName: type: string description: 'Must not be greater than 191 characters.' example: s nullable: true drawerTaxId: type: string description: 'Must not be greater than 11 characters.' example: cqldzs nullable: true beneficiaryName: type: string description: 'Must not be greater than 191 characters.' example: 'n' nullable: true bankName: type: string description: 'Banka adı.' example: 'İş Bankası' bankBranch: type: string description: 'Must not be greater than 100 characters.' example: w nullable: true bankAccountNo: type: string description: 'Must not be greater than 34 characters.' example: t nullable: true amount: type: number description: 'Tutar (0.01 - 999999999.99).' example: 1500.5 currencyCode: type: string description: 'Must be 3 characters.' example: jwv nullable: true issueDate: type: date description: 'Düzenleme tarihi.' example: '2026-01-20' dueDate: type: date description: "Vade tarihi (issueDate'ten önce olamaz)." example: '2026-02-19' notes: type: string description: 'Must not be greater than 1000 characters.' example: 'n' nullable: true required: - kind - checkNumber - bankName - amount - issueDate - dueDate '/api/public/v1/checks/{check_id}': get: summary: 'Çek görüntüle' operationId: ekGrntle description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler patch: summary: 'Çek güncelle' operationId: ekGncelle description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: false content: application/json: schema: type: object properties: instrumentType: type: string description: '' example: senet enum: - cek - senet kind: type: string description: '' example: verilen enum: - alinan - verilen checkNumber: type: string description: 'Must match the regex /^[0-9]{6,12}$/.' example: '564255' serialNumber: type: string description: 'Must not be greater than 32 characters.' example: l nullable: true partyId: type: string description: 'The id of an existing record in the parties table. Must be 26 characters.' example: jnikhwaykcmyuwpwlvqwrsitcp nullable: true drawerName: type: string description: 'Must not be greater than 191 characters.' example: s nullable: true drawerTaxId: type: string description: 'Must not be greater than 11 characters.' example: cqldzs nullable: true beneficiaryName: type: string description: 'Must not be greater than 191 characters.' example: 'n' nullable: true bankName: type: string description: 'Must not be greater than 100 characters.' example: r bankBranch: type: string description: 'Must not be greater than 100 characters.' example: w nullable: true bankAccountNo: type: string description: 'Must not be greater than 34 characters.' example: t nullable: true amount: type: number description: 'Must be at least 0.01. Must not be greater than 999999999.99.' example: 16 currencyCode: type: string description: 'Must be 3 characters.' example: jwv nullable: true issueDate: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' dueDate: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' notes: type: string description: 'Must not be greater than 1000 characters.' example: l nullable: true parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string - in: path name: check description: 'Çekin ULID kimliği.' example: 01JQ7Z8K3M4N5P6Q7R8S9T0V1W required: true schema: type: string '/api/public/v1/checks/{check_id}/collect': post: summary: 'Çeki tahsil et' operationId: ekiTahsilEt description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: cashAccountId: type: string description: 'Must be 26 characters.' example: bngzmiyvdljnikhwaykcmyuwpw date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: l nullable: true required: - cashAccountId - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/pay': post: summary: 'Çeki öde (verilen çek)' operationId: ekideverilenek description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: cashAccountId: type: string description: 'Must be 26 characters.' example: bngzmiyvdljnikhwaykcmyuwpw date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: l nullable: true required: - cashAccountId - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/endorse': post: summary: 'Çeki ciro et' operationId: ekiCiroEt description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: endorsedToPartyId: type: string description: 'The id of an existing record in the parties table. Must be 26 characters.' example: bngzmiyvdljnikhwaykcmyuwpw date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: l nullable: true required: - endorsedToPartyId - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/bounce': post: summary: 'Çeki karşılıksız işaretle' operationId: ekiKarlkszIaretle description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: b nullable: true required: - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/send-to-collection': post: summary: 'Çeki tahsilata gönder' operationId: ekiTahsilataGnder description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: false content: application/json: schema: type: object properties: note: type: string description: 'Must not be greater than 500 characters.' example: b nullable: true parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/return': post: summary: 'Çeki iade et' operationId: ekiIadeEt description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: b nullable: true required: - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string '/api/public/v1/checks/{check_id}/cancel': post: summary: 'Çeki iptal et (verilen çek)' operationId: ekiIptalEtverilenek description: '' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 401: description: '' content: application/json: schema: type: object example: error: code: unauthorized message: 'Geçersiz API kimlik bilgileri.' details: null properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: 'Geçersiz API kimlik bilgileri.' details: type: string example: null nullable: true tags: - Çekler requestBody: required: true content: application/json: schema: type: object properties: date: type: string description: 'Must be a valid date.' example: '2026-07-02T15:35:16' note: type: string description: 'Must not be greater than 500 characters.' example: b nullable: true required: - date parameters: - in: path name: check_id description: 'The ID of the check.' example: architecto required: true schema: type: string /api/public/v1/products: get: summary: 'Ürünleri listele' operationId: rnleriListele description: "Ürün kayıtlarını sayfalı olarak döner. Ad veya SKU üzerinden arama ve\ndurum/düşük stok filtreleri uygulanabilir." parameters: - in: query name: query description: 'Ad veya SKU içinde arama terimi.' example: kablo required: false schema: type: string description: 'Ad veya SKU içinde arama terimi.' example: kablo - in: query name: status description: 'Duruma göre filtre (active, passive, draft).' example: active required: false schema: type: string description: 'Duruma göre filtre (active, passive, draft).' example: active - in: query name: lowStock description: 'true ise yalnızca düşük stoklu ürünler döner.' example: true required: false schema: type: boolean description: 'true ise yalnızca düşük stoklu ürünler döner.' example: true - in: query name: perPage description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 required: false schema: type: integer description: 'Sayfa başına kayıt (1-100, varsayılan 20).' example: 20 - in: query name: page description: 'Sayfa numarası.' example: 1 required: false schema: type: integer description: 'Sayfa numarası.' example: 1 - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: 'Başarılı liste' content: application/json: schema: type: object example: data: - id: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: 'USB-C Kablo 1m' sku: USB-C-1M type: simple status: active trackStock: true unit: C62 price: '49.90' taxRate: 20 priceIncludingTax: '59.88' stockQuantity: '120.0000' lowStockThreshold: '10.0000' isLowStock: false createdAt: '2026-01-10T08:00:00+00:00' meta: currentPage: 1 lastPage: 4 perPage: 20 total: 73 properties: data: type: array example: - id: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: 'USB-C Kablo 1m' sku: USB-C-1M type: simple status: active trackStock: true unit: C62 price: '49.90' taxRate: 20 priceIncludingTax: '59.88' stockQuantity: '120.0000' lowStockThreshold: '10.0000' isLowStock: false createdAt: '2026-01-10T08:00:00+00:00' items: type: object properties: id: type: string example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: type: string example: 'USB-C Kablo 1m' sku: type: string example: USB-C-1M type: type: string example: simple status: type: string example: active trackStock: type: boolean example: true unit: type: string example: C62 price: type: string example: '49.90' taxRate: type: integer example: 20 priceIncludingTax: type: string example: '59.88' stockQuantity: type: string example: '120.0000' lowStockThreshold: type: string example: '10.0000' isLowStock: type: boolean example: false createdAt: type: string example: '2026-01-10T08:00:00+00:00' meta: type: object properties: currentPage: type: integer example: 1 lastPage: type: integer example: 4 perPage: type: integer example: 20 total: type: integer example: 73 tags: - Ürünler post: summary: 'Ürün oluştur' operationId: rnOlutur description: "Yeni bir ürün veya hizmet kaydı oluşturur. `slug` verilmezse ad üzerinden üretilir.\nHizmet türü ürünlerde stok takibi devre dışıdır. Idempotency-Key başlığı desteklenir." parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 201: description: Oluşturuldu content: application/json: schema: type: object example: data: id: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: 'USB-C Kablo 1m' sku: USB-C-1M type: simple status: active trackStock: true unit: C62 price: '49.90' taxRate: 20 priceIncludingTax: '59.88' stockQuantity: '120.0000' lowStockThreshold: '10.0000' isLowStock: false createdAt: '2026-01-10T08:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: type: string example: 'USB-C Kablo 1m' sku: type: string example: USB-C-1M type: type: string example: simple status: type: string example: active trackStock: type: boolean example: true unit: type: string example: C62 price: type: string example: '49.90' taxRate: type: integer example: 20 priceIncludingTax: type: string example: '59.88' stockQuantity: type: string example: '120.0000' lowStockThreshold: type: string example: '10.0000' isLowStock: type: boolean example: false createdAt: type: string example: '2026-01-10T08:00:00+00:00' 422: description: 'Doğrulama hatası' content: application/json: schema: type: object example: error: code: validation_error message: 'Gönderilen veriler geçersiz.' details: sku: - "SKU yalnızca A-Z, 0-9, '-' karakterleri içerebilir (3-32 karakter)." properties: error: type: object properties: code: type: string example: validation_error message: type: string example: 'Gönderilen veriler geçersiz.' details: type: object properties: sku: type: array example: - "SKU yalnızca A-Z, 0-9, '-' karakterleri içerebilir (3-32 karakter)." items: type: string tags: - Ürünler requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: 'Ürün adı (en fazla 190 karakter).' example: 'USB-C Kablo 1m' slug: type: string description: 'Must match the regex /^[a-z0-9-]+$/. Must not be greater than 190 characters.' example: 'n' nullable: true productType: type: string description: 'Ürün türü (simple, variant_parent, service).' example: simple nullable: true sku: type: string description: 'Stok kodu (3-32, yalnızca A-Z 0-9 -).' example: USB-C-1M nullable: true gtin: type: string description: 'Barkod (8/12/13/14 hane, geçerli kontrol hanesi).' example: '8690000000018' nullable: true description: type: string description: Açıklama. example: '1 metre örgülü USB-C kablo' nullable: true categoryId: type: string description: 'Kategori ULID kimliği (26 karakter).' example: 01JQ8AABBCCDDEEFF0011223344 nullable: true unitCode: type: string description: 'Birim kodu (varsayılan C62 / hizmette HUR).' example: C62 nullable: true taxRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 nullable: true price: type: number description: 'Satış fiyatı (KDV hariç).' example: 49.9 nullable: true costPrice: type: number description: 'Alış/maliyet fiyatı.' example: 30.0 nullable: true currencyCode: type: string description: 'ISO 4217 para birimi kodu.' example: TRY nullable: true trackStock: type: boolean description: 'Stok takibi yapılsın mı.' example: true nullable: true stockQuantity: type: number description: 'Başlangıç stok miktarı.' example: 120.0 nullable: true lowStockThreshold: type: number description: 'Düşük stok eşiği.' example: 10.0 nullable: true weightGrams: type: number description: 'Must be at least 0.' example: 28 nullable: true dimensions: type: object description: '' example: null properties: { } nullable: true images: type: array description: 'Must not be greater than 500 characters.' example: - v items: type: string attributes: type: object description: '' example: null properties: { } nullable: true externalRefs: type: object description: '' example: null properties: { } nullable: true status: type: string description: 'Durum (active, passive, draft).' example: active nullable: true required: - name '/api/public/v1/products/{product_id}': get: summary: 'Ürün görüntüle' operationId: rnGrntle description: 'Tek bir ürünün ayrıntılarını, varsa kategori bilgisiyle birlikte döner.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Başarılı content: application/json: schema: type: object example: data: id: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: 'USB-C Kablo 1m' sku: USB-C-1M type: simple status: active trackStock: true unit: C62 price: '49.90' taxRate: 20 priceIncludingTax: '59.88' stockQuantity: '120.0000' lowStockThreshold: '10.0000' isLowStock: false category: id: 01JQ8AABBCCDDEEFF0011223344 name: Kablolar createdAt: '2026-01-10T08:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: type: string example: 'USB-C Kablo 1m' sku: type: string example: USB-C-1M type: type: string example: simple status: type: string example: active trackStock: type: boolean example: true unit: type: string example: C62 price: type: string example: '49.90' taxRate: type: integer example: 20 priceIncludingTax: type: string example: '59.88' stockQuantity: type: string example: '120.0000' lowStockThreshold: type: string example: '10.0000' isLowStock: type: boolean example: false category: type: object properties: id: type: string example: 01JQ8AABBCCDDEEFF0011223344 name: type: string example: Kablolar createdAt: type: string example: '2026-01-10T08:00:00+00:00' 404: description: Bulunamadı content: application/json: schema: type: object example: error: code: not_found message: 'Kayıt bulunamadı.' properties: error: type: object properties: code: type: string example: not_found message: type: string example: 'Kayıt bulunamadı.' tags: - Ürünler patch: summary: 'Ürün güncelle' operationId: rnGncelle description: 'Var olan bir ürünü kısmi olarak günceller. Ad değişip slug boş bırakılırsa slug yeniden üretilir.' parameters: - in: header name: X-Api-Key description: '' example: '{API_ANAHTARINIZ}' schema: type: string responses: 200: description: Güncellendi content: application/json: schema: type: object example: data: id: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: 'USB-C Kablo 2m' sku: USB-C-1M type: simple status: passive trackStock: true unit: C62 price: '69.90' taxRate: 20 priceIncludingTax: '83.88' stockQuantity: '80.0000' lowStockThreshold: '15.0000' isLowStock: false createdAt: '2026-01-10T08:00:00+00:00' properties: data: type: object properties: id: type: string example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z name: type: string example: 'USB-C Kablo 2m' sku: type: string example: USB-C-1M type: type: string example: simple status: type: string example: passive trackStock: type: boolean example: true unit: type: string example: C62 price: type: string example: '69.90' taxRate: type: integer example: 20 priceIncludingTax: type: string example: '83.88' stockQuantity: type: string example: '80.0000' lowStockThreshold: type: string example: '15.0000' isLowStock: type: boolean example: false createdAt: type: string example: '2026-01-10T08:00:00+00:00' tags: - Ürünler requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: 'Ürün adı.' example: 'USB-C Kablo 2m' slug: type: string description: 'Must match the regex /^[a-z0-9-]+$/. Must not be greater than 190 characters.' example: 'n' nullable: true productType: type: string description: '' example: service enum: - simple - variant_parent - service sku: type: string description: 'Must match the regex /^[A-Z0-9-]{3,32}$/. Must be at least 3 characters. Must not be greater than 32 characters.' example: g nullable: true gtin: type: string description: 'Must match the regex /^\d{8}$|^\d{12,14}$/. Must not be greater than 14 characters.' example: zmiyvdljnikhwa nullable: true description: type: string description: 'Must not be greater than 5000 characters.' example: 'Perspiciatis quo omnis nostrum aut adipisci quidem nostrum qui.' nullable: true categoryId: type: string description: 'Must be 26 characters.' example: vqwrsitcpscqldzsnrwtujwvlx nullable: true unitCode: type: string description: 'Must not be greater than 16 characters.' example: jklqppwqbewtnnoq taxRate: type: number description: 'KDV oranı (0, 1, 10, 20).' example: 20.0 price: type: number description: 'Satış fiyatı (KDV hariç).' example: 69.9 costPrice: type: number description: 'Must be at least 0.' example: 67 nullable: true currencyCode: type: string description: 'Must be 3 characters.' example: xnt trackStock: type: boolean description: '' example: false lowStockThreshold: type: number description: 'Düşük stok eşiği.' example: 15.0 nullable: true weightGrams: type: number description: 'Must be at least 0.' example: 6 nullable: true dimensions: type: object description: '' example: null properties: { } nullable: true images: type: object description: '' example: null properties: { } nullable: true attributes: type: object description: '' example: null properties: { } nullable: true externalRefs: type: object description: '' example: null properties: { } nullable: true status: type: string description: 'Durum (active, passive, draft).' example: passive stockQuantity: type: number description: 'Stok miktarı.' example: 80.0 parameters: - in: path name: product_id description: 'The ID of the product.' example: architecto required: true schema: type: string - in: path name: product description: 'Ürünün ULID kimliği.' example: 01JQ8A0P2R3S4T5U6V7W8X9Y0Z required: true schema: type: string