{ "info": { "_postman_id": "6b1f0c2e-5d7a-4c93-8e41-0a7f3d9b2c58", "name": "YouSoft API (imzalı)", "description": "**Koleksiyon sürümü: v2.** YouSoft dış API'sinin (`/v1/*`) tüm uçlarını içerir ve her isteği sizin yerinize imzalar.\n\n## Başlamadan önce 3 adım\n\n1. Bu koleksiyonla birlikte **ortam dosyasını da** (`yousoft-api.postman_environment.json`) içe aktarın (Import) ve sağ üstteki ortam seçicisinden **YouSoft API** ortamını **seçin**. Ortam seçili değilse tüm değişkenler boş gelir.\n2. Ortamı açın (Environments > YouSoft API) ve `api_key` ile `api_secret` değerlerini **Current value** sütununa yazın (Initial value sütununa değil: o sütun paylaşılan dışa aktarmalara girer). Başında ya da sonunda boşluk bırakmayın.\n3. **1. Bağlantıyı doğrulayın > Kimlik (anahtarı doğrulayın)** isteğini çalıştırın. 200 aldıysanız kurulum tamamdır.\n\n## Temel kavramlar\n\n- **Firma:** API anahtarının bağlı olduğu şirket. Bayi panelinde \"müşteri\" olarak görünür (ör. \"Müşteri Bilgileri\" listesindeki bir satır).\n- **Cari kart:** Firmanın KENDİ müşteri ve tedarikçi kayıtları (`/v1/contacts`). Bayi panelindeki \"müşteri\" ile karıştırmayın.\n- Bir anahtar **tek bir firmaya** bağlıdır ve başka firmanın verisini görmez. Yeni firmada hiç cari kart yoktur: önce bir cari kart oluşturun. Dış API cari kartları ve ürünleri listelemez; oluşturma yanıtındaki `id` değerini kendi kaydınızda saklayın. Faturalar listelenir (\"4. Giden faturalar > Liste ve arama\", \"5. Gelen faturalar\").\n\n## 401 alıyorsanız kontrol listesi\n\nSunucu 401 nedenini bilerek söylemez (\"API anahtarı doğrulanamadı\"). Sırayla kontrol edin:\n\n1. `X-Api-Key` herkese açık anahtar kimliğidir (`ysk_` ile başlar). **Secret hiçbir başlığa yazılmaz;** yalnız `api_secret` ortam değişkeninde durur.\n2. `X-Api-Signature` 64 karakterlik onaltılık bir metindir. **Elle yazılmaz;** koleksiyon her istekte kendisi üretir.\n3. Sağ üstte **YouSoft API** ortamı seçili mi?\n4. `api_key` ve `api_secret` **Current value** sütununda dolu mu, başında ya da sonunda boşluk yok mu?\n5. İsteği **koleksiyonun içinde** mi kurdunuz? Koleksiyonun dışında elle kurulan istekler imzalanmaz. Yeni istek için \"8. Kendi isteğiniz (şablon)\" klasöründeki şablonu çoğaltın.\n6. `/api/*` ile başlayan yollar YouSoft **panelinin** uçlarıdır, dış API değildir. Yalnız `/v1/*` yolları çağrılır.\n7. Bilgisayarınızın saati sunucudan en çok 5 dakika sapabilir; saati otomatik eşitleyin.\n8. Postman Console'u açın (View > Show Postman Console): koleksiyon imza metnini ve uyarıları oraya yazar. Secret hiçbir zaman yazılmaz.\n\n## İmza kuralı (özet)\n\n`imza = HMAC-SHA256(secret, \"\\n\\n\\n\")`\n\nKoleksiyonun ön-istek betiği bunu hesaplar ve `X-Api-Key`, `X-Api-Timestamp`, `X-Api-Signature` başlıklarını koyar; betiği değiştirmeyin. Tüm kural ve test vektörü geliştirici portalının **/imzalama** sayfasındadır.\n\n## Değişkenler ve örnek yanıtlar\n\n`cari_id`, `fatura_id` gibi ortam değişkenleri isteklerce kendiliğinden doldurulur: oluşturma isteği yeni kaydın id'sini yazar, \"Ölçü birimi listesi\" ve \"Gelen fatura listesi\" değişken boşsa ilk satırı yazar, \"Fatura listesi\" arama örnekleri için `fatura_no`, `ettn` ve `zarf_id` değerlerini doldurur (`fatura_id`'ye dokunmaz). Dış API'de listesi olmayan kayıtların (makbuz, irsaliye) id değerini ortama elle yazın. Boş değişkenle istek atarsanız hangi isteği önce çalıştıracağınızı söyleyen bir hata alırsınız. Her isteğin altındaki **Examples** bölümünde sözleşmeyle birebir örnek yanıtlar (başarı ve tipik hatalar) kayıtlıdır.\n\n## Sınır ve uyarı\n\n- Anahtar başına anlık en çok **60 istek**, sürekli hızda dakikada 120; firmanın bütün anahtarları için toplam dakikada 300. XML ve PDF indirme uçlarının ayrı ve daha dar bir kotası ve firma başına aynı anda 4 indirme sınırı vardır. Aşılırsa 429 ve `Retry-After` başlığı döner; hangi kovanın dolduğu `X-RateLimit-Resource` başlığındadır.\n- **Bu API gerçek sistemle çalışır, deneme ortamı yoktur.** Oluşturma ve güncelleme istekleri gerçek kayıt açar ya da değiştirir. \"Faturayı gönderime al\" gerçek e-belge gönderir ve kontör harcar; \"Gönderilmiş faturayı iptal et\" geri alınamaz. **Collection Runner ile tüm koleksiyonu çalıştırmayın.**", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// YouSoft API imzası: HMAC-SHA256(secret, \"\\n\\n\\n\").", "// Kaynak: geliştirici portalının /imzalama sayfası (yayımlanmış test vektörü ile doğrulanır).", "// Üç X-Api-* başlığını bu betik koyar: başlığı elle eklemeyin, secret'ı hiçbir başlığa yazmayın.", "const sabit = pm.variables.get('zaman_damgasi_sabit');", "const anahtar = String(pm.variables.get('api_key') || '').trim();", "const secret = String(pm.variables.get('api_secret') || '').trim();", "if (!anahtar || !secret) {", " throw new Error('api_key ve api_secret dolu olmalı. Sağ üstten YouSoft API ortamını seçtiniz mi? Değerleri Environments > YouSoft API > Current value sütununa yazın.');", "}", "", "// zaman_damgasi_sabit doluysa yayımlanmış test vektörü yeniden üretiliyordur: örnek anahtar ysk_ taşımaz.", "if (sabit) {", " console.warn('zaman_damgasi_sabit dolu: imza sabit bir zaman damgasıyla üretilir ve sunucu 5 dakikadan eski damgayı 401 ile reddeder. Yalnız yayımlanmış test vektörünü denerken doldurun, normal kullanımda boş bırakın.');", "} else {", " if (anahtar.indexOf('ysk_') !== 0) {", " throw new Error('api_key X-Api-Key değeridir ve ysk_ ile başlar; secret değil. Güvenlik anahtarını (secret) api_secret alanına yazın.');", " }", " if (secret.indexOf('ysk_') === 0) {", " throw new Error('api_secret alanına X-Api-Key değeri (ysk_ ile başlar) yazılmış. Secret, anahtar üretilirken bir kez gösterilen ayrı değerdir.');", " }", " // Biçim ileride değişebilir: yalnız uyarı, hata değil.", " if (!/^[A-Za-z0-9_-]{43}$/.test(secret)) {", " console.warn('api_secret 43 karakterlik bir base64url metni olmalıydı (şu an ' + secret.length + ' karakter). Biçim ileride değişebilir, bu yüzden hata değil uyarı; yine de eksik ya da fazla kopyalanmış olabilir.');", " }", "}", "", "// Yalnız raw gövde imzalanır: form-data sınırı (boundary) gönderim anında üretilir, imzaya girmez.", "const govdeKipi = pm.request.body ? pm.request.body.mode : undefined;", "if (govdeKipi && govdeKipi !== 'raw') {", " throw new Error('Yalnız raw (JSON) gövde imzalanır; form-data/urlencoded kullanmayın.');", "}", "const hamGovde = govdeKipi === 'raw' ? (pm.request.body.raw || '') : '';", "const hamAdres = pm.request.url.toString();", "", "// Postman bilinmeyen değişkeni {{ad}} olarak bırakır, boş değişkeni ise '' yapar: ikisi de imzadan önce durdurulur.", "const YARDIM = {", " base_url: 'sağ üstten YouSoft API ortamını seçin (ortam seçili değilse tüm değişkenler boş gelir).',", " cari_id: 'önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda cari_id değerini elle yazın.',", " kisi_id: 'önce \"İletişim kişisi ekle\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda kisi_id değerini elle yazın.',", " urun_id: 'önce \"Ürün oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda urun_id değerini elle yazın.',", " kategori_id: 'önce \"Stok kategorisi oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda kategori_id değerini elle yazın.',", " etiket_id: 'önce \"Etiket oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda etiket_id değerini elle yazın.',", " birim_id: 'önce \"Ölçü birimi listesi\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda birim_id değerini elle yazın.',", " fatura_id: 'önce \"Fatura taslağı oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda fatura_id değerini elle yazın.',", " makbuz_id: 'dış API makbuzları listelemez: makbuzun id değerini ortamda makbuz_id olarak elle yazın.',", " irsaliye_id: 'dış API irsaliyeleri listelemez: irsaliyenin id değerini ortamda irsaliye_id olarak elle yazın.',", " gelen_fatura_id: 'önce \"Gelen fatura listesi\" isteğini çalıştırın (ilk satırdan dolar) ya da ortamda gelen_fatura_id değerini elle yazın.',", " fatura_no: 'önce \"Fatura listesi\" isteğini çalıştırın (ilk dolu satırdan dolar) ya da ortamda fatura_no değerini elle yazın.',", " ettn: 'önce \"Fatura listesi\" isteğini çalıştırın (ilk dolu satırdan dolar) ya da ortamda ettn değerini elle yazın.',", " zarf_id: 'önce \"Fatura listesi\" isteğini çalıştırın (yalnız e-Fatura satırında dolar) ya da ortamda zarf_id değerini elle yazın.',", "};", "const eksik = [];", "const dinamik = [];", "const jetonlariTara = (metin, dinamikYasak) => {", " (metin.match(/\\{\\{[^{}]+\\}\\}/g) || []).forEach((jeton) => {", " const ad = jeton.slice(2, -2).trim();", " if (ad.charAt(0) === '$') {", " if (dinamikYasak && dinamik.indexOf(ad) < 0) dinamik.push(ad);", " return;", " }", " const deger = pm.variables.get(ad);", " if ((deger === undefined || deger === null || String(deger).trim() === '') && eksik.indexOf(ad) < 0) eksik.push(ad);", " });", "};", "jetonlariTara(hamAdres, true);", "jetonlariTara(hamGovde, true);", "pm.request.headers.each((baslik) => {", " if (!baslik.disabled) jetonlariTara(String(baslik.value || ''), false);", "});", "if (eksik.length) {", " throw new Error(eksik.map((ad) => '{{' + ad + '}} boş: ' + (YARDIM[ad] || 'ortamda ' + ad + ' değerini doldurun.')).join(' | '));", "}", "if (dinamik.length) {", " throw new Error('Adreste ya da gövdede {{' + dinamik[0] + '}} gibi dinamik değişken var: imza ile gönderim farklı değer görür. Değeri sabit yazın.');", "}", "", "const govde = pm.variables.replaceIn(hamGovde);", "// Sunucu yolu EscapedPath, sorguyu HAM alır; sorgu yoksa \"?\" da yoktur.", "const tamAdres = pm.variables.replaceIn(hamAdres);", "const yolSorgu = tamAdres.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\\/\\/[^/?#]+/, '').replace(/\\?$/, '');", "", "// /api/* panelin uçlarıdır: anahtar ve imza orada geçmez, imzalamak yalnız yanıltıcı bir 401 üretir.", "if (/^\\/api(\\/|\\?|$)/.test(yolSorgu)) {", " throw new Error('Bu istek /api/* ile başlıyor: bunlar YouSoft PANELİNİN uçlarıdır, dış API değildir ve API anahtarıyla çağrılmaz (panel oturumu ister). Dış API yalnız /v1/* uçlarını sunar.');", "}", "if (yolSorgu.indexOf('/v1/') !== 0) {", " console.warn('Yol /v1/ ile başlamıyor (' + yolSorgu.split('?')[0] + '). base_url yalnız adres olmalı: sonunda bölü işareti ve yol bulunmamalı.');", "}", "// Postman boşluğu ve ASCII dışı karakteri kodlayarak gönderir, betik ise kodlanmamış hâlini görür: imza tutmaz.", "if (/[^\\x21-\\x7E]/.test(yolSorgu)) {", " console.warn('Adreste boşluk ya da ASCII dışı karakter var. Postman bunları kodlayarak gönderir ama imza kodlanmamış hâliyle hesaplanır, bu yüzden 401 alırsınız. Değerleri yüzde kodlu yazın (örn. boşluk için %20).');", "}", "", "// zaman_damgasi_sabit yalnız yayımlanmış test vektörünü yeniden üretmek içindir; normal kullanımda BOŞ kalır.", "const ts = sabit ? String(parseInt(sabit, 10)) : String(Math.floor(Date.now() / 1000));", "", "const govdeOzeti = CryptoJS.SHA256(govde).toString(CryptoJS.enc.Hex);", "const metin = ts + '\\n' + pm.request.method + '\\n' + yolSorgu + '\\n' + govdeOzeti;", "const imza = CryptoJS.HmacSHA256(metin, secret).toString(CryptoJS.enc.Hex);", "", "pm.request.headers.upsert({ key: 'X-Api-Key', value: anahtar });", "pm.request.headers.upsert({ key: 'X-Api-Timestamp', value: ts });", "pm.request.headers.upsert({ key: 'X-Api-Signature', value: imza });", "", "// Secret yazılmaz. Konsoldaki satırı, Postman Console'un gösterdiği GERÇEK istek adresiyle karşılaştırın.", "console.log('YouSoft imza metni (\\\\n = satır sonu): ' + metin.replace(/\\n/g, '\\\\n'));", "console.log('YouSoft imza: ' + imza);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Hata ipuçları: yanıt gövdesi ortak hata zarfıdır {\"error\",\"message\",\"details\"}. Secret hiçbir zaman yazılmaz.", "const kod = pm.response.code;", "const IPUCLARI = {", " 400: 'validation_failed: istekte geçersiz bir alan ya da parametre var; details.field hangisi olduğunu söyler.',", " 401: 'unauthorized: sunucu nedenini bilerek söylemez. Koleksiyon açıklamasındaki 401 kontrol listesine bakın (secret başlığa yazılmaz, ortam seçili mi, Current value dolu mu, saat sapması 5 dakikayı geçmemeli).',", " 403: 'forbidden: anahtarın bu uç için kapsamı yok (gerekli kapsam isteğin açıklamasında yazar). Kapsam sonradan değişmez, gerekirse yeni anahtar üretilir. Gönderim uçlarında hesabın kapalı olması da 403 verir, message nedeni söyler.',", " 404: 'not_found: kayıt yok ya da anahtarın firmasına ait değil. Adresteki id değişkenini (ortam) kontrol edin.',", " 409: 'conflict: istek kaydın bugünkü hâliyle çakışıyor (aynı VKN ya da kod, zaten yapılmış işlem); details.field çakışan alanı gösterir.',", " 422: 'invalid_state: istek geçerli ama iş kuralı bu anda izin vermiyor; message nedeni söyler.',", " 429: 'rate_limited: oran ya da eşzamanlılık tavanı aşıldı; X-RateLimit-Resource hangi kova olduğunu söyler (genel: anahtar başına dakikada 120, indirme: anahtar başına dakikada 60 istek; firma toplamı ve firma başına 4 eşzamanlı indirme ayrıca sayılır). Retry-After başlığındaki saniye kadar bekleyin.',", " 500: 'internal_error: sunucu hatası; details.request_id değerini destek talebine yazın.',", "};", "if (IPUCLARI[kod]) {", " let zarf = {};", " try {", " const cozulen = pm.response.json();", " if (cozulen && typeof cozulen === 'object') zarf = cozulen;", " } catch (e) {", " zarf = {};", " }", " const ayrinti = zarf.details && typeof zarf.details === 'object' ? zarf.details : {};", " console.warn('YouSoft ' + kod + ': ' + (zarf.error || '?') + ' | ' + (zarf.message || '(gövde yok)') + (ayrinti.field ? ' | alan: ' + ayrinti.field : '') + (ayrinti.request_id ? ' | request_id: ' + ayrinti.request_id : ''));", " pm.test(kod + ' ipucu: ' + IPUCLARI[kod], function () {});", "}", "", "// 401'in en sık sessiz nedeni saat sapmasıdır: sunucunun Date başlığı ile imzadaki zaman damgasını karşılaştırır.", "if (kod === 401) {", " const sunucuAni = Date.parse(pm.response.headers.get('Date') || '');", " const damga = Number(pm.request.headers.get('X-Api-Timestamp'));", " if (!isNaN(sunucuAni) && damga) {", " const sapma = Math.round(damga - sunucuAni / 1000);", " if (Math.abs(sapma) > 300) {", " const sabitNotu = pm.variables.get('zaman_damgasi_sabit') ? ' zaman_damgasi_sabit dolu: boşaltın.' : '';", " console.warn('Saat uyarısı: imzadaki zaman damgası sunucu saatinden ' + Math.abs(sapma) + ' sn ' + (sapma > 0 ? 'ileride' : 'geride') + ' (en çok 300 sn kabul edilir). Bilgisayarınızın saatini otomatik eşitleyin; VPN ya da sanal makine saat kayması yaygın nedendir.' + sabitNotu);", " pm.test('Saat uyarısı: imza saati sunucudan ' + Math.abs(sapma) + ' sn sapmış, 401 nedeni bu olabilir.', function () {});", " }", " }", "}" ] } } ], "item": [ { "name": "1. Bağlantıyı doğrulayın", "description": "Önce **Kimlik (anahtarı doğrulayın)** isteğini çalıştırın. 200 alıyorsanız anahtar, secret, imza ve saat doğrudur. 401 alıyorsanız koleksiyon açıklamasındaki kontrol listesine bakın. Bu klasördeki istekler salt okumadır.", "item": [ { "name": "Kimlik (anahtarı doğrulayın)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"], "query": [ { "key": "include", "value": "firma", "description": "`firma` bağlı firmanın özetini (`firma.title`, `firma.tax_number`) yanıtın içine ekler. Anahtarın hangi firmaya bağlı olduğunu doğrulamak için açın.", "disabled": true } ] }, "description": "Çağrıyı yapan API anahtarının kimliğini ve bağlı olduğu firmayı döner. Kurulumu doğrulamanın en ucuz yolu budur: anahtar, secret, imza ve saat doğruysa 200 alırsınız. Anahtarı üreten kişinin adı ve e-postası yanıtta yer almaz.\n\n**Gerekli kapsam:** yok, geçerli her anahtar çağırabilir.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `include`.\n\n**Notlar:**\n- **İlk deneme bu istektir.** Bu istek 200 dönmeden diğerlerini denemeyin: 401 alıyorsanız koleksiyon açıklamasındaki kontrol listesine bakın.\n\n**Örnek yanıtlar hakkında:**\n- `401` Anahtar ya da imza doğrulanamadı: Sunucu nedenini bilerek söylemez: anahtar yok, kapalı, imza yanlış ya da saat sapmış olabilir. Kontrol listesi koleksiyon açıklamasındadır." }, "response": [ { "name": "Anahtarın kimliği", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5cc-f37d-7754-9b94-cf5a9429e904" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"role\": \"API_CLIENT\",\n \"scope\": \"API\",\n \"firma_id\": \"0191e515-2e76-767e-ab5d-0500f96619e5\",\n \"api_client_id\": \"0191e520-15ed-74ac-a95c-a15b584d852b\"\n }\n}" }, { "name": "Anahtar ya da imza doğrulanamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5da-349d-72d6-9bc7-e1a2c5fc0488" } ], "cookie": [], "body": "{\n \"error\": \"unauthorized\",\n \"message\": \"API anahtarı doğrulanamadı\"\n}" } ] }, { "name": "Sözleşmeyi indirin (OpenAPI)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/openapi.yaml", "host": ["{{base_url}}"], "path": ["v1", "openapi.yaml"] }, "description": "Bu API sözleşmesinin güncel metnini (OpenAPI 3.1, YAML) döner. Diğer uçlar gibi anahtar ve imza ister. Postman ya da kod üreticisine içe aktarmak için kullanabilirsiniz; aynı içerik geliştirici portalındaki OpenAPI referansında okunur.\n\n**Gerekli kapsam:** yok, geçerli her anahtar çağırabilir.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez." }, "response": [ { "name": "OpenAPI belgesi (YAML, kısaltılmış)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/openapi.yaml", "host": ["{{base_url}}"], "path": ["v1", "openapi.yaml"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "text", "header": [ { "key": "Content-Type", "value": "application/yaml" }, { "key": "X-Request-Id", "value": "0191e508-4bbb-7e8c-b993-34873695d95b" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "openapi: 3.1.0\ninfo:\n title: YouSoft Dış API\n version: '1.0.4'\n# ... (belgenin devamı kısaltıldı)" }, { "name": "Anahtar ya da imza doğrulanamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/openapi.yaml", "host": ["{{base_url}}"], "path": ["v1", "openapi.yaml"] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e579-a851-7698-a7bd-66f0626b48f6" } ], "cookie": [], "body": "{\n \"error\": \"unauthorized\",\n \"message\": \"API anahtarı doğrulanamadı\"\n}" } ] } ] }, { "name": "2. Cari kartlar", "description": "**Firma ile cari kart farkı:** API anahtarı bir **firmaya** bağlıdır (bayi panelinde \"Müşteri Bilgileri\" listesindeki bir satır, örneğin \"Örnek Test Müşterisi\"). `/v1/contacts` ise o firmanın **içindeki** cari kartlardır: firmanın kendi müşterileri ve tedarikçileri. Yeni firmada hiç cari kart yoktur.\n\n**Sıra:** ilk denemede önce \"Cari kart oluştur\" isteğini çalıştırın. Diğer istekler `cari_id` ortam değişkenindeki karta gider; değişken oluşturma isteğince kendiliğinden dolar. Dış API cari kartları listelemez, okumaz ve silmez: oluşturma yanıtındaki `id` değerini kendi kaydınızda saklayın.", "item": [ { "name": "Kartlar", "item": [ { "name": "Cari kart oluştur", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts", "host": ["{{base_url}}"], "path": ["v1", "contacts"] }, "description": "Anahtarın bağlı olduğu firmaya yeni bir cari kart (firmanın müşterisi ya da tedarikçisi) açar. **Yeni firmada hiç cari kart yoktur: ilk denemede önce bu isteği çalıştırın.** Dış API cari kartları listelemez ve tek tek okumaz: yanıttaki `id` değerini kendi kaydınızda saklayın. Panelle aynı kuralları uygular: aynı VKN ya da TCKN ikinci kez kabul edilmez, `code` verilmezse sunucu üretir (örneğin `M013`). Gövdede olmayan alan panelin varsayılanını alır.\n\n**Gerekli kapsam:** `Kart.MusteriTedarikciDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı kayıt açar.** Üretimde gerçek bir cari kart doğar; dış API'de silme ucu yoktur.\n\n**Notlar:**\n- Örnekteki `1234567890` sunucunun VKN doğrulayıcısından geçen uydurma bir değerdir. **Aynı VKN ikinci kez 409 `conflict` verir**; tekrar denerken kontrol basamağını tutan başka bir VKN kullanın. Kontrol basamağı tutmayan değer 400 alır. Nihai tüketici `11111111111` ve yurt dışı alıcı `2222222222` istisnadır.\n- e-Fatura ve e-Arşiv gönderimi alıcının `address.city` (il) ve `address.district` (ilçe) bilgisini ister; eksik kartta kesilen belge gönderimde 400 alır.\n- Gövde alanları: `title` zorunlu. `type` MUSTERI, TEDARIKCI, MUSTERI_TEDARIKCI ya da PERSONEL (varsayılan MUSTERI, açıldıktan sonra değişmez). `person_type` GERCEK ya da TUZEL. `tax_number` 10 haneli VKN, `national_id` 11 haneli TCKN.\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır). Dış API kartı okumaz: zaman aşımından sonra kartın açılıp açılmadığını panelden doğrulayın (aynı VKN ile yeniden gönderim 409 `conflict` alır).\n- Başarılı yanıtta `cari_id` ortam değişkeni yeni kartın id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si cari_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('cari_id', veri.id);", " console.log('cari_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan cari kart", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts", "host": ["{{base_url}}"], "path": ["v1", "contacts"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e59c-27ef-7d8e-abec-de90b0078e87" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e562-1348-75a9-bbb8-7af792d33d98\",\n \"code\": \"M013\",\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"status\": \"active\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\"\n },\n \"created_at\": \"2026-10-04T09:12:31.482913Z\",\n \"updated_at\": \"2026-10-04T09:12:31.482913Z\"\n }\n}" }, { "name": "Geçersiz VKN", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts", "host": ["{{base_url}}"], "path": ["v1", "contacts"] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5fe-d42a-7bad-a541-d3e85c601dd7" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"tax_number 10 haneli, kontrol basamağı tutan bir VKN olmalı\",\n \"details\": {\n \"field\": \"tax_number\"\n }\n}" }, { "name": "Aynı VKN ile kart var", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts", "host": ["{{base_url}}"], "path": ["v1", "contacts"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e555-31f4-7544-a82e-f711765ff79f" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Bu VKN ile kayıtlı cari zaten mevcut\",\n \"details\": {\n \"field\": \"tax_number\"\n }\n}" } ] }, { "name": "Cari kartı güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"short_title\": \"Örnek Müşteri\",\n \"address\": {\n \"neighborhood\": \"Fikirtepe\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}"] }, "description": "Cari kartı kısmen günceller: yalnız gönderilen alanlar yazılır, gönderilmeyen alan olduğu gibi kalır. `null` göndermek \"dokunma\" demektir; bir alanı boşaltmak için boş dize gönderin (`title` ve `code` boşaltılamaz). `address` alan alan birleştirilir.\n\n**Gerekli kapsam:** `Kart.MusteriTedarikciDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kartı kalıcı olarak değiştirir.** `type` kart açıldıktan sonra değişmez: farklı bir değer 400 alır.\n\n**Kullanılan değişkenler (ortam):**\n- `{{cari_id}}`: Cari kartın id'si. Boşsa önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Çakışma ve kimlik doğrulama kuralları \"Cari kart oluştur\" ile aynıdır (409 `conflict`, 400 `validation_failed`).\n- GİB dizininde doğrulanmış kartta `title`, `tax_number` ve `national_id` değişmez; `tax_office` ve `address` alanları doluysa değişmez, boşsa bir kez doldurulur (400 `validation_failed`, `details.field` alanın adı)." }, "response": [ { "name": "Güncellenmiş cari kart", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"short_title\": \"Örnek Müşteri\",\n \"address\": {\n \"neighborhood\": \"Fikirtepe\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5cd-6554-783c-a29c-d18ffc3df655" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e562-1348-75a9-bbb8-7af792d33d98\",\n \"code\": \"M013\",\n \"title\": \"Örnek Müşteri A.Ş.\",\n \"type\": \"MUSTERI\",\n \"person_type\": \"TUZEL\",\n \"tax_number\": \"1234567890\",\n \"tax_office\": \"Kadıköy\",\n \"status\": \"active\",\n \"address\": {\n \"line\": \"Örnek Mah. Deneme Sok. No:1\",\n \"district\": \"Kadıköy\",\n \"city\": \"İstanbul\",\n \"country\": \"TR\",\n \"neighborhood\": \"Fikirtepe\"\n },\n \"created_at\": \"2026-10-04T09:12:31.482913Z\",\n \"updated_at\": \"2026-10-04T10:02:44.208117Z\",\n \"short_title\": \"Örnek Müşteri\"\n }\n}" }, { "name": "Kod başka kartta kullanılıyor", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"short_title\": \"Örnek Müşteri\",\n \"address\": {\n \"neighborhood\": \"Fikirtepe\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e589-5861-7f82-941c-cc548a3d1afc" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Bu cari kodu ile kayıtlı cari zaten mevcut\",\n \"details\": {\n \"field\": \"code\"\n }\n}" } ] } ] }, { "name": "İletişim kişileri", "item": [ { "name": "İletişim kişisi ekle", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Ayşe Örnek\",\n \"job_title\": \"Muhasebe Müdürü\",\n \"email\": \"ayse.ornek@example.com\",\n \"phone\": \"+90 212 555 01 01\",\n \"is_primary\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people"] }, "description": "Cari karta bir iletişim kişisi ekler. `name` zorunludur; e-posta biçimi denetlenir.\n\n**Gerekli kapsam:** `Kart.MusteriTedarikciDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı kayıt açar.** `is_primary: true` gönderirken kartın zaten birincil kişisi varsa istek 409 `conflict` alır; sunucu eski birincil kişiyi sessizce düşürmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{cari_id}}`: Cari kartın id'si. Boşsa önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır). Dış API kişileri okumaz: zaman aşımından sonra kişinin eklenip eklenmediğini panelden doğrulayın.\n- Başarılı yanıtta `kisi_id` ortam değişkeni yeni kişinin id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si kisi_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('kisi_id', veri.id);", " console.log('kisi_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan kişi", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Ayşe Örnek\",\n \"job_title\": \"Muhasebe Müdürü\",\n \"email\": \"ayse.ornek@example.com\",\n \"phone\": \"+90 212 555 01 01\",\n \"is_primary\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5ec-6f0f-7d1c-ae14-d4309d0b6271" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e502-339f-7173-b532-676d38fdda12\",\n \"contact_id\": \"0191e562-1348-75a9-bbb8-7af792d33d98\",\n \"name\": \"Ayşe Örnek\",\n \"job_title\": \"Muhasebe Müdürü\",\n \"email\": \"ayse.ornek@example.com\",\n \"phone\": \"+90 212 555 01 01\",\n \"is_primary\": true,\n \"created_at\": \"2026-10-04T09:40:05.117204Z\",\n \"updated_at\": \"2026-10-04T09:40:05.117204Z\"\n }\n}" }, { "name": "Kartın birincil kişisi zaten var", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Ayşe Örnek\",\n \"job_title\": \"Muhasebe Müdürü\",\n \"email\": \"ayse.ornek@example.com\",\n \"phone\": \"+90 212 555 01 01\",\n \"is_primary\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5a5-09d0-781b-a97c-a2f579a2d1b6" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Kartın birincil iletişim kişisi zaten tanımlı\",\n \"details\": {\n \"field\": \"is_primary\"\n }\n}" } ] }, { "name": "İletişim kişisini güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"job_title\": \"Mali İşler Direktörü\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people/{{kisi_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people", "{{kisi_id}}"] }, "description": "İletişim kişisini kısmen günceller: yalnız gönderilen alan yazılır, `null` \"dokunma\" demektir. Yolun cari kartına ait olmayan kişi id'si 404 alır.\n\n**Gerekli kapsam:** `Kart.MusteriTedarikciDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kişiyi kalıcı olarak değiştirir.**\n\n**Kullanılan değişkenler (ortam):**\n- `{{cari_id}}`: Cari kartın id'si. Boşsa önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n- `{{kisi_id}}`: İletişim kişisinin id'si. Boşsa önce \"İletişim kişisi ekle\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın." }, "response": [ { "name": "Güncellenmiş kişi", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"job_title\": \"Mali İşler Direktörü\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people/{{kisi_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people", "{{kisi_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e54b-5494-7e86-acb6-d9503195cc63" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e502-339f-7173-b532-676d38fdda12\",\n \"contact_id\": \"0191e562-1348-75a9-bbb8-7af792d33d98\",\n \"name\": \"Ayşe Örnek\",\n \"job_title\": \"Mali İşler Direktörü\",\n \"email\": \"ayse.ornek@example.com\",\n \"phone\": \"+90 212 555 01 01\",\n \"is_primary\": true,\n \"created_at\": \"2026-10-04T09:40:05.117204Z\",\n \"updated_at\": \"2026-10-04T10:15:09.771402Z\"\n }\n}" }, { "name": "Kişi bulunamadı", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"job_title\": \"Mali İşler Direktörü\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/contacts/{{cari_id}}/people/{{kisi_id}}", "host": ["{{base_url}}"], "path": ["v1", "contacts", "{{cari_id}}", "people", "{{kisi_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e53d-4bf0-7419-9809-9825b496061b" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"İletişim kişisi bulunamadı\"\n}" } ] } ] } ] }, { "name": "3. Ürünler ve stok", "description": "Ürün (stok kartı), stok hareketi, stok kategorisi, belge etiketi ve ölçü birimi uçları. Stok hareketi oluşturmak ürünün stok sayısını kalıcı olarak değiştirir. Dış API ürünleri, stok hareketlerini, kategorileri ve etiketleri listelemez: oluşturma yanıtındaki `id` değerini saklayın.", "item": [ { "name": "Ürünler", "item": [ { "name": "Ürün oluştur", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"code\": \"STK-0001\",\n \"name\": \"Kablosuz Mouse\",\n \"unit\": \"ADET\",\n \"type\": \"STOK\",\n \"vat_rate\": 20,\n \"unit_price\": 450,\n \"currency\": \"TRY\",\n \"brand\": \"Örnek Marka\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products", "host": ["{{base_url}}"], "path": ["v1", "products"] }, "description": "Yeni bir stok ya da hizmet kartı açar. Yazmada `vat_rate` ve `unit_price` sayıdır (okumada ondalık metin döner); ikisi de iki ondalıklı saklanır.\n\n**Gerekli kapsam:** `Kart.Stok`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı kayıt açar.** Aynı `code` ile kart varsa 409 `conflict` (`details.field: code`); örneği ikinci kez göndermeden önce `code` değerini değiştirin.\n\n**Notlar:**\n- Zorunlu alanlar: `code`, `name`, `unit`. `unit`: `ADET`, `KG`, `GR`, `TON`, `LT`, `ML`, `M`, `M2`, `M3`, `PKT`, `KOLI`, `KUTU` ya da firmanın \"Ölçü birimleri\" listesindeki bir birimin `code` değeri (büyük/küçük harf birebir). Birim listesi için bu klasördeki \"Ölçü birimleri\" isteklerine bakın.\n- `vat_rate`: 0, 1, 8, 10, 18 ya da 20 (varsayılan 20). `currency`: büyük harfli ISO 4217 kodu (varsayılan `TRY`). `type`: `STOK` ya da `HIZMET` (varsayılan `STOK`). `category_id` için \"Stok kategorisi oluştur\" yanıtındaki id kullanılabilir.\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır).\n- Başarılı yanıtta `urun_id` ortam değişkeni yeni kartın id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si urun_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('urun_id', veri.id);", " console.log('urun_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan ürün", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"code\": \"STK-0001\",\n \"name\": \"Kablosuz Mouse\",\n \"unit\": \"ADET\",\n \"type\": \"STOK\",\n \"vat_rate\": 20,\n \"unit_price\": 450,\n \"currency\": \"TRY\",\n \"brand\": \"Örnek Marka\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products", "host": ["{{base_url}}"], "path": ["v1", "products"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e55e-3315-7de0-b452-8e1c99b26d0b" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5c3-f259-71a9-b91d-7a19f7be758b\",\n \"code\": \"STK-0001\",\n \"name\": \"Kablosuz Mouse\",\n \"type\": \"STOK\",\n \"unit\": \"ADET\",\n \"vat_rate\": \"20.00\",\n \"unit_price\": \"450.00\",\n \"currency\": \"TRY\",\n \"brand\": \"Örnek Marka\",\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n}" }, { "name": "Aynı kodla kart var", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"code\": \"STK-0001\",\n \"name\": \"Kablosuz Mouse\",\n \"unit\": \"ADET\",\n \"type\": \"STOK\",\n \"vat_rate\": 20,\n \"unit_price\": 450,\n \"currency\": \"TRY\",\n \"brand\": \"Örnek Marka\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products", "host": ["{{base_url}}"], "path": ["v1", "products"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5c2-80da-7012-88d3-ff82c60ae287" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Bu stok kodu ile kayıtlı kart zaten mevcut\",\n \"details\": {\n \"field\": \"code\"\n }\n}" } ] }, { "name": "Ürünü güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"unit_price\": 475,\n \"description\": \"Fiyat Ekim 2026 listesine göre güncellendi\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products/{{urun_id}}", "host": ["{{base_url}}"], "path": ["v1", "products", "{{urun_id}}"] }, "description": "Stok kartını kısmen günceller; gönderilmeyen alan olduğu gibi kalır. `code`, `name` ve `unit` boş dizeyle boşaltılamaz (400). `category_id: \"\"` kartın kategorisini kaldırır. Gönderilen `unit`, `currency`, `vat_rate` ve `unit_price` \"Ürün oluştur\" ile aynı kurallarla denetlenir.\n\n**Gerekli kapsam:** `Kart.Stok`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kartı kalıcı olarak değiştirir.**\n\n**Kullanılan değişkenler (ortam):**\n- `{{urun_id}}`: Ürünün (stok kartının) id'si. Boşsa önce \"Ürün oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın." }, "response": [ { "name": "Güncellenmiş ürün", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"unit_price\": 475,\n \"description\": \"Fiyat Ekim 2026 listesine göre güncellendi\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products/{{urun_id}}", "host": ["{{base_url}}"], "path": ["v1", "products", "{{urun_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e570-8648-7e62-a2d5-80c99c5861af" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5c3-f259-71a9-b91d-7a19f7be758b\",\n \"code\": \"STK-0001\",\n \"barcode\": \"8690000000011\",\n \"name\": \"Kablosuz Mouse\",\n \"type\": \"STOK\",\n \"unit\": \"ADET\",\n \"vat_rate\": \"20.00\",\n \"unit_price\": \"475.00\",\n \"currency\": \"TRY\",\n \"stock_count\": \"120.0000\",\n \"category_id\": \"0191e5ac-deb6-7230-a33c-1a306f633821\",\n \"brand\": \"Örnek Marka\",\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-10-04T10:20:31.640221Z\",\n \"description\": \"Fiyat Ekim 2026 listesine göre güncellendi\"\n }\n}" }, { "name": "Kart bulunamadı", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"unit_price\": 475,\n \"description\": \"Fiyat Ekim 2026 listesine göre güncellendi\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products/{{urun_id}}", "host": ["{{base_url}}"], "path": ["v1", "products", "{{urun_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5af-3909-7705-859b-a477be75e669" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Stok kartı bulunamadı\"\n}" } ] } ] }, { "name": "Stok hareketleri", "item": [ { "name": "Stok hareketi oluştur (DİKKAT: gerçek stok yazar)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"Giriş\",\n \"date\": \"2026-10-04\",\n \"document_no\": \"STK-GIRIS-0001\",\n \"currency\": \"TRY\",\n \"description\": \"Açılış girişi\",\n \"items\": [\n {\n \"product_id\": \"{{urun_id}}\",\n \"quantity\": \"100\",\n \"unit_price\": \"450\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/stock-movements", "host": ["{{base_url}}"], "path": ["v1", "stock-movements"] }, "description": "Giriş, çıkış, devir ya da transfer hareketini satırlarıyla birlikte yazar: biri başarısız olursa hiçbiri yazılmaz ve depo bakiyeleri aynı işlemde güncellenir. Yanıt, oluşan defter satırlarının dizisidir (transfer iki satır üretir: çıkış ve giriş).\n\n**Gerekli kapsam:** `Kart.Stok`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Gerçek stok değiştirir.** Hareketin güncellenmesi ve silinmesi bu sürümde yoktur: düzeltme ters hareketle yapılır.\n\n**Kullanılan değişkenler (ortam):**\n- `{{urun_id}}`: Ürünün (stok kartının) id'si. Boşsa önce \"Ürün oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Örnek, `urun_id` değişkenindeki karta 100 adet giriş yazar; ürün `STOK` tipinde olmalıdır (hizmet kartı 400 alır). `type`: `Giriş`, `Çıkış`, `Devir` (açılış girişi) ya da `Transfer`. `quantity` ve `unit_price` ondalık metindir.\n- `warehouse_id` verilmezse: firmanın tek aktif stok lokasyonu varsa hareket ona yazılır, birden çoksa depoya bağlanmaz (\"Genel\" grubu). Dış API depoları listelemez; belirli bir depo için deponun id değerini `warehouse_id` olarak ekleyin. Transferde `counterparty_warehouse_id` zorunludur ve `warehouse_id` ile aynı olamaz.\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır)." }, "response": [ { "name": "Oluşan defter satırları", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"Giriş\",\n \"date\": \"2026-10-04\",\n \"document_no\": \"STK-GIRIS-0001\",\n \"currency\": \"TRY\",\n \"description\": \"Açılış girişi\",\n \"items\": [\n {\n \"product_id\": \"{{urun_id}}\",\n \"quantity\": \"100\",\n \"unit_price\": \"450\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/stock-movements", "host": ["{{base_url}}"], "path": ["v1", "stock-movements"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5a9-1d84-7591-8af5-bf99c69eab74" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5cd-a4f5-7c18-ad0c-4c93ff1825d6\",\n \"product_id\": \"0191e5c3-f259-71a9-b91d-7a19f7be758b\",\n \"date\": \"2026-10-04T00:00:00Z\",\n \"document_no\": \"STK-GIRIS-0001\",\n \"document_type\": \"Stok İşlemi\",\n \"type\": \"Giriş\",\n \"warehouse_id\": \"0191e5ac-3e84-7537-a7b1-07ec1be62636\",\n \"quantity\": \"100.0000\",\n \"unit_price\": \"450.00\",\n \"amount\": \"45000.00\",\n \"balance_quantity\": \"120.0000\",\n \"description\": \"Açılış girişi\"\n }\n ]\n}" }, { "name": "Hizmet kartına stok girişi yapılamaz", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"Giriş\",\n \"date\": \"2026-10-04\",\n \"document_no\": \"STK-GIRIS-0001\",\n \"currency\": \"TRY\",\n \"description\": \"Açılış girişi\",\n \"items\": [\n {\n \"product_id\": \"{{urun_id}}\",\n \"quantity\": \"100\",\n \"unit_price\": \"450\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/stock-movements", "host": ["{{base_url}}"], "path": ["v1", "stock-movements"] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e50a-c2f7-779c-8e1d-45451e064a2b" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"Hizmet kartına stok girişi yapılamaz\",\n \"details\": {\n \"field\": \"items[0].product_id\"\n }\n}" } ] } ] }, { "name": "Stok kategorileri", "item": [ { "name": "Stok kategorisi oluştur", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Bilgisayar Çevre Birimleri\",\n \"sort_order\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories", "host": ["{{base_url}}"], "path": ["v1", "item-categories"] }, "description": "Yeni bir stok kategorisi açar. `parent_id` verilmezse (ya da boş dizeyse) kök kategori olur.\n\n**Gerekli kapsam:** `Kart.Stok`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı kayıt açar.** Firmada aynı adla bir kategori varsa 409 `conflict` (`details.field: name`); olmayan ya da UUID olmayan `parent_id` 400 alır.\n\n**Notlar:**\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır).\n- Başarılı yanıtta `kategori_id` ortam değişkeni yeni kategorinin id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si kategori_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('kategori_id', veri.id);", " console.log('kategori_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan kategori", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Bilgisayar Çevre Birimleri\",\n \"sort_order\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories", "host": ["{{base_url}}"], "path": ["v1", "item-categories"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e57f-6c47-7239-a269-d27b936bf645" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5ac-deb6-7230-a33c-1a306f633821\",\n \"name\": \"Bilgisayar Çevre Birimleri\",\n \"sort_order\": 1,\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n}" }, { "name": "Aynı adla kategori var", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Bilgisayar Çevre Birimleri\",\n \"sort_order\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories", "host": ["{{base_url}}"], "path": ["v1", "item-categories"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e58d-b9ae-7ee4-87b2-619c93f7d568" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Bu adla kayıtlı kategori zaten mevcut\",\n \"details\": {\n \"field\": \"name\"\n }\n}" } ] }, { "name": "Stok kategorisini güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çevre Birimleri\",\n \"sort_order\": 2\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories/{{kategori_id}}", "host": ["{{base_url}}"], "path": ["v1", "item-categories", "{{kategori_id}}"] }, "description": "Kategoriyi kısmen günceller. `parent_id` kategorinin kendisi ya da altındaki bir kategori olamaz (400). `parent_id: \"\"` kategoriyi köke taşır, alanı hiç göndermemek üst kategoriye dokunmaz. `name` boşaltılamaz.\n\n**Gerekli kapsam:** `Kart.Stok`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kategoriyi kalıcı olarak değiştirir.** Firmadaki başka bir kategorinin adı 409 `conflict` alır.\n\n**Kullanılan değişkenler (ortam):**\n- `{{kategori_id}}`: Stok kategorisinin id'si. Boşsa önce \"Stok kategorisi oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın." }, "response": [ { "name": "Güncellenmiş kategori", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çevre Birimleri\",\n \"sort_order\": 2\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories/{{kategori_id}}", "host": ["{{base_url}}"], "path": ["v1", "item-categories", "{{kategori_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5af-05cc-7493-9442-0c4d38228de8" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5ac-deb6-7230-a33c-1a306f633821\",\n \"name\": \"Çevre Birimleri\",\n \"parent_id\": \"0191e5b9-7fe6-7b8c-89b0-d919f8149732\",\n \"sort_order\": 2,\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-10-04T10:31:02.115880Z\"\n }\n}" }, { "name": "Kategori bulunamadı", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çevre Birimleri\",\n \"sort_order\": 2\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/item-categories/{{kategori_id}}", "host": ["{{base_url}}"], "path": ["v1", "item-categories", "{{kategori_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5cd-75e8-7c8b-adbd-fadd694a2e9d" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Kategori bulunamadı\"\n}" } ] } ] }, { "name": "Etiketler", "item": [ { "name": "Etiket oluştur", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Öncelikli\",\n \"color\": \"#2563EB\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags", "host": ["{{base_url}}"], "path": ["v1", "tags"] }, "description": "Yeni bir belge etiketi açar. Etiket her zaman aktif oluşur: `status: passive` 400 alır (pasife almak için ayrı bir güncelleme gerekir). `color` `#RRGGBB` biçiminde ya da boş olur.\n\n**Gerekli kapsam:** `Kart.BelgeSiniflari`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı kayıt açar.** Etiket adı benzersiz değildir: aynı adla ikinci bir etiket açılabilir, bu yüzden isteği tekrarlamak çift kayıt bırakır.\n\n**Notlar:**\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur (ya da çakışma kuralına takılıp 409 alır).\n- Başarılı yanıtta `etiket_id` ortam değişkeni yeni etiketin id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si etiket_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('etiket_id', veri.id);", " console.log('etiket_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan etiket", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Öncelikli\",\n \"color\": \"#2563EB\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags", "host": ["{{base_url}}"], "path": ["v1", "tags"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e53d-b8a8-7dd6-ab29-98b90c2cabeb" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5e0-fb54-73be-a036-9c2fefcf9552\",\n \"name\": \"Öncelikli\",\n \"color\": \"#2563EB\",\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n}" }, { "name": "Geçersiz renk", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Öncelikli\",\n \"color\": \"#2563EB\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags", "host": ["{{base_url}}"], "path": ["v1", "tags"] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5bc-7f6e-755f-976a-6593ede37a80" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"color #RRGGBB biçiminde olmalı\",\n \"details\": {\n \"field\": \"color\"\n }\n}" } ] }, { "name": "Etiketi güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çok öncelikli\",\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags/{{etiket_id}}", "host": ["{{base_url}}"], "path": ["v1", "tags", "{{etiket_id}}"] }, "description": "Etiketi kısmen günceller; gönderilmeyen (ya da `null` gönderilen) alana dokunulmaz. Pasife almak için `status: passive` gönderin. `group_id` bu uçtan koparılamaz.\n\n**Gerekli kapsam:** `Kart.BelgeSiniflari`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Etiketi kalıcı olarak değiştirir.**\n\n**Kullanılan değişkenler (ortam):**\n- `{{etiket_id}}`: Belge etiketinin id'si. Boşsa önce \"Etiket oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın." }, "response": [ { "name": "Güncellenmiş etiket", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çok öncelikli\",\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags/{{etiket_id}}", "host": ["{{base_url}}"], "path": ["v1", "tags", "{{etiket_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e548-74df-7378-a4a6-8d0dfc49ef8a" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5e0-fb54-73be-a036-9c2fefcf9552\",\n \"name\": \"Çok öncelikli\",\n \"group\": \"Müşteri Segmenti\",\n \"color\": \"#2563EB\",\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-10-04T10:44:12.902617Z\"\n }\n}" }, { "name": "Etiket bulunamadı", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Çok öncelikli\",\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/tags/{{etiket_id}}", "host": ["{{base_url}}"], "path": ["v1", "tags", "{{etiket_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5bf-cad5-71ed-879d-07b431f9bea6" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Etiket bulunamadı\"\n}" } ] } ] }, { "name": "Ölçü birimleri", "item": [ { "name": "Ölçü birimi listesi", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units", "host": ["{{base_url}}"], "path": ["v1", "units"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız.", "disabled": true }, { "key": "page_size", "value": "25", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-created_at", "description": "Sıralama (tek alan): `created_at` artan, `-created_at` azalan. Varsayılan `-created_at`.", "disabled": true }, { "key": "filter[created_at][gte]", "value": "2026-01-01T00:00:00Z", "description": "`created_at` alanı için büyük ya da eşit süzgeci (`gte`). RFC3339 zaman damgası (saniye altı hassasiyet kabul edilir). Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[created_at][lte]", "value": "2026-12-31T23:59:59Z", "description": "`created_at` alanı için küçük ya da eşit süzgeci (`lte`). RFC3339 zaman damgası (saniye altı hassasiyet kabul edilir). Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[created_at][gt]", "value": "2026-01-01T00:00:00Z", "description": "`created_at` alanı için büyüktür süzgeci (`gt`). RFC3339 zaman damgası (saniye altı hassasiyet kabul edilir). Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[created_at][lt]", "value": "2026-12-31T23:59:59Z", "description": "`created_at` alanı için küçüktür süzgeci (`lt`). RFC3339 zaman damgası (saniye altı hassasiyet kabul edilir). Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true } ] }, "description": "Kalem satırlarının birim tanımlarını listeler. `iso_code` UBL belgesine yazılan koddur; kendi birim tablonuzu bununla eşleyebilirsiniz. Ürün ve fatura kaleminde `unit` olarak bu listedeki `code` ya da sabit birim kodları (`ADET`, `KG` ...) kullanılır.\n\n**Gerekli kapsam:** `Sistem.FirmaBilgileriIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `filter[created_at][gte]`, `filter[created_at][lte]`, `filter[created_at][gt]`, `filter[created_at][lt]`.\n\n**Notlar:**\n- `birim_id` boşsa listenin ilk satırıyla dolar." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: birim_id boşsa listenin ilk satırından doldurulur.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " if (satirlar.length > 0 && !pm.environment.get('birim_id')) {", " pm.environment.set('birim_id', satirlar[0].id);", " console.log('birim_id listenin ilk satırından dolduruldu.');", " }", "}" ] } } ], "response": [ { "name": "Birim sayfası", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units", "host": ["{{base_url}}"], "path": ["v1", "units"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e58a-3bee-7772-9ad8-8537f4788150" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e557-46b0-7348-aeb1-f3c3b301595d\",\n \"code\": \"ADET\",\n \"name\": \"Adet\",\n \"iso_code\": \"C62\",\n \"sort_order\": 1,\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Anahtarın kapsamı yok", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units", "host": ["{{base_url}}"], "path": ["v1", "units"] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e551-99c8-7cb4-988c-4946d61a289f" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"forbidden\",\n \"message\": \"Bu işlem için yetkiniz yok\"\n}" } ] }, { "name": "Ölçü birimi detayı", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units/{{birim_id}}", "host": ["{{base_url}}"], "path": ["v1", "units", "{{birim_id}}"] }, "description": "`birim_id` değişkenindeki birim tanımını okur. Sözleşmede sayfalanan her kaynağın tekil okuması vardır; elinizdeki id'yi doğrulamak için sayfaları taramanız gerekmez.\n\n**Gerekli kapsam:** `Sistem.FirmaBilgileriIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{birim_id}}`: Ölçü biriminin id'si. Boşsa önce \"Ölçü birimi listesi\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın." }, "response": [ { "name": "Birim", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units/{{birim_id}}", "host": ["{{base_url}}"], "path": ["v1", "units", "{{birim_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e537-cde5-7d4c-b594-0c87c0138bee" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e557-46b0-7348-aeb1-f3c3b301595d\",\n \"code\": \"ADET\",\n \"name\": \"Adet\",\n \"iso_code\": \"C62\",\n \"sort_order\": 1,\n \"status\": \"active\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n}" }, { "name": "Birim bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/units/{{birim_id}}", "host": ["{{base_url}}"], "path": ["v1", "units", "{{birim_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e557-2ecc-73dd-b632-5708fcbee739" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Birim bulunamadı\"\n}" } ] } ] } ] }, { "name": "4. Giden faturalar", "description": "Taslak oluşturma ve güncelleme gönderim yapmaz; liste, arama ve indirme salt okumadır. **\"Faturayı gönderime al\" ve \"Gönderilmiş faturayı iptal et\" istekleri ÜRETİMDE GERÇEK e-belge işlemidir** (kontör harcar, geri alınamaz). Bu klasörü Collection Runner ile toplu çalıştırmayın.", "item": [ { "name": "Faturalar ve taslaklar", "item": [ { "name": "Fatura taslağı oluştur", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 1,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] }, "description": "Yeni bir giden fatura **taslağı** yazar. **Bu uç GİB'e hiçbir şey göndermez**; gönderim ayrı ve açık bir adımdır (\"Faturayı gönderime al\"). Satır toplamları, KDV matrahı ve tevkifat sunucuda hesaplanır, gövdedeki toplamlar yok sayılır.\n\n**Gerekli kapsam:** `Fatura.SatisFaturasiDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Kalıcı taslak açar** (gönderim yapmaz). Dış API'de taslak silme ucu yoktur.\n\n**Kullanılan değişkenler (ortam):**\n- `{{cari_id}}`: Cari kartın id'si. Boşsa önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Örnekteki `issue_date` yalnız bir örnektir: **bugünün tarihini yazın** (`YYYY-AA-GG`). Tarih bugünden ileri olamaz (422 `invalid_state`), gönderimde ise bugünden 7 günden eskiyse `backdate_confirmed: true` gerekir.\n- Zorunlu alanlar: `document_type`, `invoice_type`, `scenario`, `issue_date`, `contact_id` ve `items` (her satırda `name`, `quantity`, `unit_price`, `vat_rate`). Örnek, `cari_id` değişkenindeki karta e-Arşiv satış faturası taslağı yazar; cari yoksa önce \"Cari kart oluştur\" isteğini çalıştırın. e-Arşiv gönderimi için kartta il ve ilçe dolu olmalıdır.\n- `vat_rate`: 0, 1, 8, 10, 18 ya da 20; 0 ise `exemption_code` gerekir (satışta 351). `currency` TRY değilse `exchange_rate` zorunludur (0'dan büyük, 1'den farklı). `unit`: `ADET`, `KG` gibi birim kodları (\"Ölçü birimleri\" klasörüne bakın); UBL kodunu (`C62`) sunucu kendisi yazar.\n- e-Fatura için `document_type: E_FATURA`, `scenario: TEMEL_FATURA` ya da `TICARI_FATURA` ve alıcının GİB posta kutusu etiketi `recipient_mailbox` (`urn:mail:...`) gerekir; etiketi \"GİB posta kutusu sorgusu\" isteğiyle bulun. İade tipleri bu uçta taslak olarak yazılır ama API'den gönderilemez.\n- Bu uç `Idempotency-Key` okumaz: aynı isteği yeniden göndermek ikinci bir kayıt oluşturur. Yeniden denemeden önce kaydı okuyup doğrulayın.\n- Başarılı yanıtta `fatura_id` ortam değişkeni yeni taslağın id değerine ayarlanır." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: oluşturulan kaydın id'si fatura_id değişkenine yazılır.", "if (pm.response.code === 201) {", " let veri = {};", " try {", " veri = pm.response.json().data;", " } catch (e) {", " veri = null;", " }", " if (veri && veri.id) {", " pm.environment.set('fatura_id', veri.id);", " console.log('fatura_id güncellendi: sonraki istekler bu kayda gider.');", " }", "}" ] } } ], "response": [ { "name": "Oluşturulan taslak", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 1,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5aa-cc19-7da6-be85-c377a30d2b72" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e584-4e68-7e5d-a018-5cdf6d924457\",\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"1200.00\",\n \"currency\": \"TRY\",\n \"status\": \"draft\",\n \"created_at\": \"2026-10-04T09:40:05.117204Z\",\n \"updated_at\": \"2026-10-04T09:40:05.117204Z\"\n }\n}" }, { "name": "Geçersiz KDV oranı", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 1,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e559-1784-738a-979c-4b84b30f4644" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"vat_rate sözleşmedeki KDV oranlarından biri olmalı\",\n \"details\": {\n \"field\": \"items[0].vat_rate\"\n }\n}" }, { "name": "Cari kart bulunamadı", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 1,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5ec-a694-72fc-a14d-2bf0fc2e28bc" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Cari kart bulunamadı\"\n}" }, { "name": "Fatura tarihi bugünden ileri", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 1,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e525-d32b-7380-b6e5-3cc6bde8728f" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"invalid_state\",\n \"message\": \"Fatura tarihi bugünden ileri olamaz\",\n \"details\": {\n \"field\": \"issue_date\"\n }\n}" } ] }, { "name": "Fatura detayı (gönderim durumunu izleyin)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"], "query": [ { "key": "include", "value": "contact", "description": "`contact` belgenin seçtiği cari kartı yanıtın içine ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true } ] }, "description": "Tek bir faturayı okur; taslak da bu uçtan okunur. **Gönderimin durumunu bu uçla izleyin:** `status` alanı `draft` → `sending` → `sent` (ya da `failed`) yolunu izler; e-Fatura `accepted` ya da `rejected` ile sonlanır. Ayrıntılı durum `status_detail` alanındadır. Arşivlenmiş belge de döner.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın (taslak ya da gönderilmiş) id'si. Boşsa önce \"Fatura taslağı oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `include`.\n\n**Notlar:**\n- `failed` ve `status_detail: HATA` gönderimin başarısız olduğunu söyler, nedeni yanıt taşımaz. Firmanın e-belge entegrasyonu tamamlanmamışsa `send` yine 202 döner ve belge arka planda `failed` olur.\n- Durum arka planda güncellenir (gönderim kuyruğu yaklaşık 10 saniyede bir taranır, GİB durumu yaklaşık dakikada bir eşitlenir). Aynı faturayı saniyede bir sormayın: ilk sorguyu birkaç saniye sonra atın, sonra 30 ila 60 saniye arayla sorun. Kota anahtar başına dakikada 120 istektir; çok sayıda bekleyen fatura için \"Fatura listesi\" isteğini `filter[status][eq]=sending` ile kullanın.\n- Okuma yanıtında fatura kalemleri yayımlanmaz." }, "response": [ { "name": "Gönderilmiş fatura", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e530-dd6a-7c92-9ce7-3228d006605e" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"sent\",\n \"status_detail\": \"GIBE_GONDERILDI\",\n \"payment_status\": \"not_due\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-04T08:31:17.664092Z\"\n }\n}" }, { "name": "Fatura bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e535-f287-7acc-ac0e-b632cff03e65" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Fatura bulunamadı\"\n}" } ] }, { "name": "Fatura taslağını güncelle", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 2,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ],\n \"notes\": [\n \"Ekim ayı danışmanlık bedeli\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"] }, "description": "Taslağı günceller. **Yöntem PATCH olsa da güncelleme tam değiştirmedir:** gövde \"Fatura taslağı oluştur\" ile aynı zorunlu alanları ister ve taslak bu gövdeyle baştan yazılır. Gönderilmeyen isteğe bağlı alan korunmaz, varsayılanına döner (`currency` TRY olur; `exchange_rate`, `recipient_mailbox`, `exemption_code` ve `notes` boşalır). `items` kısmi değil, yerine geçer. `issue_time` güncellemede yazılmaz.\n\n**Gerekli kapsam:** `Fatura.SatisFaturasiDuzenleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **Taslağı kalıcı olarak yeniden yazar.** Yalnız taslak güncellenir: gönderilmiş belge 409 `conflict` alır. Panelde irsaliyeden oluşturulmuş taslak bu uçtan güncellenemez (409).\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın (taslak ya da gönderilmiş) id'si. Boşsa önce \"Fatura taslağı oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n- `{{cari_id}}`: Cari kartın id'si. Boşsa önce \"Cari kart oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Örnekteki `issue_date` yalnız bir örnektir: **bugünün tarihini yazın** (`YYYY-AA-GG`). Tarih bugünden ileri olamaz (422 `invalid_state`), gönderimde ise bugünden 7 günden eskiyse `backdate_confirmed: true` gerekir.\n- `GET` yanıtı kalemleri taşımadığı için tam gövdeyi geri kurmaya yetmez: güvenli yol, taslağın tam gövdesini kendi kaydınızdan göndermektir." }, "response": [ { "name": "Güncellenmiş taslak", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 2,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ],\n \"notes\": [\n \"Ekim ayı danışmanlık bedeli\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e582-811b-7bac-b2e4-9b1f9123781f" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e584-4e68-7e5d-a018-5cdf6d924457\",\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"2400.00\",\n \"currency\": \"TRY\",\n \"status\": \"draft\",\n \"created_at\": \"2026-10-04T09:40:05.117204Z\",\n \"updated_at\": \"2026-10-04T10:05:51.384420Z\"\n }\n}" }, { "name": "Gönderilmiş belge güncellenemez", "originalRequest": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"issue_date\": \"2026-10-04\",\n \"currency\": \"TRY\",\n \"contact_id\": \"{{cari_id}}\",\n \"items\": [\n {\n \"name\": \"Danışmanlık hizmeti\",\n \"quantity\": 2,\n \"unit\": \"ADET\",\n \"unit_price\": 1000,\n \"vat_rate\": 20\n }\n ],\n \"notes\": [\n \"Ekim ayı danışmanlık bedeli\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e55a-8e84-7d01-8883-20792e454647" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Yalnız taslak güncellenebilir\"\n}" } ] } ] }, { "name": "Gönderim ve iptal", "description": "**DİKKAT: bu klasördeki istekler gerçek e-belge gönderir ya da iptal eder.** Tek tek ve bilerek çalıştırın.", "item": [ { "name": "Faturayı gönderime al (DİKKAT: gerçek e-belge gönderimi)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "gonderim-{{fatura_id}}", "description": "Aynı gönderim niyeti için sabit anahtar: tekrar gönderim ikinci bir belge üretmez (24 saat saklanır, en çok 255 karakter)." } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/send", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "send"] }, "description": "Taslağı gönderim kuyruğuna alır ve **202** döner. **202, belgenin GİB'e ulaştığı anlamına gelmez.** Uç taslağın gönderilebilir olduğunu doğrular (firma durumu, kesim izni, alıcı posta kutusu), kuyruğa alır ve döner; imzalama ve GİB'e iletim arka planda yürür. Sonuç için bildirim (webhook) gönderilmez: ilerlemeyi \"Fatura detayı\" isteğiyle `status` alanından izleyin (`draft` → `sending` → `sent` ya da `failed`).\n\n**Gerekli kapsam:** `EFatura.TaslaktanGonderimYapabilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** **ÜRETİMDE GERÇEK E-BELGE GÖNDERİMİDİR: kontör harcar ve geri alınamaz** (gönderilmiş belge yalnız iptal edilebilir). Deneme ortamı yoktur. Göndermeden önce `fatura_id` değişkeninin göndermek istediğiniz taslağı gösterdiğini doğrulayın; **Collection Runner ile tüm koleksiyonu çalıştırmayın.**\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın (taslak ya da gönderilmiş) id'si. Boşsa önce \"Fatura taslağı oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- **Idempotency-Key bu uçta okunur.** İstek, her gönderim niyeti için sabit bir anahtarla (`gonderim-{{fatura_id}}`) gelir: aynı anahtarla gelen ikinci istek saklanan 202 yanıtını döner ve GİB'e ikinci bir gönderim olmaz. Aynı anahtar farklı bir gövdeyle kullanılırsa 422 `idempotency_key_reuse` döner. Anahtar 24 saat saklanır; süre dolduktan sonra aynı anahtar yeni istek sayılır, bu yüzden yeniden denemeden önce faturanın durumunu okuyun.\n- Gövde boş nesnedir (`{}`). Fatura tarihi bugünden 7 günden fazla gerideyse `{\"backdate_confirmed\": true}` gerekir (VUK 231/5).\n- Firmanın e-belge entegrasyonu tamamlanmamışsa ya da bu ortama ait değilse uç yine 202 döner; belge arka planda `failed` olur. Anahtarsız ikinci istek, belgenin o anki durumuna göre 409 ya da yeniden kuyruğa alma (202) sonucu verir (ayrıntı: OpenAPI referansı, `sendInvoice`).\n- Hesap kapalıysa (firma pasif ya da deneme süresi dolmuş) 403 `forbidden`; ödeme gecikmişse (vade tarihinden 4 gün sonra) ya da kontör eşiği dolmuşsa 422 `invalid_state` döner. Gönderim öncesi kapılar (vergi dairesi, il ve ilçe, e-Belge Tanımları, gönderici etiketi, KDV 0 için `exemption_code`) 400 ya da 422 ile hemen bildirilir.\n- İade ve tevkifat tipleri, e-Arşiv'in YTB tipleri ve Yatırım Teşvik senaryosu bu uçtan gönderilemez.\n- e-Fatura alıcısının kartı GİB dizininde doğrulanmamışsa sunucu VKN/TCKN'yi gönderimden önce dizine sorar: bulunursa kart doğrulanır ve gönderim sürer, bulunmazsa 422 `invalid_state`. Sorgu kart başına bir kez yapılır ve 1 VKN sorgu kontörü düşer (iş ortağınızdan; yoksa firmanızdan). `recipient_mailbox` bu sorgunun yerini tutmaz.\n\n**Örnek yanıtlar hakkında:**\n- `202` Gönderim kuyruğuna alındı: 202 yalnız kuyruğa alındığını söyler; belgenin GİB'e ulaştığını söylemez. Durumu \"Fatura detayı\" ile izleyin." }, "response": [ { "name": "Gönderim kuyruğuna alındı", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "gonderim-{{fatura_id}}", "description": "Aynı gönderim niyeti için sabit anahtar: tekrar gönderim ikinci bir belge üretmez (24 saat saklanır, en çok 255 karakter)." } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/send", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "send"] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e50f-7611-79e8-9ea3-01f675a4e482" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"invoice_id\": \"0191e584-4e68-7e5d-a018-5cdf6d924457\"\n }\n}" }, { "name": "Hesap belge kesmeye kapalı", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "gonderim-{{fatura_id}}", "description": "Aynı gönderim niyeti için sabit anahtar: tekrar gönderim ikinci bir belge üretmez (24 saat saklanır, en çok 255 karakter)." } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/send", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "send"] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e509-feb8-706f-a0be-8bee9447760c" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"forbidden\",\n \"message\": \"Bu işlem için yetkiniz yok\"\n}" }, { "name": "Belge zaten gönderilmiş", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "gonderim-{{fatura_id}}", "description": "Aynı gönderim niyeti için sabit anahtar: tekrar gönderim ikinci bir belge üretmez (24 saat saklanır, en çok 255 karakter)." } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/send", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "send"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5cd-02c6-7a99-93c6-80a7a667d332" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"conflict\",\n \"message\": \"Belge zaten gönderilmiş\"\n}" }, { "name": "Gönderim kapısı: fatura tarihi çok eski", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "gonderim-{{fatura_id}}", "description": "Aynı gönderim niyeti için sabit anahtar: tekrar gönderim ikinci bir belge üretmez (24 saat saklanır, en çok 255 karakter)." } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/send", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "send"] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5bd-b6d2-77fb-a732-61743aa42b87" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"invalid_state\",\n \"message\": \"Fatura tarihi bugünden 7 günden eski: gönderim için backdate_confirmed: true gerekir\",\n \"details\": {\n \"field\": \"issue_date\"\n }\n}" } ] }, { "name": "Gönderilmiş faturayı iptal et (DİKKAT: geri alınamaz)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"objection_type\": \"GIB\",\n \"reason\": \"Hatalı tutar girişi, fatura iptal ediliyor\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/cancel", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "cancel"] }, "description": "Gönderilmiş bir faturayı iptal eder. GİB'e ulaşmış e-Arşiv faturası e-belge servisinde iptal edilir ve iptal GİB'e iptal raporuyla bildirilir; kayıt yalnız bu işlem başarılıysa iptal olur. e-Fatura için bu uç GİB'e talep göndermez: kayıt, dış kanalda yapılmış itiraz ya da iptalin kaydıdır (`objection_type`).\n\n**Gerekli kapsam:** `EFatura.IptalEdebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır. Bu kapsam varsayılan kümededir; anahtar panelde üretilirken \"Fatura iptaline izin ver\" kutusu kaldırıldıysa anahtar onu taşımaz ve yeni anahtar gerekir.\n\n**Yan etki:** **ÜRETİMDE GERÇEK İPTALDİR ve geri alınamaz.** Taslak bu uçtan iptal edilmez. Zaten iptal edilmiş, yeniden düzenlenmiş ya da gönderimi süren belge 409 `conflict` alır.\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın (taslak ya da gönderilmiş) id'si. Boşsa önce \"Fatura taslağı oluştur\" isteğini çalıştırın (id kendiliğinden dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- `objection_type` ve `reason` zorunludur. GİB'e ulaşmış e-Arşiv faturasında yalnız `GIB` kabul edilir; diğer değerler 400 alır ve e-belge servisine iptal gönderilmez. e-Fatura ve GİB'e ulaşmamış e-Arşiv için `GIB`, `KEP`, `NOTER` ve `TAAHHUTLU_MEKTUP` değerlerinin tamamı geçerlidir.\n- `cancel_date` verilmezse bugündür; GİB'e ulaşmış e-Arşiv için yalnız bugün kabul edilir. e-Arşiv iptali belgenin GİB'e iletildiği günden itibaren **8 gün** içinde (son gün dahil) yapılabilir, sonrası 422 `invalid_state`; geriye tarihli belgede süre belge tarihinden değil iletim gününden işler.\n- e-belge servisi hata verirse yanıt 500 `internal_error` olur ve fatura değişmemiştir; istek tekrarlanabilir." }, "response": [ { "name": "İptal edilmiş fatura", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"objection_type\": \"GIB\",\n \"reason\": \"Hatalı tutar girişi, fatura iptal ediliyor\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/cancel", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "cancel"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5ce-dda0-716f-a30f-1a6d599820dc" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"cancelled\",\n \"status_detail\": \"IPTAL_EDILDI\",\n \"payment_status\": \"not_due\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-04T11:02:19.540873Z\"\n }\n}" }, { "name": "İptal süresi geçmiş", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"objection_type\": \"GIB\",\n \"reason\": \"Hatalı tutar girişi, fatura iptal ediliyor\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/cancel", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "cancel"] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5de-76b2-7377-b19e-ebdd62c967ca" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"invalid_state\",\n \"message\": \"İptal süresi doldu: belge, alıcıya iletildiği günden itibaren 8 gün içinde iptal edilebilir\"\n}" } ] } ] }, { "name": "Liste ve arama", "description": "Giden fatura listesi ve fatura numarası, ETTN ya da zarf kimliğiyle arama. Bu klasördeki isteklerin hepsi salt okumadır.", "item": [ { "name": "Fatura listesi", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: arama örnekleri için fatura_no, ettn ve zarf_id boşsa ilk dolu satırdan yazılır. fatura_id'ye dokunulmaz: gönderim ve iptal istekleri onu kullanır.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " const alanlar = [['fatura_no', 'invoice_no'], ['ettn', 'uuid'], ['zarf_id', 'envelope_id']];", " alanlar.forEach(function (eslesme) {", " const satir = satirlar.find(function (s) { return s[eslesme[1]]; });", " if (satir && !pm.environment.get(eslesme[0])) {", " pm.environment.set(eslesme[0], satir[eslesme[1]]);", " console.log(eslesme[0] + ' listenin ilk dolu satırından dolduruldu.');", " }", " });", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "include", "value": "contact", "description": "`contact` her satıra belgenin seçtiği cari kartı ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 30 gün öncesini verin (kayan pencere).", "disabled": true }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`.", "disabled": true }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `draft`, `sending`, `sent`, `accepted`, `rejected`, `failed`, `cancelled`. `draft` yalnız taslakları döndürür. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`): `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "YSF2026000000012", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil.", "disabled": true }, { "key": "filter[uuid][eq]", "value": "0191e541-1685-7953-a18b-075029fefd2c", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın.", "disabled": true }, { "key": "filter[envelope_id][eq]", "value": "0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70", "description": "Zarf kimliği (e-Faturanın alıcıya gönderildiği zarfın ETTN değeri) ile tam eşleşme (yalnız `eq`). Yalnız e-Fatura satırlarında doludur.", "disabled": true } ] }, "description": "Giden faturaları (taslaklar dahil) belge tarihine göre, en yeni önce listeler. Süzgeçlerin hepsi Params sekmesinde işaretsiz durur.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `include`, `filter[issue_date][gte]`, `filter[issue_date][lte]`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[invoice_no][eq]`, `filter[uuid][eq]`, `filter[envelope_id][eq]`.\n\n**Notlar:**\n- Taslak ve gönderilmiş faturalar tek listededir; taslak `status: draft` taşır. Liste yalnız şu belge tiplerini kapsar: `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Arşivlenen belge listeden düşer, ama `GET /v1/invoices/{id}` onu da okur.\n- Kendi kaydınızla eşitlemek için her turda son 30 günü (`filter[issue_date][gte]`) baştan sona okuyun: durum belge tarihinden sonra da değişir (ticari yanıt belge tarihinden sonraki 7 gün, e-Arşiv iptali GİB'e iletim gününden itibaren 8 gün). Dönemi kapatmadan önce o dönemin tamamını bir kez daha okuyun.\n- Liste genel kotadan sayılır (anahtar başına dakikada 120, firma toplamı dakikada 300). Sayfa başına 100 satır isteyin." }, "response": [ { "name": "Fatura sayfası", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices", "host": ["{{base_url}}"], "path": ["v1", "invoices"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"envelope_id\": \"0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"payment_status\": \"not_due\",\n \"paid_amount\": \"0.00\",\n \"remaining_amount\": \"3600.00\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-05T10:02:44.120391Z\"\n },\n {\n \"id\": \"0191e5f1-2c40-7a11-8f0e-6d2b9c4e7a13\",\n \"document_type\": \"E_ARSIV\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"EARSIV_FATURA\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-03\",\n \"total\": \"1200.00\",\n \"currency\": \"TRY\",\n \"status\": \"draft\",\n \"created_at\": \"2026-10-03T14:05:51.902114Z\",\n \"updated_at\": \"2026-10-03T14:05:51.902114Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Eski sözleşmenin süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[created_at][gte]=2026-10-01T00:00:00Z", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[created_at][gte]", "value": "2026-10-01T00:00:00Z" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"bu kaynak için süzülemeyen alan: created_at\",\n \"details\": {\n \"field\": \"filter[created_at][gte]\"\n }\n}" } ] }, { "name": "Tarih aralığıyla fatura listesi", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: arama örnekleri için fatura_no, ettn ve zarf_id boşsa ilk dolu satırdan yazılır. fatura_id'ye dokunulmaz: gönderim ve iptal istekleri onu kullanır.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " const alanlar = [['fatura_no', 'invoice_no'], ['ettn', 'uuid'], ['zarf_id', 'envelope_id']];", " alanlar.forEach(function (eslesme) {", " const satir = satirlar.find(function (s) { return s[eslesme[1]]; });", " if (satir && !pm.environment.get(eslesme[0])) {", " pm.environment.set(eslesme[0], satir[eslesme[1]]);", " console.log(eslesme[0] + ' listenin ilk dolu satırından dolduruldu.');", " }", " });", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[issue_date][gte]=2026-10-01&filter[issue_date][lte]=2026-10-31", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "include", "value": "contact", "description": "`contact` her satıra belgenin seçtiği cari kartı ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 30 gün öncesini verin (kayan pencere)." }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`." }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `draft`, `sending`, `sent`, `accepted`, `rejected`, `failed`, `cancelled`. `draft` yalnız taslakları döndürür. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`): `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "YSF2026000000012", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil.", "disabled": true }, { "key": "filter[uuid][eq]", "value": "0191e541-1685-7953-a18b-075029fefd2c", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın.", "disabled": true }, { "key": "filter[envelope_id][eq]", "value": "0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70", "description": "Zarf kimliği (e-Faturanın alıcıya gönderildiği zarfın ETTN değeri) ile tam eşleşme (yalnız `eq`). Yalnız e-Fatura satırlarında doludur.", "disabled": true } ] }, "description": "Belge tarihi verilen aralıktaki giden faturaları listeler (`filter[issue_date][gte]` ve `[lte]` açık). Aralığı kendi tarihlerinizle değiştirin.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `include`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[invoice_no][eq]`, `filter[uuid][eq]`, `filter[envelope_id][eq]`.\n\n**Notlar:**\n- Taslak ve gönderilmiş faturalar tek listededir; taslak `status: draft` taşır. Liste yalnız şu belge tiplerini kapsar: `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Arşivlenen belge listeden düşer, ama `GET /v1/invoices/{id}` onu da okur.\n- Kendi kaydınızla eşitlemek için her turda son 30 günü (`filter[issue_date][gte]`) baştan sona okuyun: durum belge tarihinden sonra da değişir (ticari yanıt belge tarihinden sonraki 7 gün, e-Arşiv iptali GİB'e iletim gününden itibaren 8 gün). Dönemi kapatmadan önce o dönemin tamamını bir kez daha okuyun.\n- Liste genel kotadan sayılır (anahtar başına dakikada 120, firma toplamı dakikada 300). Sayfa başına 100 satır isteyin." }, "response": [ { "name": "Ekim faturaları", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[issue_date][gte]=2026-10-01&filter[issue_date][lte]=2026-10-31", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[issue_date][gte]", "value": "2026-10-01" }, { "key": "filter[issue_date][lte]", "value": "2026-10-31" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"envelope_id\": \"0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"payment_status\": \"not_due\",\n \"paid_amount\": \"0.00\",\n \"remaining_amount\": \"3600.00\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-05T10:02:44.120391Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Eski sözleşmenin süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[created_at][gte]=2026-10-01T00:00:00Z", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[created_at][gte]", "value": "2026-10-01T00:00:00Z" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"bu kaynak için süzülemeyen alan: created_at\",\n \"details\": {\n \"field\": \"filter[created_at][gte]\"\n }\n}" } ] }, { "name": "Fatura numarasıyla bul", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: arama örnekleri için fatura_no, ettn ve zarf_id boşsa ilk dolu satırdan yazılır. fatura_id'ye dokunulmaz: gönderim ve iptal istekleri onu kullanır.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " const alanlar = [['fatura_no', 'invoice_no'], ['ettn', 'uuid'], ['zarf_id', 'envelope_id']];", " alanlar.forEach(function (eslesme) {", " const satir = satirlar.find(function (s) { return s[eslesme[1]]; });", " if (satir && !pm.environment.get(eslesme[0])) {", " pm.environment.set(eslesme[0], satir[eslesme[1]]);", " console.log(eslesme[0] + ' listenin ilk dolu satırından dolduruldu.');", " }", " });", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[invoice_no][eq]={{fatura_no}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "include", "value": "contact", "description": "`contact` her satıra belgenin seçtiği cari kartı ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 30 gün öncesini verin (kayan pencere).", "disabled": true }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`.", "disabled": true }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `draft`, `sending`, `sent`, `accepted`, `rejected`, `failed`, `cancelled`. `draft` yalnız taslakları döndürür. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`): `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "{{fatura_no}}", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil." }, { "key": "filter[uuid][eq]", "value": "0191e541-1685-7953-a18b-075029fefd2c", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın.", "disabled": true }, { "key": "filter[envelope_id][eq]", "value": "0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70", "description": "Zarf kimliği (e-Faturanın alıcıya gönderildiği zarfın ETTN değeri) ile tam eşleşme (yalnız `eq`). Yalnız e-Fatura satırlarında doludur.", "disabled": true } ] }, "description": "Fatura numarasıyla faturayı bulur (`filter[invoice_no][eq]`). Tam eşleşmedir; bulunamazsa liste boş döner. Genellikle tek satır döner ama aynı numara farklı belge tiplerinde bulunabilir: `document_type` alanına da bakın.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_no}}`: Aranan fatura numarası. Boşsa önce \"Fatura listesi\" isteğini çalıştırın (ilk dolu satırdan dolar) ya da ortamda elle yazın.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `include`, `filter[issue_date][gte]`, `filter[issue_date][lte]`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[uuid][eq]`, `filter[envelope_id][eq]`.\n\n**Notlar:**\n- Taslak ve gönderilmiş faturalar tek listededir; taslak `status: draft` taşır. Liste yalnız şu belge tiplerini kapsar: `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Arşivlenen belge listeden düşer, ama `GET /v1/invoices/{id}` onu da okur.\n- Kendi kaydınızla eşitlemek için her turda son 30 günü (`filter[issue_date][gte]`) baştan sona okuyun: durum belge tarihinden sonra da değişir (ticari yanıt belge tarihinden sonraki 7 gün, e-Arşiv iptali GİB'e iletim gününden itibaren 8 gün). Dönemi kapatmadan önce o dönemin tamamını bir kez daha okuyun.\n- Liste genel kotadan sayılır (anahtar başına dakikada 120, firma toplamı dakikada 300). Sayfa başına 100 satır isteyin." }, "response": [ { "name": "Numarayla bulunan fatura", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[invoice_no][eq]={{fatura_no}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[invoice_no][eq]", "value": "{{fatura_no}}" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"envelope_id\": \"0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"payment_status\": \"not_due\",\n \"paid_amount\": \"0.00\",\n \"remaining_amount\": \"3600.00\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-05T10:02:44.120391Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Eski sözleşmenin süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[created_at][gte]=2026-10-01T00:00:00Z", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[created_at][gte]", "value": "2026-10-01T00:00:00Z" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"bu kaynak için süzülemeyen alan: created_at\",\n \"details\": {\n \"field\": \"filter[created_at][gte]\"\n }\n}" } ] }, { "name": "ETTN ile bul", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: arama örnekleri için fatura_no, ettn ve zarf_id boşsa ilk dolu satırdan yazılır. fatura_id'ye dokunulmaz: gönderim ve iptal istekleri onu kullanır.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " const alanlar = [['fatura_no', 'invoice_no'], ['ettn', 'uuid'], ['zarf_id', 'envelope_id']];", " alanlar.forEach(function (eslesme) {", " const satir = satirlar.find(function (s) { return s[eslesme[1]]; });", " if (satir && !pm.environment.get(eslesme[0])) {", " pm.environment.set(eslesme[0], satir[eslesme[1]]);", " console.log(eslesme[0] + ' listenin ilk dolu satırından dolduruldu.');", " }", " });", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[uuid][eq]={{ettn}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "include", "value": "contact", "description": "`contact` her satıra belgenin seçtiği cari kartı ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 30 gün öncesini verin (kayan pencere).", "disabled": true }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`.", "disabled": true }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `draft`, `sending`, `sent`, `accepted`, `rejected`, `failed`, `cancelled`. `draft` yalnız taslakları döndürür. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`): `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "YSF2026000000012", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil.", "disabled": true }, { "key": "filter[uuid][eq]", "value": "{{ettn}}", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın." }, { "key": "filter[envelope_id][eq]", "value": "0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70", "description": "Zarf kimliği (e-Faturanın alıcıya gönderildiği zarfın ETTN değeri) ile tam eşleşme (yalnız `eq`). Yalnız e-Fatura satırlarında doludur.", "disabled": true } ] }, "description": "ETTN (belgenin GİB tekil kimliği) ile tek faturayı bulur (`filter[uuid][eq]`). Tam eşleşmedir; bulunamazsa liste boş döner.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{ettn}}`: Aranan ETTN. Boşsa önce \"Fatura listesi\" isteğini çalıştırın (ilk dolu satırdan dolar) ya da ortamda elle yazın.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `include`, `filter[issue_date][gte]`, `filter[issue_date][lte]`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[invoice_no][eq]`, `filter[envelope_id][eq]`.\n\n**Notlar:**\n- Taslak ve gönderilmiş faturalar tek listededir; taslak `status: draft` taşır. Liste yalnız şu belge tiplerini kapsar: `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Arşivlenen belge listeden düşer, ama `GET /v1/invoices/{id}` onu da okur.\n- Kendi kaydınızla eşitlemek için her turda son 30 günü (`filter[issue_date][gte]`) baştan sona okuyun: durum belge tarihinden sonra da değişir (ticari yanıt belge tarihinden sonraki 7 gün, e-Arşiv iptali GİB'e iletim gününden itibaren 8 gün). Dönemi kapatmadan önce o dönemin tamamını bir kez daha okuyun.\n- Liste genel kotadan sayılır (anahtar başına dakikada 120, firma toplamı dakikada 300). Sayfa başına 100 satır isteyin." }, "response": [ { "name": "ETTN ile bulunan fatura", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[uuid][eq]={{ettn}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[uuid][eq]", "value": "{{ettn}}" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"envelope_id\": \"0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"payment_status\": \"not_due\",\n \"paid_amount\": \"0.00\",\n \"remaining_amount\": \"3600.00\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-05T10:02:44.120391Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Eski sözleşmenin süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[created_at][gte]=2026-10-01T00:00:00Z", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[created_at][gte]", "value": "2026-10-01T00:00:00Z" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"bu kaynak için süzülemeyen alan: created_at\",\n \"details\": {\n \"field\": \"filter[created_at][gte]\"\n }\n}" } ] }, { "name": "Zarf kimliğiyle bul", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: arama örnekleri için fatura_no, ettn ve zarf_id boşsa ilk dolu satırdan yazılır. fatura_id'ye dokunulmaz: gönderim ve iptal istekleri onu kullanır.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " const alanlar = [['fatura_no', 'invoice_no'], ['ettn', 'uuid'], ['zarf_id', 'envelope_id']];", " alanlar.forEach(function (eslesme) {", " const satir = satirlar.find(function (s) { return s[eslesme[1]]; });", " if (satir && !pm.environment.get(eslesme[0])) {", " pm.environment.set(eslesme[0], satir[eslesme[1]]);", " console.log(eslesme[0] + ' listenin ilk dolu satırından dolduruldu.');", " }", " });", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[envelope_id][eq]={{zarf_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "include", "value": "contact", "description": "`contact` her satıra belgenin seçtiği cari kartı ekler. Ek kapsam ister: `Kart.MusteriTedarikciIzleyebilir` (yoksa 403). Seçim çözülemezse alan gelmez.", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 30 gün öncesini verin (kayan pencere).", "disabled": true }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`.", "disabled": true }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `draft`, `sending`, `sent`, `accepted`, `rejected`, `failed`, `cancelled`. `draft` yalnız taslakları döndürür. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`): `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Sözlük dışı değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "YSF2026000000012", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil.", "disabled": true }, { "key": "filter[uuid][eq]", "value": "0191e541-1685-7953-a18b-075029fefd2c", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın.", "disabled": true }, { "key": "filter[envelope_id][eq]", "value": "{{zarf_id}}", "description": "Zarf kimliği (e-Faturanın alıcıya gönderildiği zarfın ETTN değeri) ile tam eşleşme (yalnız `eq`). Yalnız e-Fatura satırlarında doludur." } ] }, "description": "Zarf kimliğiyle (`filter[envelope_id][eq]`) faturayı bulur. Zarf kimliği yalnız e-Fatura'da, belge alıcıya zarflanınca dolar ve e-belge servisinin bildirdiği değerdir.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{zarf_id}}`: Aranan zarf kimliği. Boşsa önce \"Fatura listesi\" isteğini çalıştırın (ilk dolu satırdan dolar) ya da ortamda elle yazın.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `include`, `filter[issue_date][gte]`, `filter[issue_date][lte]`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[invoice_no][eq]`, `filter[uuid][eq]`.\n\n**Notlar:**\n- Taslak ve gönderilmiş faturalar tek listededir; taslak `status: draft` taşır. Liste yalnız şu belge tiplerini kapsar: `E_FATURA`, `E_ARSIV`, `E_IHRACAT`, `E_ILAC_TIBBI`, `E_KAMU`, `E_SGK`, `PROFORMA`, `IADE`. Arşivlenen belge listeden düşer, ama `GET /v1/invoices/{id}` onu da okur.\n- Kendi kaydınızla eşitlemek için her turda son 30 günü (`filter[issue_date][gte]`) baştan sona okuyun: durum belge tarihinden sonra da değişir (ticari yanıt belge tarihinden sonraki 7 gün, e-Arşiv iptali GİB'e iletim gününden itibaren 8 gün). Dönemi kapatmadan önce o dönemin tamamını bir kez daha okuyun.\n- Liste genel kotadan sayılır (anahtar başına dakikada 120, firma toplamı dakikada 300). Sayfa başına 100 satır isteyin." }, "response": [ { "name": "Zarfla bulunan fatura", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[envelope_id][eq]={{zarf_id}}", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[envelope_id][eq]", "value": "{{zarf_id}}" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5e4-9e91-71fe-9383-b05f57bc41a2\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"YSF2026000000012\",\n \"uuid\": \"0191e541-1685-7953-a18b-075029fefd2c\",\n \"envelope_id\": \"0191e5c2-7b10-7d4e-9a51-2f6e8c1d3b70\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-04\",\n \"total\": \"3600.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"payment_status\": \"not_due\",\n \"paid_amount\": \"0.00\",\n \"remaining_amount\": \"3600.00\",\n \"created_at\": \"2026-10-04T08:31:17.664092Z\",\n \"updated_at\": \"2026-10-05T10:02:44.120391Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Eski sözleşmenin süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices?filter[created_at][gte]=2026-10-01T00:00:00Z", "host": ["{{base_url}}"], "path": ["v1", "invoices"], "query": [ { "key": "filter[created_at][gte]", "value": "2026-10-01T00:00:00Z" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"bu kaynak için süzülemeyen alan: created_at\",\n \"details\": {\n \"field\": \"filter[created_at][gte]\"\n }\n}" } ] } ] }, { "name": "İndirme", "description": "Gönderilmiş giden faturanın UBL XML'i ve PDF'i. Yanıt dosyadır: Postman'de Send and Download ile kaydedin. Bu klasördeki isteklerin hepsi salt okumadır.", "item": [ { "name": "Fatura XML'ini indir", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "xml"] }, "description": "Gönderilmiş faturanın UBL XML'ini e-belge servisindeki imzalı hâliyle indirir. e-Arşiv belgesi de bu uçtan indirilir. Simülasyon ortamında kesilen belgenin XML'i imzasızdır ve yerelde üretilir.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın id'si. Taslağı değil, gönderilmiş bir faturayı gösterin: \"Fatura taslağı oluştur\" yeni taslağı yazar ve taslak indirilemez (422). Gönderilmiş faturanın id'sini \"Fatura listesi\" yanıtından alıp ortamda elle yazın.\n\n**Notlar:**\n- Yanıt dosyanın kendisidir. Postman'de **Send and Download** ile kaydedin; XML'i saklarken yeniden biçimlendirmeyin, imza bozulur.\n- Taslak, henüz e-belge servisine ulaşmamış belge, elle kaydedilmiş gelen belge ve e-belge entegrasyonu tamamlanmamış firma 422 `invalid_state` alır.\n- e-belge servisi hata verirse 500 `internal_error` döner; indirme yeniden denenebilir.\n- İndirme uçlarının ayrı kotası vardır (anahtar başına dakikada 60, firma toplamı dakikada 120) ve firma başına aynı anda en çok 4 indirme yapılır; fazlası 429 alır." }, "response": [ { "name": "Dosya", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "xml"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "xml", "header": [ { "key": "Content-Type", "value": "application/xml; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" }, { "key": "Content-Disposition", "value": "attachment; filename=\"YSF2026000000012.xml\"" } ], "cookie": [], "body": "\n\n \n ...\n" }, { "name": "Taslak indirilemez", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "xml"] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" } ], "cookie": [], "body": "{\n \"error\": \"invalid_state\",\n \"message\": \"Fatura henüz gönderilmemiş bir taslak; indirmeden önce gönderin\"\n}" } ] }, { "name": "Fatura PDF'ini indir", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "pdf"] }, "description": "Gönderilmiş faturanın PDF görüntüsünü indirir. e-Arşiv belgesi de bu uçtan indirilir.\n\n**Gerekli kapsam:** `EFatura.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{fatura_id}}`: Faturanın id'si. Taslağı değil, gönderilmiş bir faturayı gösterin: \"Fatura taslağı oluştur\" yeni taslağı yazar ve taslak indirilemez (422). Gönderilmiş faturanın id'sini \"Fatura listesi\" yanıtından alıp ortamda elle yazın.\n\n**Notlar:**\n- Yanıt dosyanın kendisidir. Postman'de **Send and Download** ile kaydedin.\n- Taslak, henüz e-belge servisine ulaşmamış belge, elle kaydedilmiş gelen belge ve e-belge entegrasyonu tamamlanmamış firma 422 `invalid_state` alır.\n- e-belge servisi hata verirse 500 `internal_error` döner; indirme yeniden denenebilir.\n- İndirme uçlarının ayrı kotası vardır (anahtar başına dakikada 60, firma toplamı dakikada 120) ve firma başına aynı anda en çok 4 indirme yapılır; fazlası 429 alır." }, "response": [ { "name": "Dosya", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "pdf"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "text", "header": [ { "key": "Content-Type", "value": "application/pdf" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" }, { "key": "Content-Disposition", "value": "attachment; filename=\"YSF2026000000012.pdf\"" } ], "cookie": [], "body": "%PDF-1.7\n(ikili PDF içeriği: Postman'de Send yerine Send and Download ile dosyaya kaydedin)" }, { "name": "Belge bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/invoices/{{fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "invoices", "{{fatura_id}}", "pdf"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Fatura bulunamadı\"\n}" } ] } ] } ] }, { "name": "5. Gelen faturalar", "description": "Karşı tarafın firmaya gönderdiği faturalar: liste, tek belge, XML ve PDF. Taslak aşaması yoktur. Alımında hata oluşmuş belge listede görünmez ve tek okuması 404 döner. e-İrsaliye bu klasörde değildir. Bu klasördeki isteklerin hepsi salt okumadır.", "item": [ { "name": "Gelen fatura listesi", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Zincirleme: gelen_fatura_id boşsa listenin ilk satırından doldurulur.", "if (pm.response.code === 200) {", " let satirlar = [];", " try {", " satirlar = pm.response.json().data || [];", " } catch (e) {", " satirlar = [];", " }", " if (satirlar.length > 0 && !pm.environment.get('gelen_fatura_id')) {", " pm.environment.set('gelen_fatura_id', satirlar[0].id);", " console.log('gelen_fatura_id listenin ilk satırından dolduruldu.');", " }", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız. Sayfalar arasında süzgeci ve sıralamayı değiştirmeyin.", "disabled": true }, { "key": "page_size", "value": "100", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-issue_date", "description": "Sıralama: `issue_date` artan, `-issue_date` azalan (belge tarihi, en yeni önce). Varsayılan `-issue_date`. `created_at` ile sıralama yoktur (400).", "disabled": true }, { "key": "filter[issue_date][gte]", "value": "2026-10-01", "description": "Belge tarihi bu günden büyük ya da eşit (`gte`). Yalnız gün: `YYYY-MM-DD`; saat taşıyan değer 400 alır. Kendi kaydınızla eşitlerken bugünden 45 gün öncesini verin (kayan pencere; geç ulaşan belge eski bir tarihe düşer).", "disabled": true }, { "key": "filter[issue_date][lte]", "value": "2026-10-31", "description": "Belge tarihi bu günden küçük ya da eşit (`lte`); o günü de kapsar. Yalnız gün: `YYYY-MM-DD`.", "disabled": true }, { "key": "filter[status][eq]", "value": "accepted", "description": "Durum süzgeci (yalnız `eq`). Değerler: `sent`, `accepted`, `rejected`, `cancelled`. Alımında hata oluşmuş belge listede görünmediği için `failed` yoktur (400).", "disabled": true }, { "key": "filter[document_type][eq]", "value": "E_FATURA", "description": "Belge tipi süzgeci (yalnız `eq`). Tek değer `E_FATURA`; e-İrsaliye bu listede yoktur. Başka değer 400 alır.", "disabled": true }, { "key": "filter[invoice_no][eq]", "value": "YSF2026000000012", "description": "Fatura numarasıyla tam eşleşme (yalnız `eq`, parça arama yok), en çok 32 karakter. Bulunamazsa liste boş döner, 404 değil.", "disabled": true }, { "key": "filter[uuid][eq]", "value": "0191e541-1685-7953-a18b-075029fefd2c", "description": "ETTN (belgenin GİB tekil kimliği) ile tam eşleşme (yalnız `eq`), UUID biçiminde. Yoldaki `id` ile karıştırmayın.", "disabled": true } ] }, "description": "Gelen faturaları belge tarihine göre, en yeni önce listeler. `status` hiçbir zaman `draft` ya da `sending` olmaz. Panelden elle kaydedilmiş belgede `uuid`, `received_at` ve `answer_due_date` null döner.\n\n**Gerekli kapsam:** `EFatura.GelenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `filter[issue_date][gte]`, `filter[issue_date][lte]`, `filter[status][eq]`, `filter[document_type][eq]`, `filter[invoice_no][eq]`, `filter[uuid][eq]`.\n\n**Notlar:**\n- Arşivlenen belge listeden düşer, tek okuma onu da döndürür.\n- Alımında hata oluşmuş belge listede görünmez; hata giderilince gerçek durumuyla görünür. Bu yüzden `failed` süzgeci yoktur.\n- Zarf kimliği (`envelope_id`) gelen faturada yoktur.\n- Belge tipi yalnız `E_FATURA`'dır; iade, kamu, ihracat gibi ayrımlar `invoice_type` ve `scenario` alanlarındadır.\n- Fatura numarası gelen faturada benzersiz değildir: iki tedarikçi aynı numarayı kullanabilir, `filter[invoice_no][eq]` birden çok satır döndürebilir; gönderenleri `sender_tax_number` ile ayırın.\n- Gelen belge bize belge tarihinden günler sonra ulaşabilir (`received_at`): her turda son 45 günü okuyun, dönemi kapatmadan önce o dönemi bir kez tam okuyun.\n- `gelen_fatura_id` boşsa listenin ilk satırıyla dolar." }, "response": [ { "name": "Gelen fatura sayfası", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e5a8-6f21-7c0d-b3e4-91a7f2c5d806\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"TDR2026000000481\",\n \"uuid\": \"0191e5a7-0e3c-7b52-8d19-4c6f0a2e9b71\",\n \"sender_title\": \"Örnek Tedarikçi Ltd. Şti.\",\n \"sender_tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-02\",\n \"total\": \"8400.00\",\n \"currency\": \"TRY\",\n \"status\": \"sent\",\n \"status_detail\": \"YANIT_BEKLENIYOR\",\n \"received_at\": \"2026-10-02T09:41:07.551820Z\",\n \"answer_due_date\": \"2026-10-14\",\n \"created_at\": \"2026-10-02T09:41:08.002113Z\",\n \"updated_at\": \"2026-10-02T09:41:08.002113Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Gelen listede failed süzgeci", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices?filter[status][eq]=failed", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices"], "query": [ { "key": "filter[status][eq]", "value": "failed" } ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"değer şunlardan biri olmalı: sent, accepted, rejected, cancelled\",\n \"details\": {\n \"field\": \"filter[status][eq]\"\n }\n}" } ] }, { "name": "Gelen fatura detayı", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}"] }, "description": "Tek bir gelen faturayı okur; arşivlenmiş belge de döner. `answer_due_date` ticari faturada kabul ya da red için son gündür; yanıt dış API'den değil panelden verilir.\n\n**Gerekli kapsam:** `EFatura.GelenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{gelen_fatura_id}}`: Gelen faturanın id'si. Boşsa önce \"Gelen fatura listesi\" isteğini çalıştırın (ilk satırdan dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Alımında hata oluşmuş belge ve e-İrsaliye 404 döner." }, "response": [ { "name": "Gelen fatura", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e5a8-6f21-7c0d-b3e4-91a7f2c5d806\",\n \"document_type\": \"E_FATURA\",\n \"invoice_type\": \"SATIS\",\n \"scenario\": \"TICARI_FATURA\",\n \"invoice_no\": \"TDR2026000000481\",\n \"uuid\": \"0191e5a7-0e3c-7b52-8d19-4c6f0a2e9b71\",\n \"sender_title\": \"Örnek Tedarikçi Ltd. Şti.\",\n \"sender_tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-02\",\n \"total\": \"8400.00\",\n \"currency\": \"TRY\",\n \"status\": \"sent\",\n \"status_detail\": \"YANIT_BEKLENIYOR\",\n \"received_at\": \"2026-10-02T09:41:07.551820Z\",\n \"answer_due_date\": \"2026-10-14\",\n \"created_at\": \"2026-10-02T09:41:08.002113Z\",\n \"updated_at\": \"2026-10-02T09:41:08.002113Z\"\n }\n}" }, { "name": "Gelen fatura bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "57" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:general" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Gelen fatura bulunamadı\"\n}" } ] }, { "name": "Gelen fatura XML'ini indir", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "xml"] }, "description": "Gelen faturanın UBL XML'ini gönderenin imzalı hâliyle indirir.\n\n**Gerekli kapsam:** `EFatura.GelenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: belge değişmez. İndirme firmanın işlem geçmişine dış API anahtarı adıyla yazılır (panelden yapılan indirmeyle aynı kural).\n\n**Kullanılan değişkenler (ortam):**\n- `{{gelen_fatura_id}}`: Gelen faturanın id'si. Boşsa önce \"Gelen fatura listesi\" isteğini çalıştırın (ilk satırdan dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Yanıt dosyanın kendisidir. Postman'de **Send and Download** ile kaydedin; XML'i saklarken yeniden biçimlendirmeyin, imza bozulur.\n- Elle kaydedilmiş (e-belge olarak gelmemiş) belge ve e-belge entegrasyonu tamamlanmamış firma 422 `invalid_state` alır. Arşivlenmiş belge listede yoktur ama id ile indirilir.\n- e-belge servisi hata verirse 500 `internal_error` döner; indirme yeniden denenebilir.\n- İndirme uçlarının ayrı kotası vardır (anahtar başına dakikada 60, firma toplamı dakikada 120) ve firma başına aynı anda en çok 4 indirme yapılır; fazlası 429 alır." }, "response": [ { "name": "Dosya", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "xml"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "xml", "header": [ { "key": "Content-Type", "value": "application/xml; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" }, { "key": "Content-Disposition", "value": "attachment; filename=\"TDR2026000000481.xml\"" } ], "cookie": [], "body": "\n\n \n ...\n" }, { "name": "Elle kaydedilmiş belge", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/xml", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "xml"] } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" } ], "cookie": [], "body": "{\n \"error\": \"invalid_state\",\n \"message\": \"Belgenin e-belge kaydı yok; indirilemez\"\n}" } ] }, { "name": "Gelen fatura PDF'ini indir", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "pdf"] }, "description": "Gelen faturanın PDF görüntüsünü indirir.\n\n**Gerekli kapsam:** `EFatura.GelenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: belge değişmez. İndirme firmanın işlem geçmişine dış API anahtarı adıyla yazılır (panelden yapılan indirmeyle aynı kural).\n\n**Kullanılan değişkenler (ortam):**\n- `{{gelen_fatura_id}}`: Gelen faturanın id'si. Boşsa önce \"Gelen fatura listesi\" isteğini çalıştırın (ilk satırdan dolar) ya da ortamda elle yazın.\n\n**Notlar:**\n- Yanıt dosyanın kendisidir. Postman'de **Send and Download** ile kaydedin.\n- Elle kaydedilmiş (e-belge olarak gelmemiş) belge ve e-belge entegrasyonu tamamlanmamış firma 422 `invalid_state` alır. Arşivlenmiş belge listede yoktur ama id ile indirilir.\n- e-belge servisi hata verirse 500 `internal_error` döner; indirme yeniden denenebilir.\n- İndirme uçlarının ayrı kotası vardır (anahtar başına dakikada 60, firma toplamı dakikada 120) ve firma başına aynı anda en çok 4 indirme yapılır; fazlası 429 alır." }, "response": [ { "name": "Dosya", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "pdf"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "text", "header": [ { "key": "Content-Type", "value": "application/pdf" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "10" }, { "key": "X-RateLimit-Remaining", "value": "9" }, { "key": "X-RateLimit-Reset", "value": "1791105600" }, { "key": "X-RateLimit-Resource", "value": "key:download" }, { "key": "Content-Disposition", "value": "attachment; filename=\"TDR2026000000481.pdf\"" } ], "cookie": [], "body": "%PDF-1.7\n(ikili PDF içeriği: Postman'de Send yerine Send and Download ile dosyaya kaydedin)" }, { "name": "Aynı anda çok fazla indirme", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/inbox-invoices/{{gelen_fatura_id}}/pdf", "host": ["{{base_url}}"], "path": ["v1", "inbox-invoices", "{{gelen_fatura_id}}", "pdf"] } }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f0-0000-7000-8000-000000000001" }, { "key": "X-RateLimit-Limit", "value": "4" }, { "key": "X-RateLimit-Remaining", "value": "0" }, { "key": "X-RateLimit-Reset", "value": "1791105601" }, { "key": "X-RateLimit-Resource", "value": "firm:download-concurrency" }, { "key": "Retry-After", "value": "1" } ], "cookie": [], "body": "{\n \"error\": \"rate_limited\",\n \"message\": \"Çok fazla istek gönderildi - lütfen biraz sonra tekrar deneyin\"\n}" } ] } ] }, { "name": "6. Makbuz, irsaliye ve e-Fatura posta kutuları", "description": "Tek makbuz ve tek irsaliye okuması ile alıcının GİB posta kutusu sorgusu. Dış API makbuzları ve irsaliyeleri listelemez; gelen faturalar \"5. Gelen faturalar\" klasöründedir. Bu klasördeki isteklerin hepsi salt okumadır.", "item": [ { "name": "Makbuzlar", "item": [ { "name": "Makbuz detayı", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/receipts/{{makbuz_id}}", "host": ["{{base_url}}"], "path": ["v1", "receipts", "{{makbuz_id}}"] }, "description": "`makbuz_id` değişkenindeki makbuzu okur. Fatura ya da irsaliye id'si bu uca gelirse 404 döner (kaynaklar birbirini dışlar).\n\n**Gerekli kapsam:** `Makbuz.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{makbuz_id}}`: Makbuzun id'si. Dış API makbuzları listelemez: id değerini ortamda elle yazın." }, "response": [ { "name": "Makbuz", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/receipts/{{makbuz_id}}", "host": ["{{base_url}}"], "path": ["v1", "receipts", "{{makbuz_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e583-8c1d-7c61-87dc-aea88bb12713" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e538-2262-7752-ab5e-b9e834dc2047\",\n \"document_type\": \"E_SMM\",\n \"receipt_no\": \"SMM2026000000003\",\n \"uuid\": \"0191e531-1794-77a9-a372-7f7ffc618111\",\n \"contact_title\": \"Örnek Danışmanlık\",\n \"tax_number\": \"11111111111\",\n \"issue_date\": \"2026-09-29\",\n \"total\": \"5000.00\",\n \"currency\": \"TRY\",\n \"status\": \"accepted\",\n \"status_detail\": \"KABUL\",\n \"created_at\": \"2026-09-30T11:22:09.250618Z\",\n \"updated_at\": \"2026-09-30T11:22:09.250618Z\"\n }\n}" }, { "name": "Makbuz bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/receipts/{{makbuz_id}}", "host": ["{{base_url}}"], "path": ["v1", "receipts", "{{makbuz_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e506-90b4-74b8-9a8c-0eb05864eabb" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"Makbuz bulunamadı\"\n}" } ] } ] }, { "name": "İrsaliyeler", "item": [ { "name": "İrsaliye detayı", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/despatches/{{irsaliye_id}}", "host": ["{{base_url}}"], "path": ["v1", "despatches", "{{irsaliye_id}}"] }, "description": "`irsaliye_id` değişkenindeki irsaliyeyi okur; giden ve gelen irsaliye aynı uçtan okunur.\n\n**Gerekli kapsam:** `EIrsaliye.GidenKutusuIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Kullanılan değişkenler (ortam):**\n- `{{irsaliye_id}}`: İrsaliyenin id'si. Dış API irsaliyeleri listelemez: id değerini ortamda elle yazın." }, "response": [ { "name": "İrsaliye", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/despatches/{{irsaliye_id}}", "host": ["{{base_url}}"], "path": ["v1", "despatches", "{{irsaliye_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5ae-1a75-77c8-b540-7f8926d83283" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"id\": \"0191e543-e6b3-7955-9e99-b3eb091b5e54\",\n \"direction\": \"outbound\",\n \"despatch_no\": \"IRS2026000000007\",\n \"uuid\": \"0191e5e3-c1b1-7e5f-b770-66058189c21b\",\n \"contact_title\": \"Örnek Müşteri A.Ş.\",\n \"tax_number\": \"1234567890\",\n \"issue_date\": \"2026-10-03\",\n \"total\": \"0.00\",\n \"currency\": \"TRY\",\n \"status\": \"sent\",\n \"status_detail\": \"GIBE_GONDERILDI\",\n \"created_at\": \"2026-10-03T14:05:48.903351Z\",\n \"updated_at\": \"2026-10-03T14:05:48.903351Z\"\n }\n}" }, { "name": "İrsaliye bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/despatches/{{irsaliye_id}}", "host": ["{{base_url}}"], "path": ["v1", "despatches", "{{irsaliye_id}}"] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e545-de87-722b-b5bb-6a15ffde4133" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"not_found\",\n \"message\": \"İrsaliye bulunamadı\"\n}" } ] } ] }, { "name": "e-Fatura posta kutusu", "item": [ { "name": "GİB posta kutusu sorgusu", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/e-invoice-inboxes/1234567890", "host": ["{{base_url}}"], "path": ["v1", "e-invoice-inboxes", "1234567890"] }, "description": "Alıcının GİB mükellef dizinindeki durumunu döner. **e-Fatura mı e-Arşiv mi keseceğinize karar vermek için gereklidir:** alıcı e-Fatura mükellefiyse e-Arşiv kesmek belgeyi hukuken geçersiz kılar. e-Fatura keserken `recipient_mailbox` değeri olarak `direction: inbox` etiketini (GİB PK etiketi) kullanın.\n\n**Gerekli kapsam:** `Diger.EBelgeMukellefBilgileriIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**Notlar:**\n- Yoldaki `1234567890` yalnız bir örnektir: **kendi alıcınızın 10 haneli VKN ya da 11 haneli TCKN değerini yazın.** Başka biçim 400 alır.\n- Dizinde bulunmayan VKN 404 döndürmez: `e_invoice_user: false` taşıyan geçerli bir yanıt verir, çünkü sorunun yanıtı \"hayır\"dır. Mükellefiyet aktif (silinmemiş) etiketten türer; silinmiş etiketler de `addresses` içinde `deleted_at` ile döner.\n- Dizin ulusal bir sicildir, firmaya ait değildir; bu kaynağın firma kapsamı yoktur. Dizinin yüklemesi eksikse yanıt 500 `internal_error` olur." }, "response": [ { "name": "Dizinde kayıtlı değil (e-Arşiv kesilebilir)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/e-invoice-inboxes/1234567890", "host": ["{{base_url}}"], "path": ["v1", "e-invoice-inboxes", "1234567890"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e59e-4a50-7fdf-8ade-07f9ffdf96e2" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"tax_number\": \"1234567890\",\n \"e_invoice_user\": false,\n \"e_despatch_user\": false,\n \"addresses\": []\n }\n}" }, { "name": "e-Fatura mükellefi", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/e-invoice-inboxes/4567890128", "host": ["{{base_url}}"], "path": ["v1", "e-invoice-inboxes", "4567890128"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e522-5376-78da-9042-aa53afee265b" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"tax_number\": \"4567890128\",\n \"title\": \"Örnek Lojistik A.Ş.\",\n \"e_invoice_user\": true,\n \"e_despatch_user\": true,\n \"e_invoice_registered_at\": \"2021-03-15T00:00:00Z\",\n \"e_despatch_registered_at\": \"2022-01-10T00:00:00Z\",\n \"addresses\": [\n {\n \"address\": \"urn:mail:defaultpk@ornek-lojistik.example\",\n \"document_type\": \"FATURA\",\n \"direction\": \"inbox\",\n \"created_at\": \"2021-03-15T00:00:00Z\"\n },\n {\n \"address\": \"urn:mail:defaultgb@ornek-lojistik.example\",\n \"document_type\": \"FATURA\",\n \"direction\": \"outbox\",\n \"created_at\": \"2021-03-15T00:00:00Z\"\n },\n {\n \"address\": \"urn:mail:irsaliyepk@ornek-lojistik.example\",\n \"document_type\": \"IRSALIYE\",\n \"direction\": \"inbox\",\n \"created_at\": \"2022-01-10T00:00:00Z\"\n }\n ]\n }\n}" }, { "name": "Geçersiz VKN ya da TCKN", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/e-invoice-inboxes/123", "host": ["{{base_url}}"], "path": ["v1", "e-invoice-inboxes", "123"] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e578-1dad-737d-8c28-3865c64b31a3" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"validation_failed\",\n \"message\": \"tax_number 10 haneli VKN veya 11 haneli TCKN olmalı\",\n \"details\": {\n \"field\": \"tax_number\"\n }\n}" } ] } ] } ] }, { "name": "7. Kurlar ve KDV oranları", "description": "TCMB kurları ve faaliyet koduna göre KDV oranları. Kasa, banka ve POS hesapları dış API'de yoktur. Bu klasördeki isteklerin hepsi salt okumadır.", "item": [ { "name": "TCMB döviz kurları", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/exchange-rates", "host": ["{{base_url}}"], "path": ["v1", "exchange-rates"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız.", "disabled": true }, { "key": "page_size", "value": "25", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true }, { "key": "sort", "value": "-date", "description": "Sıralama (tek alan): `date` artan, `-date` azalan. Varsayılan `-date`.", "disabled": true }, { "key": "filter[date][gte]", "value": "2026-01-01T00:00:00Z", "description": "`date` alanı için büyük ya da eşit süzgeci (`gte`). RFC3339 zaman damgası; tarih gün hassasiyetli olduğu için değerin gün kısmı kullanılır. Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[date][lte]", "value": "2026-12-31T23:59:59Z", "description": "`date` alanı için küçük ya da eşit süzgeci (`lte`). RFC3339 zaman damgası; tarih gün hassasiyetli olduğu için değerin gün kısmı kullanılır. Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[date][gt]", "value": "2026-01-01T00:00:00Z", "description": "`date` alanı için büyüktür süzgeci (`gt`). RFC3339 zaman damgası; tarih gün hassasiyetli olduğu için değerin gün kısmı kullanılır. Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true }, { "key": "filter[date][lt]", "value": "2026-12-31T23:59:59Z", "description": "`date` alanı için küçüktür süzgeci (`lt`). RFC3339 zaman damgası; tarih gün hassasiyetli olduğu için değerin gün kısmı kullanılır. Örnek: `2026-01-01T00:00:00Z`. Saat farkında `+` yerine `%2B` yazın.", "disabled": true } ] }, "description": "TCMB bülteninin satırlarını döner; firmaya ait değil, ulusal bir veridir ve geçmişi de sayfalar. Değerler her zaman **1 birim yabancı paranın TL karşılığıdır** (bülten JPY'yi 100 birim üzerinden yayımlar, bu yüzden `unit` alanı yoktur) ve sekiz ondalıklı metindir. Bülten bir değeri boş yayımlarsa alan hiç gelmez.\n\n**Gerekli kapsam:** `Sistem.FirmaBilgileriIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`, `sort`, `filter[date][gte]`, `filter[date][lte]`, `filter[date][gt]`, `filter[date][lt]`.\n\n**Notlar:**\n- Dövizli fatura kesmeden önce `exchange_rate` değeri için kullanabilirsiniz. `date` bültenin kendi tarihidir (yayın günü)." }, "response": [ { "name": "Kur sayfası", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/exchange-rates", "host": ["{{base_url}}"], "path": ["v1", "exchange-rates"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e58f-c8dc-7627-ac00-06e64dd39f99" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"id\": \"0191e554-e133-7030-85f4-53f61a737470\",\n \"date\": \"2026-10-02\",\n \"currency\": \"USD\",\n \"forex_buying\": \"44.12340000\",\n \"forex_selling\": \"44.19750000\",\n \"effective_buying\": \"44.09870000\",\n \"effective_selling\": \"44.45510000\",\n \"created_at\": \"2026-10-03T14:05:48.903351Z\",\n \"updated_at\": \"2026-10-03T14:05:48.903351Z\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Anahtarın kapsamı yok", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/exchange-rates", "host": ["{{base_url}}"], "path": ["v1", "exchange-rates"] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e554-060a-7cd3-a54f-3d44257e0b36" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"forbidden\",\n \"message\": \"Bu işlem için yetkiniz yok\"\n}" } ] }, { "name": "Faaliyet koduna göre KDV oranları", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/tax-rates", "host": ["{{base_url}}"], "path": ["v1", "tax-rates"], "query": [ { "key": "cursor", "value": "", "description": "Sayfalama imleci: bir önceki yanıttaki `meta.next_cursor` değeri, olduğu gibi. Opak bir metindir: yorumlamayın, değiştirmeyin. İlk sayfada gönderilmez; `next_cursor` `null` ise son sayfadasınız.", "disabled": true }, { "key": "page_size", "value": "25", "description": "Sayfa başına satır sayısı: 1 ile 100 arası, varsayılan 25. 100'ün üstü hata vermeden 100'e kırpılır.", "disabled": true } ] }, "description": "Yürürlükteki GİB listesine göre her faaliyet kodunda (NACE) kullanılabilecek KDV oranlarını döner; firmaya ait değil, tüm firmalar için ortak bir listedir. Oranlar iki ondalıklı metindir (`\"20.00\"`) ve her satır, okunduğu listenin sürümünü `list_version` ile taşır. Listede ÖTV oranı yoktur.\n\n**Gerekli kapsam:** `Sistem.FirmaBilgileriIzleyebilir`. Anahtar bu kapsamı taşımıyorsa istek 403 `forbidden` alır.\n\n**Yan etki:** Salt okuma: hiçbir kayıt değişmez.\n\n**İsteğe bağlı parametreler** (Params sekmesinde işaretsiz gelir, kutucuğu işaretleyerek açın): `cursor`, `page_size`.\n\n**Notlar:**\n- Sıra NACE koduna göre sabittir; `sort` ve `filter` parametresi yoktur. `cursor` yine opak bir metindir, yalnız geri verirsiniz.\n- Henüz hiç liste yüklenmemişse yanıt boş bir sayfadır, hata değildir." }, "response": [ { "name": "Oran listesi sayfası", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/tax-rates", "host": ["{{base_url}}"], "path": ["v1", "tax-rates"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e58f-c8dc-7627-ac00-06e64dd39f99" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": [\n {\n \"nace_code\": \"47.11\",\n \"allowed_vat_rates\": [\n \"1.00\",\n \"10.00\",\n \"20.00\"\n ],\n \"list_version\": \"2026-04\"\n }\n ],\n \"meta\": {\n \"next_cursor\": null\n }\n}" }, { "name": "Anahtarın kapsamı yok", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/tax-rates", "host": ["{{base_url}}"], "path": ["v1", "tax-rates"] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e554-060a-7cd3-a54f-3d44257e0b36" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"error\": \"forbidden\",\n \"message\": \"Bu işlem için yetkiniz yok\"\n}" } ] } ] }, { "name": "8. Kendi isteğiniz (şablon)", "description": "Koleksiyonda olmayan bir isteği buradan kurun: şablonu **çoğaltın (Duplicate)** ve yolu, yöntemi ya da gövdeyi değiştirin. Koleksiyonun dışında kurulan istekler imzalanmaz ve 401 alır.", "item": [ { "name": "Şablon: yolu ve gövdeyi değiştirip kullanın", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"] }, "description": "Kendi isteğinizi buradan kurun. **Bu isteği çoğaltın (Duplicate) ve yolu, yöntemi ya da gövdeyi değiştirin.** Çoğaltılan istek bu klasörde, yani koleksiyonun İÇİNDE kaldığı sürece imzalanır.\n\n**Gerekli kapsam:** yok, geçerli her anahtar çağırabilir.\n\n**Yan etki:** Şablon `GET /v1/me` ile gelir ve salt okuma yapar; yöntemi ya da yolu değiştirirseniz yan etki sizin seçiminizdir.\n\n**Notlar:**\n- **Başlık ELLE EKLEMEYİN.** Koleksiyon `X-Api-Key`, `X-Api-Timestamp` ve `X-Api-Signature` başlıklarını her istekte kendisi üretir. Secret'ı hiçbir başlığa yazmayın.\n- **Koleksiyonun dışında kurduğunuz istekler imzalanmaz** ve 401 alır: isteği Postman'de yeni bir sekmede ya da başka bir koleksiyonda kurmayın, bu klasörde çoğaltın.\n- Yalnız `/v1/*` yolları çağrılır. `/api/*` ile başlayan yollar YouSoft panelinin uçlarıdır, dış API değildir ve API anahtarı ile çağrılmaz; koleksiyon bu yolları imzalamadan hata ile durdurur.\n- Gövde yalnız **raw (JSON)** olmalıdır; form-data ve urlencoded imzalanmaz. İmza her gönderimde yeniden hesaplanır, bu yüzden gövdeyi düzenledikten sonra yeniden göndermeniz yeter.\n- Tüm uçların listesi, parametreleri ve yanıtları için geliştirici portalındaki OpenAPI referansına bakın." }, "response": [ { "name": "Anahtarın kimliği", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e551-2b22-7f80-b30b-18566b6f6c27" }, { "key": "X-RateLimit-Limit", "value": "60" }, { "key": "X-RateLimit-Remaining", "value": "58" }, { "key": "X-RateLimit-Reset", "value": "1791105600" } ], "cookie": [], "body": "{\n \"data\": {\n \"role\": \"API_CLIENT\",\n \"scope\": \"API\",\n \"firma_id\": \"0191e515-2e76-767e-ab5d-0500f96619e5\",\n \"api_client_id\": \"0191e520-15ed-74ac-a95c-a15b584d852b\"\n }\n}" }, { "name": "Anahtar ya da imza doğrulanamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/v1/me", "host": ["{{base_url}}"], "path": ["v1", "me"] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "X-Request-Id", "value": "0191e5f4-0609-7d37-9c3d-c57b00937dd2" } ], "cookie": [], "body": "{\n \"error\": \"unauthorized\",\n \"message\": \"API anahtarı doğrulanamadı\"\n}" } ] } ] } ] }