{ "openapi": "3.0.3", "info": { "title": "CariErp Açık API", "version": "1.0.0", "description": "CariErp Açık API ile kendi yazılımınızdan (ERP, e-ticaret sitesi, WHMCS, faturalama sistemi) cari, ürün, fatura, e-Fatura / e-Arşiv, tahsilat ve kasa-banka kayıtlarınıza erişirsiniz.\n\n## Kimlik doğrulama\nPanelde **Entegrasyonlar › API ve webhook** ekranında API anahtarı üretin. Anahtar yalnız oluşturulduğu anda bir kez gösterilir, tek şirkete bağlıdır ve seçtiğiniz kapsamlarla (`fatura:write`, `cari:read` …) sınırlıdır. Her istekte gönderin:\n\n`Authorization: Bearer dfk_…` (ya da `X-Api-Key: dfk_…`)\n\nAnahtarı iptal ettiğinizde hemen geçersiz olur. Şirket `X-Company-Id` başlığı gerekmez; anahtar şirketi belirler.\n\n## Biçim\n- Alan adları `snake_case`. Tutarlar iki ondalıklı metindir: `\"1250.00\"`. Miktar ve oranlar ondalık metindir: `\"1.5\"`, `\"20\"`.\n- Tarihler `YYYY-AA-GG`, zaman damgaları ISO 8601 (UTC).\n- Girdi tutarı metin ya da sayı olabilir (\"1250.50\" ya da 1250.5).\n\n## Sayfalama\nListeler `page` (1'den başlar) ve `per_page` (en çok 100, varsayılan 25) alır. Yanıt: `{ \"data\": [...], \"meta\": { \"page\", \"per_page\", \"total\", \"total_pages\" } }`. Değişiklikleri çekmek için `updated_since` kullanın.\n\n## Hatalar\nBütün hatalar aynı biçimdedir: `{ \"error\": { \"code\", \"message\", \"details\" } }`. `code` makinece okunur ve değişmez; `message` Türkçe ve kullanıcıya gösterilebilir. 4xx yanıtları yeniden denemeyin (429 hariç); 5xx'te üstel bekleyerek yeniden deneyin.\n\n## İstek sınırı\nAnahtar başına dakikada 120 istek. Her yanıtta `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset` başlıkları döner; aşılırsa 429 `ISTEK_SINIRI` ve `retry-after` (saniye).\n\n## Tekrar güvenliği\nBelge oluşturan `POST` isteklerinde `Idempotency-Key` başlığı gönderin (ör. dış sistemdeki fatura no). Aynı anahtarla 24 saat içinde gelen tekrar istek yeni kayıt açmaz; ilk yanıt `Idempotent-Replay: true` başlığıyla döner.\n\n## e-Fatura ve e-Arşiv\nFaturayı `issue: true` ile kesin, `send: true` ile GİB'e gönderin. Alıcı GİB'de kayıtlı e-Fatura kullanıcısıysa e-Fatura, değilse e-Arşiv olarak gider; hangisinin kullanılacağına CariErp karar verir. Gönderim jetonla ücretlendirilir. GİB durumu `e_document.status` alanındadır (`gonderiliyor`, `iletildi`, `kabul`, `red`, `iptal`, `hata`) ve her değişimde `invoice.status_changed` webhook'u gider.\n\n## Webhook\nOlaylara abone olmak için `POST /webhooks`. Her teslim `POST` + JSON gövde: `{ \"id\": \"evt_…\", \"event\": \"invoice.paid\", \"created_at\", \"company_id\", \"data\": { … } }`. `data` kaydın teslim anındaki hâlidir (fatura olaylarında fatura nesnesi).\n\nBaşlıklar: `X-CariErp-Olay`, `X-CariErp-Teslim` (olay kimliği; aynı olay birden fazla gelebilir, bununla tekilleştirin), `X-CariErp-Zaman` (unix saniye), `X-CariErp-Imza: sha256=`.\n\nİmza: `HMAC-SHA256(imza_anahtari, X-CariErp-Zaman + \".\" + ham_gövde)`. İmza anahtarı (`whsec_…`) ilk uç noktayı eklerken bir kez döner. 5 dakikadan eski zaman damgalarını reddedin. 2xx dışındaki yanıtlar artan aralıklarla 6 kez yeniden denenir.\n\nOlaylar: `invoice.created` (Fatura kesildi), `invoice.sent` (Fatura GİB'e iletildi), `invoice.status_changed` (Faturanın GİB durumu değişti), `invoice.paid` (Fatura tamamen ödendi), `invoice.cancelled` (Fatura iptal edildi), `payment.received` (Tahsilat kaydedildi), `contact.updated` (Cari eklendi ya da güncellendi), `order.created` (Pazaryeri/site siparişi geldi), `stock.low` (Kritik stok seviyesine inildi).", "contact": { "name": "CariErp Geliştirici Desteği", "url": "https://carierp.com/gelistirici", "email": "destek@carierp.com" } }, "servers": [ { "url": "https://app.carierp.com/api/open/v1", "description": "Canlı" } ], "tags": [ { "name": "Hesap", "description": "Bağlantı denemesi ve anahtar bilgisi" }, { "name": "Cariler", "description": "Müşteri ve tedarikçi kartları" }, { "name": "Ürünler ve stok", "description": "Ürün ve hizmet kartları, depo bazında stok" }, { "name": "Faturalar", "description": "Satış ve alış faturaları: oluşturma, kesme, PDF, iptal" }, { "name": "e-Fatura ve e-Arşiv", "description": "e-Fatura / e-Arşiv gönderimi ve GİB durumu" }, { "name": "Tahsilat ve ödemeler", "description": "Fatura tahsilatları ve cari tahsilat/ödemeleri" }, { "name": "Kasa ve banka", "description": "Kasa, banka, kredi kartı ve POS hesapları ile hareketleri" }, { "name": "Webhook", "description": "Olay bildirimleri" } ], "paths": { "/contacts": { "get": { "summary": "Carileri listele", "tags": [ "Cariler" ], "description": "Müşteri ve tedarikçi kartları; en yeni önce.\n\n**Kapsam:** `cari:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "q", "required": false, "description": "Ad, VKN/TCKN, e-posta, telefon ya da kodda arama" }, { "schema": { "type": "string" }, "in": "query", "name": "tax_number", "required": false, "description": "VKN/TCKN tam eşleşme" }, { "schema": { "type": "string" }, "in": "query", "name": "email", "required": false, "description": "E-posta tam eşleşme (büyük/küçük harf duyarsız)" }, { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, { "schema": { "type": "string", "enum": [ "musteri", "tedarikci", "her_ikisi" ] }, "in": "query", "name": "role", "required": false, "description": "Cari türü: musteri | tedarikci | her_ikisi" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "is_active", "required": false, "description": "Etkin mi; false ise arşivlenmiş" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "updated_since", "required": false, "description": "Bu zamandan sonra değişenler (ISO 8601)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CariListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getContacts" }, "post": { "summary": "Cari oluştur", "tags": [ "Cariler" ], "description": "VKN/TCKN kontrol hanesiyle doğrulanır. `Idempotency-Key` başlığı desteklenir.\n\n**Kapsam:** `cari:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "Varsayılan musteri", "type": "string", "enum": [ "musteri", "tedarikci", "her_ikisi" ] }, "kind": { "description": "Varsayılan: 11 haneli TCKN verilirse bireysel, değilse kurumsal", "type": "string", "enum": [ "kurumsal", "bireysel" ] }, "name": { "description": "Ünvan; bireyselde boşsa ad soyaddan üretilir", "type": "string", "minLength": 1, "maxLength": 250 }, "first_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Ad (bireysel)" }, "last_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Soyad (bireysel)" }, "code": { "nullable": true, "type": "string", "maxLength": 60, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "tax_number": { "nullable": true, "type": "string", "pattern": "^\\d{10,11}$", "description": "VKN (10 hane) ya da TCKN (11 hane)" }, "tax_office": { "nullable": true, "type": "string", "maxLength": 120, "description": "Vergi dairesi" }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "E-posta adresi; e-Arşiv fatura bu adrese de gönderilir" }, "phone": { "nullable": true, "type": "string", "maxLength": 40, "description": "Telefon (ör. +902161234567)" }, "mobile": { "nullable": true, "type": "string", "maxLength": 40, "description": "Cep telefonu" }, "website": { "nullable": true, "type": "string", "maxLength": 200, "description": "Web sitesi" }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "iban": { "nullable": true, "type": "string", "description": "IBAN (TR ile başlayan, doğrulanır)" }, "billing_address": { "nullable": true, "type": "object", "properties": { "line": { "description": "Açık adres", "nullable": true, "type": "string" }, "district": { "description": "İlçe", "nullable": true, "type": "string" }, "city": { "description": "İl", "nullable": true, "type": "string" }, "postal_code": { "nullable": true, "type": "string", "description": "Posta kodu" }, "country": { "description": "Ülke (varsayılan Türkiye)", "nullable": true, "type": "string" } }, "description": "Fatura adresi" }, "notes": { "nullable": true, "type": "string", "maxLength": 2000, "description": "Not" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" } }, "example": { "role": "musteri", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890", "tax_office": "Kadıköy", "email": "muhasebe@ornekbilisim.com.tr", "phone": "+902161234567", "billing_address": { "line": "Caferağa Mah. Moda Cad. No: 10", "district": "Kadıköy", "city": "İstanbul", "postal_code": "34710" } } } } } }, "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cari" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postContacts" } }, "/contacts/{id}": { "get": { "summary": "Cari detayı", "tags": [ "Cariler" ], "description": "**Kapsam:** `cari:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cari" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getContactsById" }, "patch": { "summary": "Cariyi güncelle", "tags": [ "Cariler" ], "description": "Yalnız gönderilen alanlar değişir.\n\n**Kapsam:** `cari:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "Varsayılan musteri", "type": "string", "enum": [ "musteri", "tedarikci", "her_ikisi" ] }, "kind": { "description": "Varsayılan: 11 haneli TCKN verilirse bireysel, değilse kurumsal", "type": "string", "enum": [ "kurumsal", "bireysel" ] }, "name": { "description": "Ünvan; bireyselde boşsa ad soyaddan üretilir", "type": "string", "minLength": 1, "maxLength": 250 }, "first_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Ad (bireysel)" }, "last_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Soyad (bireysel)" }, "code": { "nullable": true, "type": "string", "maxLength": 60, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "tax_number": { "nullable": true, "type": "string", "pattern": "^\\d{10,11}$", "description": "VKN (10 hane) ya da TCKN (11 hane)" }, "tax_office": { "nullable": true, "type": "string", "maxLength": 120, "description": "Vergi dairesi" }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "E-posta adresi; e-Arşiv fatura bu adrese de gönderilir" }, "phone": { "nullable": true, "type": "string", "maxLength": 40, "description": "Telefon (ör. +902161234567)" }, "mobile": { "nullable": true, "type": "string", "maxLength": 40, "description": "Cep telefonu" }, "website": { "nullable": true, "type": "string", "maxLength": 200, "description": "Web sitesi" }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "iban": { "nullable": true, "type": "string", "description": "IBAN (TR ile başlayan, doğrulanır)" }, "billing_address": { "nullable": true, "type": "object", "properties": { "line": { "description": "Açık adres", "nullable": true, "type": "string" }, "district": { "description": "İlçe", "nullable": true, "type": "string" }, "city": { "description": "İl", "nullable": true, "type": "string" }, "postal_code": { "nullable": true, "type": "string", "description": "Posta kodu" }, "country": { "description": "Ülke (varsayılan Türkiye)", "nullable": true, "type": "string" } }, "description": "Fatura adresi" }, "notes": { "nullable": true, "type": "string", "maxLength": 2000, "description": "Not" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" } }, "example": { "phone": "+902161234567", "email": "fatura@ornekbilisim.com.tr" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cari" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "patchContactsById" }, "delete": { "summary": "Cariyi arşivle", "tags": [ "Cariler" ], "description": "Kayıt silinmez; pasife alınır (`is_active: false`). Hareketleri ve faturaları korunur.\n\n**Kapsam:** `cari:delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cari" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "deleteContactsById" } }, "/products": { "get": { "summary": "Ürün ve hizmetleri listele", "tags": [ "Ürünler ve stok" ], "description": "**Kapsam:** `stok:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "q", "required": false, "description": "Ad, stok kodu ya da barkodda arama" }, { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, { "schema": { "type": "string" }, "in": "query", "name": "barcode", "required": false, "description": "Barkod (EAN/GTIN)" }, { "schema": { "type": "string", "enum": [ "urun", "hizmet" ] }, "in": "query", "name": "type", "required": false, "description": "Tür" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "is_active", "required": false, "description": "Etkin mi; false ise arşivlenmiş" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "updated_since", "required": false, "description": "Bu zamandan sonra değişen kayıtlar (ISO 8601)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrunListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getProducts" }, "post": { "summary": "Ürün ya da hizmet oluştur", "tags": [ "Ürünler ve stok" ], "description": "Stok kodu (`code`) şirkette benzersizdir; aynısı varsa 409 KAYIT_ZATEN_VAR.\n\n**Kapsam:** `stok:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Varsayılan urun; hizmette stok tutulmaz", "type": "string", "enum": [ "urun", "hizmet" ] }, "code": { "nullable": true, "type": "string", "maxLength": 60, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "barcode": { "nullable": true, "type": "string", "maxLength": 60, "description": "Barkod (EAN/GTIN)" }, "name": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Ad ya da ünvan" }, "description": { "nullable": true, "type": "string", "maxLength": 2000, "description": "Açıklama" }, "unit": { "description": "Birim: adet, kg, g, lt, m, m2, m3, paket, kutu, koli, saat, gun, ay", "type": "string", "enum": [ "adet", "kg", "g", "lt", "m", "m2", "m3", "paket", "kutu", "koli", "saat", "gun", "ay" ] }, "sale_price": { "description": "KDV hariç satış fiyatı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "purchase_price": { "description": "KDV hariç alış fiyatı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "vat_rate": { "description": "KDV oranı (varsayılan 20)", "type": "string", "enum": [ "0", "1", "10", "20" ] }, "track_stock": { "type": "boolean", "description": "Stok takibi yapılsın mı (hizmette false)" }, "critical_level": { "description": "Kritik stok seviyesi: stok bu miktara inince uyarı verilir", "nullable": true, "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "string", "pattern": "^\\d+([.,]\\d{1,4})?$" } ] }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" } }, "required": [ "name" ], "example": { "type": "hizmet", "code": "HOST-PRO", "name": "Profesyonel hosting (yıllık)", "unit": "adet", "sale_price": "1200.00", "vat_rate": "20" } } } } }, "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Urun" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postProducts" } }, "/products/{id}": { "get": { "summary": "Ürün detayı", "tags": [ "Ürünler ve stok" ], "description": "**Kapsam:** `stok:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Urun" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getProductsById" }, "patch": { "summary": "Ürünü güncelle", "tags": [ "Ürünler ve stok" ], "description": "**Kapsam:** `stok:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Varsayılan urun; hizmette stok tutulmaz", "type": "string", "enum": [ "urun", "hizmet" ] }, "code": { "nullable": true, "type": "string", "maxLength": 60, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "barcode": { "nullable": true, "type": "string", "maxLength": 60, "description": "Barkod (EAN/GTIN)" }, "name": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Ad ya da ünvan" }, "description": { "nullable": true, "type": "string", "maxLength": 2000, "description": "Açıklama" }, "unit": { "description": "Birim: adet, kg, g, lt, m, m2, m3, paket, kutu, koli, saat, gun, ay", "type": "string", "enum": [ "adet", "kg", "g", "lt", "m", "m2", "m3", "paket", "kutu", "koli", "saat", "gun", "ay" ] }, "sale_price": { "description": "KDV hariç satış fiyatı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "purchase_price": { "description": "KDV hariç alış fiyatı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "vat_rate": { "description": "KDV oranı (varsayılan 20)", "type": "string", "enum": [ "0", "1", "10", "20" ] }, "track_stock": { "type": "boolean", "description": "Stok takibi yapılsın mı (hizmette false)" }, "critical_level": { "description": "Kritik stok seviyesi: stok bu miktara inince uyarı verilir", "nullable": true, "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "string", "pattern": "^\\d+([.,]\\d{1,4})?$" } ] }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" } }, "example": { "sale_price": "1350.00", "is_active": true } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Urun" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "patchProductsById" } }, "/products/{id}/stock": { "get": { "summary": "Depo bazında stok", "tags": [ "Ürünler ve stok" ], "description": "**Kapsam:** `stok:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Ürün/hizmet kartı kimliği" }, "total": { "type": "string", "description": "Toplam" }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "warehouse_id": { "type": "string", "description": "Depo kimliği" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "quantity": { "type": "string", "description": "Miktar" } }, "required": [ "warehouse_id", "name", "quantity" ], "additionalProperties": false }, "description": "Depo bazında miktarlar" } }, "required": [ "product_id", "total", "warehouses" ], "additionalProperties": false, "example": { "product_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "total": "42", "warehouses": [ { "warehouse_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "name": "Merkez depo", "quantity": "40" }, { "warehouse_id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Mağaza", "quantity": "2" } ] } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getProductsByIdStock" } }, "/products/{id}/stock-adjustments": { "post": { "summary": "Stok düzelt (giriş/çıkış)", "tags": [ "Ürünler ve stok" ], "description": "Sayım farkı ya da dış sistemden gelen stok hareketi. Stok takipli olmayan üründe 422 STOK_TAKIBI_YOK.\n\n**Kapsam:** `stok:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "description": "İşaretli miktar: giriş pozitif, çıkış negatif", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,4})?$" } ] }, "warehouse_id": { "description": "Boşsa varsayılan depo", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "unit_cost": { "description": "Girişte birim maliyet (KDV hariç)", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "description": { "type": "string", "maxLength": 250, "description": "Açıklama" } }, "required": [ "quantity" ], "example": { "quantity": "-2", "description": "Sayım farkı" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Ürün/hizmet kartı kimliği" }, "total": { "type": "string", "description": "Toplam" }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "warehouse_id": { "type": "string", "description": "Depo kimliği" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "quantity": { "type": "string", "description": "Miktar" } }, "required": [ "warehouse_id", "name", "quantity" ], "additionalProperties": false }, "description": "Depo bazında miktarlar" } }, "required": [ "product_id", "total", "warehouses" ], "additionalProperties": false, "example": { "product_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "total": "42", "warehouses": [ { "warehouse_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "name": "Merkez depo", "quantity": "40" }, { "warehouse_id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Mağaza", "quantity": "2" } ] } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postProductsByIdStockAdjustments" } }, "/invoices": { "get": { "summary": "Faturaları listele", "tags": [ "Faturalar" ], "description": "Kalemler listede yer almaz; detay için GET /invoices/{id}. Arşivlenmiş faturalar listelenmez.\n\n**Kapsam:** `fatura:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "q", "required": false, "description": "Numara, cari adı ya da sipariş no" }, { "schema": { "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Virgülle çoklu: satis,toptan" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Virgülle çoklu: kesildi,odendi" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "contact_id", "required": false, "description": "Cari kimliği" }, { "schema": { "type": "string" }, "in": "query", "name": "order_no", "required": false, "description": "Sipariş no tam eşleşme" }, { "schema": { "type": "string" }, "in": "query", "name": "number", "required": false, "description": "Fatura numarası tam eşleşme" }, { "schema": { "type": "string", "enum": [ "efatura", "earsiv", "kagit" ] }, "in": "query", "name": "e_document_type", "required": false, "description": "Belge türü: efatura | earsiv | kagit" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "Fatura tarihi başlangıcı" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false, "description": "Fatura tarihi bitişi" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "in": "query", "name": "updated_since", "required": false, "description": "Bu zamandan sonra değişen kayıtlar (ISO 8601)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaturaListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getInvoices" }, "post": { "summary": "Fatura oluştur (taslak, kes ya da kesip GİB’e gönder)", "tags": [ "Faturalar" ], "description": "Cari `contact_id` ile ya da `contact` nesnesiyle verilir (VKN/TCKN ya da e-postayla eşleşir, yoksa açılır).\n\n`issue: true` faturayı keser; `send: true` kesip e-Fatura ya da e-Arşiv olarak gönderir. Hangisinin kullanılacağına alıcının GİB kaydına göre CariErp karar verir.\n\nAynı isteğin iki kez işlenmemesi için `Idempotency-Key` başlığı gönderin (24 saat geçerli; tekrar istekte ilk yanıt `Idempotent-Replay: true` ile döner).\n\nFirmada onay kuralı varsa yanıt 202 ve `status: onay_bekliyor` olur.\n\n**Kapsam:** `fatura:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "default": "satis", "description": "Belge türü; dış sistemlerden genellikle satis", "type": "string", "enum": [ "satis", "toptan", "perakende", "gelir", "alis", "gider", "satis_iade", "alis_iade" ] }, "contact_id": { "description": "Cari kimliği; ya bu ya da `contact` verilir", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "contact": { "description": "Cari bilgileri: VKN/TCKN, yoksa e-posta ile eşleşir; bulunamazsa cari açılır", "type": "object", "properties": { "role": { "description": "Varsayılan musteri", "type": "string", "enum": [ "musteri", "tedarikci", "her_ikisi" ] }, "kind": { "description": "Varsayılan: 11 haneli TCKN verilirse bireysel, değilse kurumsal", "type": "string", "enum": [ "kurumsal", "bireysel" ] }, "name": { "description": "Ünvan; bireyselde boşsa ad soyaddan üretilir", "type": "string", "minLength": 1, "maxLength": 250 }, "first_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Ad (bireysel)" }, "last_name": { "nullable": true, "type": "string", "maxLength": 120, "description": "Soyad (bireysel)" }, "code": { "nullable": true, "type": "string", "maxLength": 60, "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "tax_number": { "nullable": true, "type": "string", "pattern": "^\\d{10,11}$", "description": "VKN (10 hane) ya da TCKN (11 hane)" }, "tax_office": { "nullable": true, "type": "string", "maxLength": 120, "description": "Vergi dairesi" }, "email": { "nullable": true, "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "E-posta adresi; e-Arşiv fatura bu adrese de gönderilir" }, "phone": { "nullable": true, "type": "string", "maxLength": 40, "description": "Telefon (ör. +902161234567)" }, "mobile": { "nullable": true, "type": "string", "maxLength": 40, "description": "Cep telefonu" }, "website": { "nullable": true, "type": "string", "maxLength": 200, "description": "Web sitesi" }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "iban": { "nullable": true, "type": "string", "description": "IBAN (TR ile başlayan, doğrulanır)" }, "billing_address": { "nullable": true, "type": "object", "properties": { "line": { "description": "Açık adres", "nullable": true, "type": "string" }, "district": { "description": "İlçe", "nullable": true, "type": "string" }, "city": { "description": "İl", "nullable": true, "type": "string" }, "postal_code": { "nullable": true, "type": "string", "description": "Posta kodu" }, "country": { "description": "Ülke (varsayılan Türkiye)", "nullable": true, "type": "string" } }, "description": "Fatura adresi" }, "notes": { "nullable": true, "type": "string", "maxLength": 2000, "description": "Not" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" } }, "example": { "role": "musteri", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890", "tax_office": "Kadıköy", "email": "muhasebe@ornekbilisim.com.tr", "phone": "+902161234567", "billing_address": { "line": "Caferağa Mah. Moda Cad. No: 10", "district": "Kadıköy", "city": "İstanbul", "postal_code": "34710" } } }, "issue_date": { "description": "Fatura tarihi (varsayılan bugün; GİB kuralı gereği aynı seride geriye tarih atılamaz)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "due_date": { "nullable": true, "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Vade tarihi (YYYY-AA-GG)" }, "currency": { "type": "string", "enum": [ "TRY", "USD", "EUR", "GBP" ], "description": "Para birimi" }, "exchange_rate": { "description": "Dövizli faturada kur (boşsa TCMB satış kuru)", "anyOf": [ { "type": "number", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "pattern": "^\\d+([.,]\\d+)?$" } ] }, "series": { "description": "Fatura serisi (ör. WHM); boşsa şirketin varsayılan serisi", "type": "string", "pattern": "^[A-Za-z0-9]{3}$" }, "order_no": { "description": "Dış sistemdeki sipariş/fatura numarası; faturada görünür ve listede aranabilir", "nullable": true, "type": "string", "maxLength": 60 }, "notes": { "description": "Faturadaki not", "nullable": true, "type": "string", "maxLength": 2000 }, "payment_method": { "nullable": true, "type": "string", "maxLength": 60, "description": "Ödeme şekli (faturada görünür; ör. Kredi kartı)" }, "scenario": { "description": "e-Fatura alıcısında senaryo (varsayılan TEMELFATURA)", "type": "string", "enum": [ "TEMELFATURA", "TICARIFATURA" ] }, "prices_include_vat": { "default": false, "description": "true ise birim fiyatlar KDV dahildir; toplam kuruşu kuruşuna korunur", "type": "boolean" }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "product_id": { "description": "Ürün/hizmet kartı; verilirse ad, birim ve KDV karttan gelir", "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": { "description": "Kalem adı (ürün verilmezse zorunlu)", "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "description": "Miktar (en çok 4 ondalık)", "anyOf": [ { "type": "number", "minimum": 0, "exclusiveMinimum": true }, { "type": "string", "pattern": "^\\d+([.,]\\d{1,4})?$" } ] }, "unit": { "description": "Birim (adet, saat, ay…); varsayılan adet", "type": "string", "maxLength": 20 }, "unit_price": { "description": "Birim fiyat; `prices_include_vat` true ise KDV dahil", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "vat_rate": { "description": "KDV oranı; boşsa üründen, o da yoksa 20", "type": "string", "enum": [ "0", "1", "10", "20" ] }, "discount_rate": { "description": "Satır iskontosu (%)", "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "pattern": "^\\d{1,3}([.,]\\d{1,2})?$" } ] }, "vat_exemption_code": { "description": "KDV %0 ise zorunlu GİB istisna kodu: 351 istisna dışı diğer, 301 mal ihracatı, 302 hizmet ihracatı, 350 diğer istisnalar (tam liste GİB kod listesinde). e-Belgedeki istisna sebebi metni (UBL TaxExemptionReason) koddan otomatik yazılır, ayrıca gönderilmez.", "nullable": true, "type": "string", "maxLength": 10 }, "withholding_code": { "description": "KDV tevkifat kodu (ör. 601)", "nullable": true, "type": "string", "maxLength": 10 }, "price_includes_vat": { "description": "Bu kalemde fiyat KDV dahil mi (verilmezse faturadaki `prices_include_vat`)", "type": "boolean" } }, "required": [ "quantity", "unit_price" ] }, "description": "Fatura kalemleri (en az 1, en çok 500)" }, "issue": { "default": false, "description": "true ise fatura kesilir (numara ve ETTN verilir); false ise taslak kalır", "type": "boolean" }, "send": { "default": false, "description": "true ise kesilip e-Fatura/e-Arşiv olarak GİB'e gönderilir (issue'yu içerir, ebelge:write kapsamı ister, jeton düşer)", "type": "boolean" }, "payment": { "description": "Kesimle birlikte tahsilat (ör. ödenmiş WHMCS faturası)", "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Kasa/banka hesabı (GET /accounts)" }, "amount": { "description": "Boşsa kalan tutarın tamamı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "method": { "type": "string", "enum": [ "nakit", "havale", "kredi_karti", "cek", "senet", "pos" ], "description": "Ödeme yöntemi" } }, "required": [ "account_id" ] } }, "required": [ "lines" ], "example": { "type": "satis", "contact": { "name": "Ayşe Yılmaz", "first_name": "Ayşe", "last_name": "Yılmaz", "tax_number": "11111111111", "email": "ayse@example.com", "billing_address": { "line": "Atatürk Cad. No: 5", "district": "Çankaya", "city": "Ankara" } }, "series": "WHM", "order_no": "WHMCS-10452", "prices_include_vat": false, "lines": [ { "description": "Profesyonel hosting (06.11.2026 - 05.11.2027)", "quantity": "1", "unit_price": "1200.00", "vat_rate": "20" } ], "issue": true, "send": true, "payment": { "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "method": "kredi_karti" } } } } } }, "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura2" } } } }, "202": { "description": "Kabul edildi; onay bekliyor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura2" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postInvoices" } }, "/invoices/{id}": { "get": { "summary": "Fatura detayı", "tags": [ "Faturalar" ], "description": "Kalemler, toplamlar, son e-belge durumu ve paylaşılabilir PDF bağlantısı.\n\n**Kapsam:** `fatura:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getInvoicesById" } }, "/invoices/{id}/issue": { "post": { "summary": "Taslak faturayı kes", "tags": [ "Faturalar" ], "description": "Numara ve ETTN verilir; cari, stok ve muhasebe kayıtları yazılır. e-Belge gönderimi için ardından POST /invoices/{id}/send.\n\n**Kapsam:** `fatura:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Kasa/banka hesabı (GET /accounts)" }, "amount": { "description": "Boşsa kalan tutarın tamamı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "method": { "type": "string", "enum": [ "nakit", "havale", "kredi_karti", "cek", "senet", "pos" ], "description": "Ödeme yöntemi" } }, "required": [ "account_id" ], "description": "Tahsilat: verilirse fatura kesilirken bu hesaba tahsilat işlenir" } }, "example": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "202": { "description": "Kabul edildi; onay bekliyor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postInvoicesByIdIssue" } }, "/invoices/{id}/send": { "post": { "summary": "Faturayı e-Fatura / e-Arşiv olarak GİB'e gönder", "tags": [ "e-Fatura ve e-Arşiv" ], "description": "Kesilmiş satış faturası entegratör üzerinden gönderilir ve jeton düşer. Alıcı GİB’de kayıtlı e-Fatura mükellefiyse e-Fatura, değilse e-Arşiv olur. Durum değişiklikleri `invoice.status_changed` webhook’uyla bildirilir.\n\n**Kapsam:** `ebelge:write`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postInvoicesByIdSend" } }, "/invoices/{id}/e-document": { "get": { "summary": "e-Belge (GİB) durumu", "tags": [ "e-Fatura ve e-Arşiv" ], "description": "Faturanın son e-Fatura/e-Arşiv kaydı. CariErp gönderilen belgelerin durumunu 15 dakikada bir entegratörden sorgular; `refresh=true` ile hemen sorgulanır. Belge yoksa 404 EBELGE_YOK.\n\n**Kapsam:** `ebelge:read`", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "refresh", "required": false, "description": "true ise durum entegratörden yeniden sorgulanır" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "type": { "type": "string", "description": "efatura | earsiv" }, "status": { "type": "string", "description": "gonderiliyor | iletildi | kabul | red | iptal | hata" }, "status_label": { "type": "string", "description": "Durumun Türkçe açıklaması" }, "provider_status": { "type": "string", "description": "Entegratörün ham durumu" }, "number": { "nullable": true, "description": "GİB fatura numarası (16 hane)", "type": "string" }, "ettn": { "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "scenario": { "nullable": true, "description": "TEMELFATURA | TICARIFATURA | EARSIVFATURA …", "type": "string" }, "response_deadline": { "nullable": true, "description": "Ticari faturada alıcının kabul/red son günü", "type": "string" }, "message": { "nullable": true, "description": "Entegratör ya da GİB açıklaması (red gerekçesi, hata)", "type": "string" }, "sent_at": { "type": "string", "description": "GİB’e gönderilme zamanı" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "type", "status", "status_label", "provider_status", "number", "ettn", "scenario", "response_deadline", "message", "sent_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getInvoicesByIdEDocument" } }, "/invoices/{id}/pdf": { "get": { "summary": "Faturanın PDF dosyası", "tags": [ "Faturalar" ], "description": "Yanıt `application/pdf`. Oturumsuz paylaşmak için faturadaki `pdf_url` alanını kullanın.\n\n**Kapsam:** `fatura:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "PDF dosyası", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getInvoicesByIdPdf" } }, "/invoices/{id}/cancel": { "post": { "summary": "Faturayı iptal et", "tags": [ "Faturalar" ], "description": "Cari, stok ve muhasebe kayıtları ters kayıtla geri alınır; e-Arşiv faturası entegratörde de iptal edilir (GİB süresi içinde). Tahsilatı olan fatura iptal edilemez (422 ODEMELI_FATURA). e-Fatura alıcı tarafından reddedilmeli ya da iade faturası kesilmelidir.\n\n**Kapsam:** `fatura:delete`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 250, "description": "İptal gerekçesi (işlem kaydına ve e-Arşiv iptaline yazılır)" } }, "required": [ "reason" ], "example": { "reason": "Müşteri siparişi iptal etti" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "202": { "description": "Kabul edildi; onay bekliyor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fatura3" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postInvoicesByIdCancel" } }, "/invoices/{id}/payments": { "post": { "summary": "Faturaya tahsilat/ödeme ekle", "tags": [ "Tahsilat ve ödemeler" ], "description": "Satış faturasında tahsilat, alış faturasında ödeme olarak kaydedilir; kasa/banka hesabına hareket yazılır. Fatura tamamen ödenince `invoice.paid` webhook’u gider.\n\n**Kapsam:** `fatura:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Kasa/banka hesabı (GET /accounts)" }, "amount": { "description": "Boşsa kalan tutarın tamamı", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "method": { "type": "string", "enum": [ "nakit", "havale", "kredi_karti", "cek", "senet", "pos" ], "description": "Ödeme yöntemi" } }, "required": [ "account_id" ], "example": { "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "amount": "1440.00", "date": "2026-11-06", "method": "kredi_karti" } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tahsilat" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postInvoicesByIdPayments" } }, "/e-invoice-users/{tax_number}": { "get": { "summary": "VKN/TCKN e-Fatura mükellefi mi", "tags": [ "e-Fatura ve e-Arşiv" ], "description": "GİB kayıtlı kullanıcı listesinden sorgular. Kayıtlıysa fatura e-Fatura, değilse e-Arşiv olarak gönderilir.\n\n**Kapsam:** `ebelge:read`", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{10,11}$" }, "in": "path", "name": "tax_number", "required": true, "description": "VKN (10 hane) ya da TCKN (11 hane)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_number": { "type": "string", "description": "VKN (10 hane) ya da TCKN (11 hane)" }, "e_invoice_user": { "type": "boolean", "description": "GİB e-Fatura kayıtlı kullanıcısı mı" }, "title": { "nullable": true, "type": "string", "description": "GİB’deki ünvan" }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Posta kutusu etiketleri" } }, "required": [ "tax_number", "e_invoice_user", "title", "aliases" ], "additionalProperties": false, "example": { "tax_number": "1234567890", "e_invoice_user": true, "title": "ÖRNEK BİLİŞİM LİMİTED ŞİRKETİ", "aliases": [ "urn:mail:defaultpk@ornekbilisim.com.tr" ] } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getEInvoiceUsersByTaxNumber" } }, "/me": { "get": { "summary": "Anahtarın bağlı olduğu şirket", "tags": [ "Hesap" ], "description": "Bağlantı denemesi için kullanın: şirket, anahtarın kapsamları, istek sınırı ve jeton bakiyesi. Herhangi bir okuma kapsamı yeterlidir.\n\n**Kapsam:** `cari:read`", "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "tax_number": { "nullable": true, "type": "string", "description": "VKN (10 hane) ya da TCKN (11 hane)" }, "e_document_enabled": { "type": "boolean", "description": "e-Belge (e-Fatura/e-Arşiv) aktif mi" } }, "required": [ "id", "name", "tax_number", "e_document_enabled" ], "additionalProperties": false, "description": "Şirket" }, "credential": { "type": "object", "properties": { "type": { "type": "string", "description": "api_anahtari | oauth" }, "name": { "nullable": true, "type": "string", "description": "Ad ya da ünvan" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Kapsamlar (modul:eylem)" } }, "required": [ "type", "name", "scopes" ], "additionalProperties": false, "description": "Kullanılan kimlik" }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Dakikada istek" } }, "required": [ "per_minute" ], "additionalProperties": false, "description": "İstek sınırı" }, "tokens": { "type": "object", "properties": { "balance": { "type": "string", "description": "e-Belge jeton bakiyesi" } }, "required": [ "balance" ], "additionalProperties": false, "description": "e-Belge jetonu" } }, "required": [ "company", "credential", "rate_limit", "tokens" ], "additionalProperties": false, "example": { "company": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "name": "Örnek Hosting A.Ş.", "tax_number": "1234567890", "e_document_enabled": true }, "credential": { "type": "api_anahtari", "name": "WHMCS", "scopes": [ "cari:write", "fatura:write", "ebelge:write", "kasa:write" ] }, "rate_limit": { "per_minute": 120 }, "tokens": { "balance": "482" } } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getMe" } }, "/accounts": { "get": { "summary": "Kasa ve banka hesapları", "tags": [ "Kasa ve banka" ], "description": "Bakiyeler hesabın para birimindedir. Tahsilat girerken `account_id` buradan alınır.\n\n**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "type": "string", "enum": [ "kasa", "banka", "kredi_karti", "pos" ] }, "in": "query", "name": "type", "required": false, "description": "Tür" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "is_active", "required": false, "description": "Etkin mi; false ise arşivlenmiş" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HesapListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getAccounts" } }, "/accounts/{id}": { "get": { "summary": "Hesap detayı ve bakiyesi", "tags": [ "Kasa ve banka" ], "description": "**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hesap" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getAccountsById" } }, "/transactions": { "get": { "summary": "Kasa ve banka hareketleri", "tags": [ "Kasa ve banka" ], "description": "Tüm hesapların hareketleri; en yeni önce. İptal edilen kayıtlar ters hareketle (`reversal_of_id`) görünür.\n\n**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "account_id", "required": false, "description": "Kasa/banka hesabı kimliği (GET /accounts)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "contact_id", "required": false, "description": "Cari kimliği" }, { "schema": { "type": "string", "enum": [ "giris", "cikis" ] }, "in": "query", "name": "direction", "required": false, "description": "Yön: giris (para girişi) | cikis (para çıkışı)" }, { "schema": { "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Virgülle çoklu: tahsilat,tediye" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "Başlangıç tarihi (YYYY-AA-GG, dahil)" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false, "description": "Bitiş tarihi (YYYY-AA-GG, dahil)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HareketListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getTransactions" } }, "/accounts/{id}/transactions": { "get": { "summary": "Hesabın hareketleri", "tags": [ "Kasa ve banka" ], "description": "**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "contact_id", "required": false, "description": "Cari kimliği" }, { "schema": { "type": "string", "enum": [ "giris", "cikis" ] }, "in": "query", "name": "direction", "required": false, "description": "Yön: giris (para girişi) | cikis (para çıkışı)" }, { "schema": { "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Virgülle çoklu: tahsilat,tediye" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "Başlangıç tarihi (YYYY-AA-GG, dahil)" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false, "description": "Bitiş tarihi (YYYY-AA-GG, dahil)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HareketListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getAccountsByIdTransactions" } }, "/payments": { "get": { "summary": "Tahsilat ve ödemeleri listele", "tags": [ "Tahsilat ve ödemeler" ], "description": "Fatura tahsilatları/ödemeleri ve faturasız cari tahsilat/ödemeleri. İptal edilenler `status: iptal`.\n\n**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "in": "query", "name": "page", "required": false, "description": "Sayfa (1’den başlar)" }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "per_page", "required": false, "description": "Sayfa başına kayıt (en çok 100)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "account_id", "required": false, "description": "Kasa/banka hesabı kimliği (GET /accounts)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "contact_id", "required": false, "description": "Cari kimliği" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "Başlangıç tarihi (YYYY-AA-GG, dahil)" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false, "description": "Bitiş tarihi (YYYY-AA-GG, dahil)" }, { "schema": { "type": "string", "enum": [ "tahsilat", "odeme" ] }, "in": "query", "name": "type", "required": false, "description": "Tür" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "invoice_id", "required": false, "description": "Fatura kimliği" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TahsilatListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getPayments" }, "post": { "summary": "Faturasız cari tahsilatı/ödemesi", "tags": [ "Tahsilat ve ödemeler" ], "description": "Carinin bakiyesine işler (ön ödeme, hesaba ödeme). Belirli bir faturaya tahsilat için POST /invoices/{id}/payments kullanın.\n\n**Kapsam:** `kasa:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tahsilat", "odeme" ], "description": "tahsilat: cariden para girişi, odeme: cariye para çıkışı" }, "contact_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Cari kimliği" }, "account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Kasa/banka hesabı" }, "amount": { "description": "Tutar: iki ondalıklı metin ya da sayı (ör. \"1250.50\")", "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+([.,]\\d{1,2})?$" } ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "description": { "type": "string", "maxLength": 250, "description": "Açıklama" } }, "required": [ "type", "contact_id", "account_id", "amount" ], "example": { "type": "tahsilat", "contact_id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "amount": "500.00", "description": "Ön ödeme" } } } } }, "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tahsilat" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postPayments" } }, "/payments/{id}": { "get": { "summary": "Tahsilat/ödeme detayı", "tags": [ "Tahsilat ve ödemeler" ], "description": "**Kapsam:** `kasa:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tahsilat" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getPaymentsById" }, "delete": { "summary": "Tahsilatı/ödemeyi iptal et", "tags": [ "Tahsilat ve ödemeler" ], "description": "Ters kayıtla iptal edilir (silinmez); faturanın ödenen tutarı geri alınır.\n\n**Kapsam:** `kasa:delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tahsilat" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "deletePaymentsById" } }, "/webhook-events": { "get": { "summary": "Abone olunabilen olaylar", "tags": [ "Webhook" ], "description": "**Kapsam:** `api_anahtari:read`", "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Olay adı" }, "label": { "type": "string", "description": "Açıklama" }, "available": { "type": "boolean", "description": "Şu anda gönderiliyor mu" } }, "required": [ "key", "label", "available" ], "additionalProperties": false }, "description": "Kayıtlar" } }, "required": [ "data" ], "additionalProperties": false, "example": { "data": [ { "key": "invoice.status_changed", "label": "Faturanın GİB durumu değişti", "available": true } ] } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getWebhookEvents" } }, "/webhooks": { "get": { "summary": "Webhook uç noktaları", "tags": [ "Webhook" ], "description": "**Kapsam:** `api_anahtari:read`", "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListesi" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getWebhooks" }, "post": { "summary": "Webhook uç noktası ekle", "tags": [ "Webhook" ], "description": "Firma başına en çok 10 uç nokta. Bütün uçlar aynı imza anahtarıyla imzalanır.\n\n**Kapsam:** `api_anahtari:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Olayların POST edileceği https adresi" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.sent", "invoice.status_changed", "invoice.paid", "invoice.cancelled", "payment.received", "contact.updated", "order.created", "stock.low", "shipment.created", "shipment.delivered" ] }, "description": "Olaylar: invoice.created, invoice.sent, invoice.status_changed, invoice.paid, invoice.cancelled, payment.received, contact.updated, order.created, stock.low, shipment.created, shipment.delivered" }, "active": { "type": "boolean", "description": "Etkin mi; false ise olay gönderilmez" }, "description": { "nullable": true, "type": "string", "maxLength": 120, "description": "Açıklama" } }, "required": [ "url", "events" ], "example": { "url": "https://muhasebe.ornekhosting.com/modules/addons/carierp/webhook.php", "events": [ "invoice.status_changed", "invoice.paid" ], "description": "WHMCS" } } } } }, "security": [ { "apiAnahtari": [] } ], "responses": { "201": { "description": "Oluşturuldu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook2" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postWebhooks" } }, "/webhooks/{id}": { "get": { "summary": "Webhook uç noktası", "tags": [ "Webhook" ], "description": "**Kapsam:** `api_anahtari:read`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "getWebhooksById" }, "patch": { "summary": "Webhook uç noktasını güncelle", "tags": [ "Webhook" ], "description": "**Kapsam:** `api_anahtari:write`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Olayların POST edileceği https adresi" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.sent", "invoice.status_changed", "invoice.paid", "invoice.cancelled", "payment.received", "contact.updated", "order.created", "stock.low", "shipment.created", "shipment.delivered" ] }, "description": "Olaylar: invoice.created, invoice.sent, invoice.status_changed, invoice.paid, invoice.cancelled, payment.received, contact.updated, order.created, stock.low, shipment.created, shipment.delivered" }, "active": { "type": "boolean", "description": "Etkin mi; false ise olay gönderilmez" }, "description": { "nullable": true, "type": "string", "maxLength": 120, "description": "Açıklama" } }, "example": { "events": [ "invoice.status_changed", "invoice.paid", "payment.received" ], "active": true } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "patchWebhooksById" }, "delete": { "summary": "Webhook uç noktasını sil", "tags": [ "Webhook" ], "description": "**Kapsam:** `api_anahtari:delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "deleted": { "type": "boolean", "description": "Silindi mi" } }, "required": [ "id", "deleted" ], "additionalProperties": false, "example": { "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "deleted": true } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "deleteWebhooksById" } }, "/webhooks/{id}/test": { "post": { "summary": "Deneme olayı gönder (ping)", "tags": [ "Webhook" ], "description": "Uca imzalı `ping` olayı gönderir ve sonucu döner.\n\n**Kapsam:** `api_anahtari:write`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [ { "apiAnahtari": [] } ], "responses": { "200": { "description": "Başarılı", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Başarılı mı (2xx)" }, "status": { "nullable": true, "type": "number", "description": "Durum" }, "ms": { "nullable": true, "type": "number", "description": "Yanıt süresi (milisaniye)" }, "error": { "nullable": true, "type": "string", "description": "Hata açıklaması" } }, "required": [ "ok", "status", "ms", "error" ], "additionalProperties": false, "example": { "ok": true, "status": 200, "ms": 184, "error": null } } } } }, "400": { "$ref": "#/components/responses/Hata400" }, "401": { "$ref": "#/components/responses/Hata401" }, "403": { "$ref": "#/components/responses/Hata403" }, "404": { "$ref": "#/components/responses/Hata404" }, "409": { "$ref": "#/components/responses/Hata409" }, "422": { "$ref": "#/components/responses/Hata422" }, "429": { "$ref": "#/components/responses/Hata429" } }, "operationId": "postWebhooksByIdTest" } }, "/public/invoices/{id}/pdf": { "get": { "summary": "Paylaşılabilir PDF (oturumsuz)", "tags": [ "Faturalar" ], "description": "Faturadaki `pdf_url` alanının adresi. İmza (`s`) fatura kimliğine bağlıdır; yanlış imzada 404.", "parameters": [ { "schema": { "type": "string", "minLength": 16, "maxLength": 64 }, "in": "query", "name": "s", "required": true, "description": "Bağlantı imzası (faturadaki pdf_url içinde gelir)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "Kaydın kimliği (UUID)" } ], "security": [], "responses": { "200": { "description": "PDF dosyası", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/Hata404" } }, "operationId": "getPublicInvoicesByIdPdf" } } }, "components": { "securitySchemes": { "apiAnahtari": { "type": "http", "scheme": "bearer", "bearerFormat": "dfk_…", "description": "Panelde üretilen API anahtarı. X-Api-Key başlığıyla da gönderilebilir." } }, "schemas": { "Cari": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "contact" ], "description": "Nesne türü" }, "role": { "type": "string", "description": "musteri | tedarikci | her_ikisi" }, "kind": { "type": "string", "description": "kurumsal | bireysel" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "first_name": { "nullable": true, "type": "string", "description": "Ad (bireysel)" }, "last_name": { "nullable": true, "type": "string", "description": "Soyad (bireysel)" }, "code": { "nullable": true, "type": "string", "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "tax_number": { "nullable": true, "description": "VKN (10) ya da TCKN (11)", "type": "string" }, "tax_office": { "nullable": true, "type": "string", "description": "Vergi dairesi" }, "email": { "nullable": true, "type": "string", "description": "E-posta adresi; e-Arşiv fatura bu adrese de gönderilir" }, "phone": { "nullable": true, "type": "string", "description": "Telefon (ör. +902161234567)" }, "mobile": { "nullable": true, "type": "string", "description": "Cep telefonu" }, "website": { "nullable": true, "type": "string", "description": "Web sitesi" }, "e_document_type": { "type": "string", "description": "belirlenmedi | efatura | earsiv — faturada kullanılacak belge; ilk faturada GİB listesinden belirlenir" }, "e_invoice_alias": { "nullable": true, "description": "e-Fatura mükellefinin GİB posta kutusu etiketi", "type": "string" }, "currency": { "type": "string", "description": "Para birimi" }, "iban": { "nullable": true, "type": "string", "description": "IBAN (TR ile başlayan, doğrulanır)" }, "billing_address": { "nullable": true, "type": "object", "properties": { "line": { "description": "Açık adres", "nullable": true, "type": "string" }, "district": { "description": "İlçe", "nullable": true, "type": "string" }, "city": { "description": "İl", "nullable": true, "type": "string" }, "postal_code": { "nullable": true, "type": "string", "description": "Posta kodu" }, "country": { "description": "Ülke (varsayılan Türkiye)", "nullable": true, "type": "string" } }, "additionalProperties": false, "description": "Fatura adresi" }, "balance": { "type": "string", "description": "Bakiye (TL): pozitif = cari size borçlu" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "object", "role", "kind", "name", "first_name", "last_name", "code", "tax_number", "tax_office", "email", "phone", "mobile", "website", "e_document_type", "e_invoice_alias", "currency", "iban", "billing_address", "balance", "is_active", "created_at", "updated_at" ], "additionalProperties": false, "example": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "contact", "role": "musteri", "kind": "kurumsal", "name": "Örnek Bilişim Ltd. Şti.", "first_name": null, "last_name": null, "code": "M-0042", "tax_number": "1234567890", "tax_office": "Kadıköy", "email": "muhasebe@ornekbilisim.com.tr", "phone": "+902161234567", "mobile": null, "website": null, "e_document_type": "efatura", "e_invoice_alias": "urn:mail:defaultpk@ornekbilisim.com.tr", "currency": "TRY", "iban": null, "billing_address": { "line": "Caferağa Mah. Moda Cad. No: 10", "district": "Kadıköy", "city": "İstanbul", "postal_code": "34710", "country": "Türkiye" }, "balance": "1440.00", "is_active": true, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } }, "CariListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cari" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "contact", "role": "musteri", "kind": "kurumsal", "name": "Örnek Bilişim Ltd. Şti.", "first_name": null, "last_name": null, "code": "M-0042", "tax_number": "1234567890", "tax_office": "Kadıköy", "email": "muhasebe@ornekbilisim.com.tr", "phone": "+902161234567", "mobile": null, "website": null, "e_document_type": "efatura", "e_invoice_alias": "urn:mail:defaultpk@ornekbilisim.com.tr", "currency": "TRY", "iban": null, "billing_address": { "line": "Caferağa Mah. Moda Cad. No: 10", "district": "Kadıköy", "city": "İstanbul", "postal_code": "34710", "country": "Türkiye" }, "balance": "1440.00", "is_active": true, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Hata": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Makinece okunur hata kodu (ör. DOGRULAMA_HATASI, BULUNAMADI, KAPSAM_YOK)" }, "message": { "type": "string", "description": "Türkçe, kullanıcıya gösterilebilir açıklama" }, "details": { "description": "Alan hataları ya da ek bilgi" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Hata açıklaması" } }, "required": [ "error" ], "additionalProperties": false, "example": { "error": { "code": "DOGRULAMA_HATASI", "message": "İstek doğrulanamadı. Alanları kontrol edin.", "details": [ { "path": "lines.0.quantity", "message": "Required" } ] } } }, "Urun": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "product" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "urun | hizmet" }, "code": { "nullable": true, "description": "Stok kodu (şirkette benzersiz)", "type": "string" }, "barcode": { "nullable": true, "type": "string", "description": "Barkod (EAN/GTIN)" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "description": { "nullable": true, "type": "string", "description": "Açıklama" }, "unit": { "type": "string", "description": "Birim: adet, kg, lt, m, saat, ay, yil…" }, "sale_price": { "type": "string", "description": "KDV hariç satış fiyatı" }, "purchase_price": { "type": "string", "description": "KDV hariç alış fiyatı" }, "currency": { "type": "string", "description": "Para birimi" }, "vat_rate": { "type": "string", "description": "KDV oranı (%)" }, "track_stock": { "type": "boolean", "description": "Stok takibi yapılsın mı (hizmette false)" }, "stock_quantity": { "nullable": true, "description": "Tüm depolardaki toplam stok (stok takipli değilse null)", "type": "string" }, "critical_level": { "nullable": true, "type": "string", "description": "Kritik stok seviyesi (bu miktara inince uyarı)" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "object", "type", "code", "barcode", "name", "description", "unit", "sale_price", "purchase_price", "currency", "vat_rate", "track_stock", "stock_quantity", "critical_level", "is_active", "created_at", "updated_at" ], "additionalProperties": false, "example": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "object": "product", "type": "hizmet", "code": "HOST-PRO", "barcode": null, "name": "Profesyonel hosting (yıllık)", "description": null, "unit": "adet", "sale_price": "1200.00", "purchase_price": "0.00", "currency": "TRY", "vat_rate": "20", "track_stock": false, "stock_quantity": null, "critical_level": null, "is_active": true, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } }, "UrunListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Urun" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "object": "product", "type": "hizmet", "code": "HOST-PRO", "barcode": null, "name": "Profesyonel hosting (yıllık)", "description": null, "unit": "adet", "sale_price": "1200.00", "purchase_price": "0.00", "currency": "TRY", "vat_rate": "20", "track_stock": false, "stock_quantity": null, "critical_level": null, "is_active": true, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Fatura": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "invoice" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "satis | toptan | perakende | gelir | alis | gider | satis_iade | alis_iade" }, "status": { "type": "string", "description": "taslak | onay_bekliyor | kesildi | gonderildi | kismi_odendi | odendi | vadesi_gecti | iptal" }, "number": { "nullable": true, "description": "Fatura numarası (kesilince verilir; e-Belgede GİB numarası)", "type": "string" }, "series": { "nullable": true, "type": "string", "description": "Fatura serisi (3 karakter)" }, "issue_date": { "type": "string", "description": "Fatura tarihi" }, "issue_time": { "nullable": true, "type": "string", "description": "Fatura saati" }, "due_date": { "nullable": true, "type": "string", "description": "Vade tarihi (YYYY-AA-GG)" }, "currency": { "type": "string", "description": "Para birimi" }, "exchange_rate": { "type": "string", "description": "Döviz kuru (TL karşılığı)" }, "contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "tax_number": { "nullable": true, "type": "string", "description": "VKN (10 hane) ya da TCKN (11 hane)" } }, "required": [ "id", "name", "tax_number" ], "additionalProperties": false, "description": "Cari" }, "order_no": { "nullable": true, "type": "string", "description": "Sipariş ya da dış sistem numarası" }, "notes": { "nullable": true, "type": "string", "description": "Not" }, "e_document_type": { "nullable": true, "description": "efatura | earsiv | kagit (kesilince belirlenir)", "type": "string" }, "scenario": { "nullable": true, "type": "string", "description": "GİB senaryosu" }, "ettn": { "nullable": true, "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string", "description": "İskonto öncesi KDV hariç toplam" }, "discount": { "type": "string", "description": "İskonto toplamı" }, "net": { "type": "string", "description": "KDV hariç net toplam" }, "vat": { "type": "string", "description": "KDV toplamı" }, "withholding": { "type": "string", "description": "KDV tevkifatı toplamı" }, "total": { "type": "string", "description": "KDV dahil genel toplam" }, "payable": { "type": "string", "description": "Ödenecek tutar (tevkifat düşülmüş)" }, "paid": { "type": "string", "description": "Tahsil edilen ya da ödenen" }, "remaining": { "type": "string", "description": "Kalan" } }, "required": [ "subtotal", "discount", "net", "vat", "withholding", "total", "payable", "paid", "remaining" ], "additionalProperties": false, "description": "Toplamlar (fatura para biriminde)" }, "lines": { "description": "Listede yer almaz; detayda gelir", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "line_no": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Satır no" }, "product_id": { "nullable": true, "type": "string", "description": "Ürün/hizmet kartı kimliği" }, "description": { "type": "string", "description": "Açıklama" }, "quantity": { "type": "string", "description": "Miktar" }, "unit": { "type": "string", "description": "Birim" }, "unit_price": { "type": "string", "description": "KDV hariç birim fiyat" }, "discount_amount": { "type": "string", "description": "İskonto tutarı" }, "net_amount": { "type": "string", "description": "İskonto sonrası KDV hariç tutar" }, "vat_rate": { "type": "string", "description": "KDV oranı (%)" }, "vat_amount": { "type": "string", "description": "KDV tutarı" }, "vat_exemption_code": { "nullable": true, "description": "KDV istisna kodu (ör. 351); istisna sebebi metni e-Belgeye koddan yazılır", "type": "string" }, "withholding_code": { "nullable": true, "description": "Tevkifat kodu", "type": "string" }, "withholding_amount": { "type": "string", "description": "Tevkifat tutarı" }, "total": { "type": "string", "description": "Toplam" } }, "required": [ "id", "line_no", "product_id", "description", "quantity", "unit", "unit_price", "discount_amount", "net_amount", "vat_rate", "vat_amount", "vat_exemption_code", "withholding_code", "withholding_amount", "total" ], "additionalProperties": false } }, "e_document": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "type": { "type": "string", "description": "efatura | earsiv" }, "status": { "type": "string", "description": "gonderiliyor | iletildi | kabul | red | iptal | hata" }, "status_label": { "type": "string", "description": "Durumun Türkçe açıklaması" }, "provider_status": { "type": "string", "description": "Entegratörün ham durumu" }, "number": { "nullable": true, "description": "GİB fatura numarası (16 hane)", "type": "string" }, "ettn": { "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "scenario": { "nullable": true, "description": "TEMELFATURA | TICARIFATURA | EARSIVFATURA …", "type": "string" }, "response_deadline": { "nullable": true, "description": "Ticari faturada alıcının kabul/red son günü", "type": "string" }, "message": { "nullable": true, "description": "Entegratör ya da GİB açıklaması (red gerekçesi, hata)", "type": "string" }, "sent_at": { "type": "string", "description": "GİB’e gönderilme zamanı" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "type", "status", "status_label", "provider_status", "number", "ettn", "scenario", "response_deadline", "message", "sent_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "description": "Son e-Belge (GİB) kaydı; gönderilmediyse null" }, "pdf_url": { "nullable": true, "description": "Oturum gerektirmeyen, paylaşılabilir PDF bağlantısı (kesilmiş faturada)", "type": "string" }, "issued_at": { "nullable": true, "type": "string", "description": "Kesilme zamanı" }, "sent_at": { "nullable": true, "type": "string", "description": "GİB’e gönderilme zamanı" }, "cancelled_at": { "nullable": true, "type": "string", "description": "İptal zamanı" }, "cancel_reason": { "nullable": true, "type": "string", "description": "İptal gerekçesi" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "object", "type", "status", "number", "series", "issue_date", "issue_time", "due_date", "currency", "exchange_rate", "contact", "order_no", "notes", "e_document_type", "scenario", "ettn", "totals", "e_document", "pdf_url", "issued_at", "sent_at", "cancelled_at", "cancel_reason", "created_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "invoice", "type": "satis", "status": "odendi", "number": "WHM2026000000123", "series": "WHM", "issue_date": "2026-11-06", "issue_time": "12:30:00", "due_date": "2026-11-06", "currency": "TRY", "exchange_rate": "1", "contact": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890" }, "order_no": "WHMCS-10452", "notes": null, "e_document_type": "earsiv", "scenario": "EARSIVFATURA", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "totals": { "subtotal": "1200.00", "discount": "0.00", "net": "1200.00", "vat": "240.00", "withholding": "0.00", "total": "1440.00", "payable": "1440.00", "paid": "1440.00", "remaining": "0.00" }, "e_document": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "pdf_url": "https://app.carierp.com/api/open/v1/public/invoices/3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01/pdf?s=Qm9yYy1hbGFjYWstaGVwLWd1bmNlbA", "issued_at": "2026-11-06T09:30:00.000Z", "sent_at": "2026-11-06T09:30:00.000Z", "cancelled_at": null, "cancel_reason": null, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } }, "FaturaListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fatura" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "invoice", "type": "satis", "status": "odendi", "number": "WHM2026000000123", "series": "WHM", "issue_date": "2026-11-06", "issue_time": "12:30:00", "due_date": "2026-11-06", "currency": "TRY", "exchange_rate": "1", "contact": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890" }, "order_no": "WHMCS-10452", "notes": null, "e_document_type": "earsiv", "scenario": "EARSIVFATURA", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "totals": { "subtotal": "1200.00", "discount": "0.00", "net": "1200.00", "vat": "240.00", "withholding": "0.00", "total": "1440.00", "payable": "1440.00", "paid": "1440.00", "remaining": "0.00" }, "e_document": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "pdf_url": "https://app.carierp.com/api/open/v1/public/invoices/3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01/pdf?s=Qm9yYy1hbGFjYWstaGVwLWd1bmNlbA", "issued_at": "2026-11-06T09:30:00.000Z", "sent_at": "2026-11-06T09:30:00.000Z", "cancelled_at": null, "cancel_reason": null, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Fatura2": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "invoice" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "satis | toptan | perakende | gelir | alis | gider | satis_iade | alis_iade" }, "status": { "type": "string", "description": "taslak | onay_bekliyor | kesildi | gonderildi | kismi_odendi | odendi | vadesi_gecti | iptal" }, "number": { "nullable": true, "description": "Fatura numarası (kesilince verilir; e-Belgede GİB numarası)", "type": "string" }, "series": { "nullable": true, "type": "string", "description": "Fatura serisi (3 karakter)" }, "issue_date": { "type": "string", "description": "Fatura tarihi" }, "issue_time": { "nullable": true, "type": "string", "description": "Fatura saati" }, "due_date": { "nullable": true, "type": "string", "description": "Vade tarihi (YYYY-AA-GG)" }, "currency": { "type": "string", "description": "Para birimi" }, "exchange_rate": { "type": "string", "description": "Döviz kuru (TL karşılığı)" }, "contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "tax_number": { "nullable": true, "type": "string", "description": "VKN (10 hane) ya da TCKN (11 hane)" } }, "required": [ "id", "name", "tax_number" ], "additionalProperties": false, "description": "Cari" }, "order_no": { "nullable": true, "type": "string", "description": "Sipariş ya da dış sistem numarası" }, "notes": { "nullable": true, "type": "string", "description": "Not" }, "e_document_type": { "nullable": true, "description": "efatura | earsiv | kagit (kesilince belirlenir)", "type": "string" }, "scenario": { "nullable": true, "type": "string", "description": "GİB senaryosu" }, "ettn": { "nullable": true, "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string", "description": "İskonto öncesi KDV hariç toplam" }, "discount": { "type": "string", "description": "İskonto toplamı" }, "net": { "type": "string", "description": "KDV hariç net toplam" }, "vat": { "type": "string", "description": "KDV toplamı" }, "withholding": { "type": "string", "description": "KDV tevkifatı toplamı" }, "total": { "type": "string", "description": "KDV dahil genel toplam" }, "payable": { "type": "string", "description": "Ödenecek tutar (tevkifat düşülmüş)" }, "paid": { "type": "string", "description": "Tahsil edilen ya da ödenen" }, "remaining": { "type": "string", "description": "Kalan" } }, "required": [ "subtotal", "discount", "net", "vat", "withholding", "total", "payable", "paid", "remaining" ], "additionalProperties": false, "description": "Toplamlar (fatura para biriminde)" }, "lines": { "description": "Listede yer almaz; detayda gelir", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "line_no": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Satır no" }, "product_id": { "nullable": true, "type": "string", "description": "Ürün/hizmet kartı kimliği" }, "description": { "type": "string", "description": "Açıklama" }, "quantity": { "type": "string", "description": "Miktar" }, "unit": { "type": "string", "description": "Birim" }, "unit_price": { "type": "string", "description": "KDV hariç birim fiyat" }, "discount_amount": { "type": "string", "description": "İskonto tutarı" }, "net_amount": { "type": "string", "description": "İskonto sonrası KDV hariç tutar" }, "vat_rate": { "type": "string", "description": "KDV oranı (%)" }, "vat_amount": { "type": "string", "description": "KDV tutarı" }, "vat_exemption_code": { "nullable": true, "description": "KDV istisna kodu (ör. 351); istisna sebebi metni e-Belgeye koddan yazılır", "type": "string" }, "withholding_code": { "nullable": true, "description": "Tevkifat kodu", "type": "string" }, "withholding_amount": { "type": "string", "description": "Tevkifat tutarı" }, "total": { "type": "string", "description": "Toplam" } }, "required": [ "id", "line_no", "product_id", "description", "quantity", "unit", "unit_price", "discount_amount", "net_amount", "vat_rate", "vat_amount", "vat_exemption_code", "withholding_code", "withholding_amount", "total" ], "additionalProperties": false } }, "e_document": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "type": { "type": "string", "description": "efatura | earsiv" }, "status": { "type": "string", "description": "gonderiliyor | iletildi | kabul | red | iptal | hata" }, "status_label": { "type": "string", "description": "Durumun Türkçe açıklaması" }, "provider_status": { "type": "string", "description": "Entegratörün ham durumu" }, "number": { "nullable": true, "description": "GİB fatura numarası (16 hane)", "type": "string" }, "ettn": { "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "scenario": { "nullable": true, "description": "TEMELFATURA | TICARIFATURA | EARSIVFATURA …", "type": "string" }, "response_deadline": { "nullable": true, "description": "Ticari faturada alıcının kabul/red son günü", "type": "string" }, "message": { "nullable": true, "description": "Entegratör ya da GİB açıklaması (red gerekçesi, hata)", "type": "string" }, "sent_at": { "type": "string", "description": "GİB’e gönderilme zamanı" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "type", "status", "status_label", "provider_status", "number", "ettn", "scenario", "response_deadline", "message", "sent_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "description": "Son e-Belge (GİB) kaydı; gönderilmediyse null" }, "pdf_url": { "nullable": true, "description": "Oturum gerektirmeyen, paylaşılabilir PDF bağlantısı (kesilmiş faturada)", "type": "string" }, "issued_at": { "nullable": true, "type": "string", "description": "Kesilme zamanı" }, "sent_at": { "nullable": true, "type": "string", "description": "GİB’e gönderilme zamanı" }, "cancelled_at": { "nullable": true, "type": "string", "description": "İptal zamanı" }, "cancel_reason": { "nullable": true, "type": "string", "description": "İptal gerekçesi" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" }, "send_error": { "nullable": true, "description": "`send: true` istendi ama gönderilemediyse nedeni (fatura kesilmiş kalır; POST /invoices/{id}/send ile yeniden denenir)", "type": "object", "properties": { "code": { "type": "string", "description": "Kod (cari kodu ya da stok kodu); şirkette benzersiz" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "id", "object", "type", "status", "number", "series", "issue_date", "issue_time", "due_date", "currency", "exchange_rate", "contact", "order_no", "notes", "e_document_type", "scenario", "ettn", "totals", "e_document", "pdf_url", "issued_at", "sent_at", "cancelled_at", "cancel_reason", "created_at", "updated_at", "send_error" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "invoice", "type": "satis", "status": "odendi", "number": "WHM2026000000123", "series": "WHM", "issue_date": "2026-11-06", "issue_time": "12:30:00", "due_date": "2026-11-06", "currency": "TRY", "exchange_rate": "1", "contact": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890" }, "order_no": "WHMCS-10452", "notes": null, "e_document_type": "earsiv", "scenario": "EARSIVFATURA", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "totals": { "subtotal": "1200.00", "discount": "0.00", "net": "1200.00", "vat": "240.00", "withholding": "0.00", "total": "1440.00", "payable": "1440.00", "paid": "1440.00", "remaining": "0.00" }, "lines": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "line_no": 1, "product_id": null, "description": "Profesyonel hosting (06.11.2026 - 05.11.2027)", "quantity": "1", "unit": "adet", "unit_price": "1200.00", "discount_amount": "0.00", "net_amount": "1200.00", "vat_rate": "20", "vat_amount": "240.00", "vat_exemption_code": null, "withholding_code": null, "withholding_amount": "0.00", "total": "1440.00" } ], "e_document": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "pdf_url": "https://app.carierp.com/api/open/v1/public/invoices/3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01/pdf?s=Qm9yYy1hbGFjYWstaGVwLWd1bmNlbA", "issued_at": "2026-11-06T09:30:00.000Z", "sent_at": "2026-11-06T09:30:00.000Z", "cancelled_at": null, "cancel_reason": null, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z", "send_error": null } }, "Fatura3": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "invoice" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "satis | toptan | perakende | gelir | alis | gider | satis_iade | alis_iade" }, "status": { "type": "string", "description": "taslak | onay_bekliyor | kesildi | gonderildi | kismi_odendi | odendi | vadesi_gecti | iptal" }, "number": { "nullable": true, "description": "Fatura numarası (kesilince verilir; e-Belgede GİB numarası)", "type": "string" }, "series": { "nullable": true, "type": "string", "description": "Fatura serisi (3 karakter)" }, "issue_date": { "type": "string", "description": "Fatura tarihi" }, "issue_time": { "nullable": true, "type": "string", "description": "Fatura saati" }, "due_date": { "nullable": true, "type": "string", "description": "Vade tarihi (YYYY-AA-GG)" }, "currency": { "type": "string", "description": "Para birimi" }, "exchange_rate": { "type": "string", "description": "Döviz kuru (TL karşılığı)" }, "contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "tax_number": { "nullable": true, "type": "string", "description": "VKN (10 hane) ya da TCKN (11 hane)" } }, "required": [ "id", "name", "tax_number" ], "additionalProperties": false, "description": "Cari" }, "order_no": { "nullable": true, "type": "string", "description": "Sipariş ya da dış sistem numarası" }, "notes": { "nullable": true, "type": "string", "description": "Not" }, "e_document_type": { "nullable": true, "description": "efatura | earsiv | kagit (kesilince belirlenir)", "type": "string" }, "scenario": { "nullable": true, "type": "string", "description": "GİB senaryosu" }, "ettn": { "nullable": true, "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string", "description": "İskonto öncesi KDV hariç toplam" }, "discount": { "type": "string", "description": "İskonto toplamı" }, "net": { "type": "string", "description": "KDV hariç net toplam" }, "vat": { "type": "string", "description": "KDV toplamı" }, "withholding": { "type": "string", "description": "KDV tevkifatı toplamı" }, "total": { "type": "string", "description": "KDV dahil genel toplam" }, "payable": { "type": "string", "description": "Ödenecek tutar (tevkifat düşülmüş)" }, "paid": { "type": "string", "description": "Tahsil edilen ya da ödenen" }, "remaining": { "type": "string", "description": "Kalan" } }, "required": [ "subtotal", "discount", "net", "vat", "withholding", "total", "payable", "paid", "remaining" ], "additionalProperties": false, "description": "Toplamlar (fatura para biriminde)" }, "lines": { "description": "Listede yer almaz; detayda gelir", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "line_no": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Satır no" }, "product_id": { "nullable": true, "type": "string", "description": "Ürün/hizmet kartı kimliği" }, "description": { "type": "string", "description": "Açıklama" }, "quantity": { "type": "string", "description": "Miktar" }, "unit": { "type": "string", "description": "Birim" }, "unit_price": { "type": "string", "description": "KDV hariç birim fiyat" }, "discount_amount": { "type": "string", "description": "İskonto tutarı" }, "net_amount": { "type": "string", "description": "İskonto sonrası KDV hariç tutar" }, "vat_rate": { "type": "string", "description": "KDV oranı (%)" }, "vat_amount": { "type": "string", "description": "KDV tutarı" }, "vat_exemption_code": { "nullable": true, "description": "KDV istisna kodu (ör. 351); istisna sebebi metni e-Belgeye koddan yazılır", "type": "string" }, "withholding_code": { "nullable": true, "description": "Tevkifat kodu", "type": "string" }, "withholding_amount": { "type": "string", "description": "Tevkifat tutarı" }, "total": { "type": "string", "description": "Toplam" } }, "required": [ "id", "line_no", "product_id", "description", "quantity", "unit", "unit_price", "discount_amount", "net_amount", "vat_rate", "vat_amount", "vat_exemption_code", "withholding_code", "withholding_amount", "total" ], "additionalProperties": false } }, "e_document": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "type": { "type": "string", "description": "efatura | earsiv" }, "status": { "type": "string", "description": "gonderiliyor | iletildi | kabul | red | iptal | hata" }, "status_label": { "type": "string", "description": "Durumun Türkçe açıklaması" }, "provider_status": { "type": "string", "description": "Entegratörün ham durumu" }, "number": { "nullable": true, "description": "GİB fatura numarası (16 hane)", "type": "string" }, "ettn": { "type": "string", "description": "ETTN (fatura evrensel kimliği, UUID)" }, "scenario": { "nullable": true, "description": "TEMELFATURA | TICARIFATURA | EARSIVFATURA …", "type": "string" }, "response_deadline": { "nullable": true, "description": "Ticari faturada alıcının kabul/red son günü", "type": "string" }, "message": { "nullable": true, "description": "Entegratör ya da GİB açıklaması (red gerekçesi, hata)", "type": "string" }, "sent_at": { "type": "string", "description": "GİB’e gönderilme zamanı" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "type", "status", "status_label", "provider_status", "number", "ettn", "scenario", "response_deadline", "message", "sent_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "description": "Son e-Belge (GİB) kaydı; gönderilmediyse null" }, "pdf_url": { "nullable": true, "description": "Oturum gerektirmeyen, paylaşılabilir PDF bağlantısı (kesilmiş faturada)", "type": "string" }, "issued_at": { "nullable": true, "type": "string", "description": "Kesilme zamanı" }, "sent_at": { "nullable": true, "type": "string", "description": "GİB’e gönderilme zamanı" }, "cancelled_at": { "nullable": true, "type": "string", "description": "İptal zamanı" }, "cancel_reason": { "nullable": true, "type": "string", "description": "İptal gerekçesi" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "updated_at": { "nullable": true, "type": "string", "description": "Son değişiklik zamanı (ISO 8601)" } }, "required": [ "id", "object", "type", "status", "number", "series", "issue_date", "issue_time", "due_date", "currency", "exchange_rate", "contact", "order_no", "notes", "e_document_type", "scenario", "ettn", "totals", "e_document", "pdf_url", "issued_at", "sent_at", "cancelled_at", "cancel_reason", "created_at", "updated_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "invoice", "type": "satis", "status": "odendi", "number": "WHM2026000000123", "series": "WHM", "issue_date": "2026-11-06", "issue_time": "12:30:00", "due_date": "2026-11-06", "currency": "TRY", "exchange_rate": "1", "contact": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "name": "Örnek Bilişim Ltd. Şti.", "tax_number": "1234567890" }, "order_no": "WHMCS-10452", "notes": null, "e_document_type": "earsiv", "scenario": "EARSIVFATURA", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "totals": { "subtotal": "1200.00", "discount": "0.00", "net": "1200.00", "vat": "240.00", "withholding": "0.00", "total": "1440.00", "payable": "1440.00", "paid": "1440.00", "remaining": "0.00" }, "lines": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "line_no": 1, "product_id": null, "description": "Profesyonel hosting (06.11.2026 - 05.11.2027)", "quantity": "1", "unit": "adet", "unit_price": "1200.00", "discount_amount": "0.00", "net_amount": "1200.00", "vat_rate": "20", "vat_amount": "240.00", "vat_exemption_code": null, "withholding_code": null, "withholding_amount": "0.00", "total": "1440.00" } ], "e_document": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "type": "earsiv", "status": "kabul", "status_label": "Raporlandı", "provider_status": "kabul", "number": "WHM2026000000123", "ettn": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a", "scenario": "EARSIVFATURA", "response_deadline": null, "message": null, "sent_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" }, "pdf_url": "https://app.carierp.com/api/open/v1/public/invoices/3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01/pdf?s=Qm9yYy1hbGFjYWstaGVwLWd1bmNlbA", "issued_at": "2026-11-06T09:30:00.000Z", "sent_at": "2026-11-06T09:30:00.000Z", "cancelled_at": null, "cancel_reason": null, "created_at": "2026-11-06T09:30:00.000Z", "updated_at": "2026-11-06T09:30:00.000Z" } }, "Tahsilat": { "type": "object", "properties": { "id": { "type": "string", "description": "Kasa/banka hareketinin kimliği" }, "object": { "type": "string", "enum": [ "payment" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "tahsilat (müşteriden) | odeme (tedarikçiye)" }, "status": { "type": "string", "description": "gecerli | iptal" }, "date": { "type": "string", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "amount": { "type": "string", "description": "Tutar" }, "currency": { "type": "string", "description": "Para birimi" }, "account_id": { "type": "string", "description": "Kasa/banka hesabı kimliği (GET /accounts)" }, "contact_id": { "nullable": true, "type": "string", "description": "Cari kimliği" }, "invoice_id": { "nullable": true, "type": "string", "description": "Fatura kimliği" }, "method": { "nullable": true, "type": "string", "description": "Ödeme yöntemi" }, "description": { "nullable": true, "type": "string", "description": "Açıklama" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" } }, "required": [ "id", "object", "type", "status", "date", "amount", "currency", "account_id", "contact_id", "invoice_id", "method", "description", "created_at" ], "additionalProperties": false, "example": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "payment", "type": "tahsilat", "status": "gecerli", "date": "2026-11-06", "amount": "1440.00", "currency": "TRY", "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "contact_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "invoice_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "method": "kart", "description": "Tahsilat: WHM2026000000123", "created_at": "2026-11-06T09:30:00.000Z" } }, "Hesap": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "account" ], "description": "Nesne türü" }, "type": { "type": "string", "description": "kasa | banka | kredi_karti | pos" }, "name": { "type": "string", "description": "Ad ya da ünvan" }, "bank_name": { "nullable": true, "type": "string", "description": "Banka adı" }, "iban": { "nullable": true, "type": "string", "description": "IBAN (TR ile başlayan, doğrulanır)" }, "currency": { "type": "string", "description": "Para birimi" }, "balance": { "type": "string", "description": "Bakiye" }, "is_active": { "type": "boolean", "description": "Etkin mi; false ise arşivlenmiş" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" } }, "required": [ "id", "object", "type", "name", "bank_name", "iban", "currency", "balance", "is_active", "created_at" ], "additionalProperties": false, "example": { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "account", "type": "banka", "name": "İş Bankası TL", "bank_name": "Türkiye İş Bankası", "iban": "TR330006100519786457841326", "currency": "TRY", "balance": "48250.75", "is_active": true, "created_at": "2026-11-06T09:30:00.000Z" } }, "HesapListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Hesap" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "object": "account", "type": "banka", "name": "İş Bankası TL", "bank_name": "Türkiye İş Bankası", "iban": "TR330006100519786457841326", "currency": "TRY", "balance": "48250.75", "is_active": true, "created_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Hareket": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "transaction" ], "description": "Nesne türü" }, "account_id": { "type": "string", "description": "Kasa/banka hesabı kimliği (GET /accounts)" }, "date": { "type": "string", "description": "Tarih (YYYY-AA-GG); boşsa bugün" }, "direction": { "type": "string", "description": "giris | cikis" }, "type": { "type": "string", "description": "tahsilat | tediye | virman | acilis | gider | gelir | pos | ekstre | duzeltme …" }, "amount": { "type": "string", "description": "Hesabın para biriminde tutar" }, "currency": { "type": "string", "description": "Para birimi" }, "amount_try": { "type": "string", "description": "TL karşılığı" }, "description": { "nullable": true, "type": "string", "description": "Açıklama" }, "contact_id": { "nullable": true, "type": "string", "description": "Cari kimliği" }, "invoice_id": { "nullable": true, "description": "Fatura tahsilatı/ödemesiyse ilgili fatura", "type": "string" }, "reconciled": { "type": "boolean", "description": "Banka ekstresiyle eşleşti mi" }, "reversal_of_id": { "nullable": true, "description": "Bu kayıt bir iptal (ters) kaydıysa iptal edilen hareket", "type": "string" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" } }, "required": [ "id", "object", "account_id", "date", "direction", "type", "amount", "currency", "amount_try", "description", "contact_id", "invoice_id", "reconciled", "reversal_of_id", "created_at" ], "additionalProperties": false, "example": { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "transaction", "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "date": "2026-11-06", "direction": "giris", "type": "tahsilat", "amount": "1440.00", "currency": "TRY", "amount_try": "1440.00", "description": "Tahsilat: WHM2026000000123", "contact_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "invoice_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "reconciled": false, "reversal_of_id": null, "created_at": "2026-11-06T09:30:00.000Z" } }, "HareketListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Hareket" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "transaction", "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "date": "2026-11-06", "direction": "giris", "type": "tahsilat", "amount": "1440.00", "currency": "TRY", "amount_try": "1440.00", "description": "Tahsilat: WHM2026000000123", "contact_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "invoice_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "reconciled": false, "reversal_of_id": null, "created_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "TahsilatListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tahsilat" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "7b2e9c41-0d3a-4f5e-8b6c-1a2b3c4d5e6f", "object": "payment", "type": "tahsilat", "status": "gecerli", "date": "2026-11-06", "amount": "1440.00", "currency": "TRY", "account_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "contact_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "invoice_id": "3f6c1d2e-8a4b-4c1d-9e2f-5a6b7c8d9e01", "method": "kart", "description": "Tahsilat: WHM2026000000123", "created_at": "2026-11-06T09:30:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "webhook" ], "description": "Nesne türü" }, "url": { "type": "string", "description": "Olayların gönderileceği https adresi" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Abone olunan olaylar" }, "active": { "type": "boolean", "description": "Etkin mi; false ise olay gönderilmez" }, "description": { "nullable": true, "type": "string", "description": "Açıklama" }, "status": { "type": "string", "description": "saglikli | hata | pasif" }, "last_delivery": { "nullable": true, "type": "object", "properties": { "at": { "type": "string", "description": "Zaman (ISO 8601)" }, "event": { "type": "string", "description": "Olay adı" }, "ok": { "type": "boolean", "description": "Başarılı mı (2xx)" }, "status": { "nullable": true, "type": "number", "description": "Durum" }, "ms": { "nullable": true, "type": "number", "description": "Yanıt süresi (milisaniye)" }, "error": { "nullable": true, "type": "string", "description": "Hata açıklaması" } }, "required": [ "at", "event", "ok", "status", "ms", "error" ], "additionalProperties": false, "description": "Son teslim denemesi" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" } }, "required": [ "id", "object", "url", "events", "active", "description", "status", "last_delivery", "created_at" ], "additionalProperties": false, "example": { "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "object": "webhook", "url": "https://muhasebe.ornekhosting.com/modules/addons/carierp/webhook.php", "events": [ "invoice.status_changed", "invoice.paid" ], "active": true, "description": "WHMCS", "status": "saglikli", "last_delivery": { "at": "2026-11-06T09:31:02.000Z", "event": "invoice.status_changed", "ok": true, "status": 200, "ms": 184, "error": null }, "created_at": "2026-11-06T09:00:00.000Z" } }, "WebhookListesi": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Kayıtlar" }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa (1’den başlar)" }, "per_page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sayfa başına kayıt (en çok 100)" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam" }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Toplam sayfa" } }, "required": [ "page", "per_page", "total", "total_pages" ], "additionalProperties": false, "description": "Sayfalama bilgisi" } }, "required": [ "data", "meta" ], "additionalProperties": false, "example": { "data": [ { "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "object": "webhook", "url": "https://muhasebe.ornekhosting.com/modules/addons/carierp/webhook.php", "events": [ "invoice.status_changed", "invoice.paid" ], "active": true, "description": "WHMCS", "status": "saglikli", "last_delivery": { "at": "2026-11-06T09:31:02.000Z", "event": "invoice.status_changed", "ok": true, "status": 200, "ms": 184, "error": null }, "created_at": "2026-11-06T09:00:00.000Z" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } }, "Webhook2": { "type": "object", "properties": { "id": { "type": "string", "description": "Kaydın kimliği (UUID)" }, "object": { "type": "string", "enum": [ "webhook" ], "description": "Nesne türü" }, "url": { "type": "string", "description": "Olayların gönderileceği https adresi" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Abone olunan olaylar" }, "active": { "type": "boolean", "description": "Etkin mi; false ise olay gönderilmez" }, "description": { "nullable": true, "type": "string", "description": "Açıklama" }, "status": { "type": "string", "description": "saglikli | hata | pasif" }, "last_delivery": { "nullable": true, "type": "object", "properties": { "at": { "type": "string", "description": "Zaman (ISO 8601)" }, "event": { "type": "string", "description": "Olay adı" }, "ok": { "type": "boolean", "description": "Başarılı mı (2xx)" }, "status": { "nullable": true, "type": "number", "description": "Durum" }, "ms": { "nullable": true, "type": "number", "description": "Yanıt süresi (milisaniye)" }, "error": { "nullable": true, "type": "string", "description": "Hata açıklaması" } }, "required": [ "at", "event", "ok", "status", "ms", "error" ], "additionalProperties": false, "description": "Son teslim denemesi" }, "created_at": { "type": "string", "description": "Oluşturulma zamanı (ISO 8601)" }, "secret": { "nullable": true, "description": "İmza anahtarı (whsec_…): yalnız firmanın ilk uç noktası eklenirken bir kez döner; sonra panelden yenilenir", "type": "string" } }, "required": [ "id", "object", "url", "events", "active", "description", "status", "last_delivery", "created_at", "secret" ], "additionalProperties": false, "example": { "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "object": "webhook", "url": "https://muhasebe.ornekhosting.com/modules/addons/carierp/webhook.php", "events": [ "invoice.status_changed", "invoice.paid" ], "active": true, "description": "WHMCS", "status": "saglikli", "last_delivery": { "at": "2026-11-06T09:31:02.000Z", "event": "invoice.status_changed", "ok": true, "status": 200, "ms": 184, "error": null }, "created_at": "2026-11-06T09:00:00.000Z", "secret": "whsec_3c5e…" } } }, "responses": { "Hata400": { "description": "İstek doğrulanamadı (DOGRULAMA_HATASI, GECERSIZ_ISTEK)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata401": { "description": "API anahtarı yok ya da geçersiz (API_ANAHTARI_GEREKLI, API_ANAHTARI_GECERSIZ)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata403": { "description": "Kapsam ya da paket izni yok (KAPSAM_YOK, PLAN_KAPSAMI_DISI, PUBLIC_API_KAPALI)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata404": { "description": "Kayıt bulunamadı (BULUNAMADI)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata409": { "description": "Kayıt zaten var (KAYIT_ZATEN_VAR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata422": { "description": "İş kuralı hatası (ör. FATURA_KESILMEMIS, ZATEN_GONDERILDI, TUTAR_FAZLA)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } }, "Hata429": { "description": "İstek sınırı aşıldı (ISTEK_SINIRI); Retry-After saniye bekleyin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hata" } } } } } }, "security": [ { "apiAnahtari": [] } ] }