{ "info": { "_postman_id": "b6f3c0c2-6a4e-4a8e-9a55-sektorbul-v1", "name": "Sektör Bul API v1", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Sektör Bul herkese açık REST API'si (v1).\n\nTemel adres: https://api.sektorbul.com\n\n**Kurulum**\n1. Bu koleksiyonu Postman'e içe aktarın (Import). Ayrı bir ortam dosyası gerekmez; temel adres koleksiyonda hazırdır.\n2. Koleksiyonun **Variables** sekmesinde **apiKey** değerine Panel → API sayfasında oluşturduğunuz anahtarı (`sb_live_…`) yazıp kaydedin. API erişimi Enterprise pakettedir.\n3. **Arama başlat** → **Durum ve sonuçlar** sırasıyla çalıştırın. Ya da tüm akış için klasörü Collection Runner ile çalıştırın.\n\n**Kurallar**\n- Kimlik: her istekte `X-API-Key` başlığı (koleksiyon düzeyinde ayarlı).\n- Hız sınırı: anahtar başına **saniyede 1 istek**. Koleksiyonun ön-istek betiği istekleri otomatik olarak aralıklandırır; yine de `429 rate_limited` gelirse `Retry-After` kadar bekleyin.\n- Kota: günlük işletme kotası; dolunca `429 daily_quota`.\n- Hatalar: `{ title, status, detail, code }` biçiminde JSON.\n\nDokümantasyon: https://sektorbul.com/docs" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Rate limit: 1 request / second per API key. Space requests out automatically. 1.25 s, not 1 s:", "// the server's window is renewed on a ~100 ms timer and network latency varies, so 1 s exactly can still hit 429.", "const last = Number(pm.collectionVariables.get(\"_lastRequestAt\") || 0);", "const wait = Math.max(0, 1250 - (Date.now() - last));", "pm.collectionVariables.set(\"_lastRequestAt\", String(Date.now() + wait));", "if (wait > 0) setTimeout(() => {}, wait);", "", "if (!pm.variables.get(\"apiKey\") || pm.variables.get(\"apiKey\").includes(\"BURAYA\")) {", " console.warn(\"apiKey boş: koleksiyonun Variables sekmesindeki apiKey değerine Panel → API'de oluşturduğunuz anahtarı yazın.\");", "}" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Every error body is { title, status, detail, code }.", "if (pm.response.code >= 400 && pm.response.headers.get(\"Content-Type\")?.includes(\"json\")) {", " const e = pm.response.json();", " console.log(`${pm.response.code} ${e.code ?? \"\"}: ${e.detail ?? e.title}`);", " // Rate limited: wait Retry-After and send the same request again (Collection Runner).", " if (pm.response.code === 429 && e.code === \"rate_limited\") {", " const seconds = Number(pm.response.headers.get(\"Retry-After\") || 1);", " setTimeout(() => {}, seconds * 1000 + 250);", " pm.execution.setNextRequest(pm.info.requestName);", " }", "}" ] } } ], "variable": [ { "key": "baseUrl", "value": "https://api.sektorbul.com", "description": "API temel adresi." }, { "key": "apiKey", "value": "sb_live_BURAYA_ANAHTARINIZI_YAZIN", "description": "Panel → API'de oluşturduğunuz anahtar (sb_live_…)." }, { "key": "searchId", "value": "", "description": "Arama başlat isteği tarafından otomatik doldurulur." }, { "key": "_lastRequestAt", "value": "0", "description": "Hız sınırı için iç sayaç." }, { "key": "docsUrl", "value": "https://sektorbul.com/docs" } ], "item": [ { "name": "1 · Arama akışı", "description": "Arama başlat → durum sorgula → sonuçları al. Klasörü Collection Runner ile çalıştırırsanız durum isteği arama bitene kadar kendini tekrarlar.", "item": [ { "name": "Arama başlat", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 202\", () => pm.response.to.have.status(202));", " const body = pm.response.json();", " pm.test(\"success: true ve GUID id\", () => {", " pm.expect(body.success).to.eql(true);", " pm.expect(body.id).to.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);", " });", " pm.test(\"Location başlığı durum adresini gösterir\", () => pm.expect(pm.response.headers.get(\"Location\")).to.include(body.id));", " pm.collectionVariables.set(\"searchId\", body.id);", " console.log(\"searchId =\", body.id, \"· status =\", body.status);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"includeEmails\": false,\n \"deepScan\": false,\n \"maxResults\": 500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "Bir arama başlatır ve **hemen** `202 Accepted` döner. Sonuçlar bu istekte gelmez; dönen `id` ile **Durum ve sonuçlar** isteği atılır.\n\n| Alan | Tip | Zorunlu | Açıklama |\n|---|---|---|---|\n| keyword | string | evet | Sektör / anahtar kelime, ör. \"kuaför\" (en fazla 120 karakter) |\n| city | string | evet | Türkiye'nin 81 ilinden biri, ör. \"İstanbul\" (büyük/küçük harf önemsiz) |\n| district | string \\| null | hayır | İlçe, ör. \"Fatih\" |\n| includeEmails | boolean | hayır | Web sitelerinden e-posta ve sosyal medya topla (daha yavaş) |\n| deepScan | boolean | hayır | includeEmails ile birlikte iletişim sayfalarına da bak |\n| maxResults | number | hayır | 20–500, varsayılan 500 |\n\nBu isteğin test betiği dönen `id`'yi **{{searchId}}** değişkenine yazar." }, "response": [ { "name": "202 · Kuyruğa alındı", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"includeEmails\": false,\n \"deepScan\": false,\n \"maxResults\": 500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "Bir arama başlatır ve **hemen** `202 Accepted` döner. Sonuçlar bu istekte gelmez; dönen `id` ile **Durum ve sonuçlar** isteği atılır.\n\n| Alan | Tip | Zorunlu | Açıklama |\n|---|---|---|---|\n| keyword | string | evet | Sektör / anahtar kelime, ör. \"kuaför\" (en fazla 120 karakter) |\n| city | string | evet | Türkiye'nin 81 ilinden biri, ör. \"İstanbul\" (büyük/küçük harf önemsiz) |\n| district | string \\| null | hayır | İlçe, ör. \"Fatih\" |\n| includeEmails | boolean | hayır | Web sitelerinden e-posta ve sosyal medya topla (daha yavaş) |\n| deepScan | boolean | hayır | includeEmails ile birlikte iletişim sayfalarına da bak |\n| maxResults | number | hayır | 20–500, varsayılan 500 |\n\nBu isteğin test betiği dönen `id`'yi **{{searchId}}** değişkenine yazar." }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" }, { "key": "Location", "value": "https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55" } ], "body": "{\n \"success\": true,\n \"id\": \"0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\",\n \"status\": \"Queued\",\n \"statusUrl\": \"https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\"\n}" }, { "name": "202 · Havuzdan anında", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"includeEmails\": false,\n \"deepScan\": false,\n \"maxResults\": 500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "Bir arama başlatır ve **hemen** `202 Accepted` döner. Sonuçlar bu istekte gelmez; dönen `id` ile **Durum ve sonuçlar** isteği atılır.\n\n| Alan | Tip | Zorunlu | Açıklama |\n|---|---|---|---|\n| keyword | string | evet | Sektör / anahtar kelime, ör. \"kuaför\" (en fazla 120 karakter) |\n| city | string | evet | Türkiye'nin 81 ilinden biri, ör. \"İstanbul\" (büyük/küçük harf önemsiz) |\n| district | string \\| null | hayır | İlçe, ör. \"Fatih\" |\n| includeEmails | boolean | hayır | Web sitelerinden e-posta ve sosyal medya topla (daha yavaş) |\n| deepScan | boolean | hayır | includeEmails ile birlikte iletişim sayfalarına da bak |\n| maxResults | number | hayır | 20–500, varsayılan 500 |\n\nBu isteğin test betiği dönen `id`'yi **{{searchId}}** değişkenine yazar." }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "body": "{\n \"success\": true,\n \"id\": \"0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\",\n \"status\": \"Completed\",\n \"statusUrl\": \"https://api.sektorbul.com/api/v1/searches/0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\"\n}" }, { "name": "400 · Geçersiz il", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"includeEmails\": false,\n \"deepScan\": false,\n \"maxResults\": 500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "Bir arama başlatır ve **hemen** `202 Accepted` döner. Sonuçlar bu istekte gelmez; dönen `id` ile **Durum ve sonuçlar** isteği atılır.\n\n| Alan | Tip | Zorunlu | Açıklama |\n|---|---|---|---|\n| keyword | string | evet | Sektör / anahtar kelime, ör. \"kuaför\" (en fazla 120 karakter) |\n| city | string | evet | Türkiye'nin 81 ilinden biri, ör. \"İstanbul\" (büyük/küçük harf önemsiz) |\n| district | string \\| null | hayır | İlçe, ör. \"Fatih\" |\n| includeEmails | boolean | hayır | Web sitelerinden e-posta ve sosyal medya topla (daha yavaş) |\n| deepScan | boolean | hayır | includeEmails ile birlikte iletişim sayfalarına da bak |\n| maxResults | number | hayır | 20–500, varsayılan 500 |\n\nBu isteğin test betiği dönen `id`'yi **{{searchId}}** değişkenine yazar." }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"title\": \"Geçersiz istek\",\n \"status\": 400,\n \"detail\": \"\\\"Istnbul\\\" geçerli bir il değil. Türkiye'nin 81 ilinden birini yazın.\",\n \"code\": \"invalid_city\"\n}" }, { "name": "429 · Günlük kota doldu", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"includeEmails\": false,\n \"deepScan\": false,\n \"maxResults\": 500\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "Bir arama başlatır ve **hemen** `202 Accepted` döner. Sonuçlar bu istekte gelmez; dönen `id` ile **Durum ve sonuçlar** isteği atılır.\n\n| Alan | Tip | Zorunlu | Açıklama |\n|---|---|---|---|\n| keyword | string | evet | Sektör / anahtar kelime, ör. \"kuaför\" (en fazla 120 karakter) |\n| city | string | evet | Türkiye'nin 81 ilinden biri, ör. \"İstanbul\" (büyük/küçük harf önemsiz) |\n| district | string \\| null | hayır | İlçe, ör. \"Fatih\" |\n| includeEmails | boolean | hayır | Web sitelerinden e-posta ve sosyal medya topla (daha yavaş) |\n| deepScan | boolean | hayır | includeEmails ile birlikte iletişim sayfalarına da bak |\n| maxResults | number | hayır | 20–500, varsayılan 500 |\n\nBu isteğin test betiği dönen `id`'yi **{{searchId}}** değişkenine yazar." }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"title\": \"Limit aşıldı\",\n \"status\": 429,\n \"detail\": \"Günlük 10.000 işletme limitinize ulaştınız (bugün 10.012). Yeni aramalar yarın 00:00'da (TSİ) açılır.\",\n \"code\": \"daily_quota\"\n}" } ] }, { "name": "Durum ve sonuçlar", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 200\", () => pm.response.to.have.status(200));", " const s = pm.response.json();", " pm.test(\"Geçerli bir durum\", () => pm.expect([\"Queued\", \"Running\", \"Completed\", \"Failed\", \"Cancelled\"]).to.include(s.status));", " if (s.status === \"Completed\") {", " pm.test(\"Sonuçlar sayfalı gelir\", () => {", " pm.expect(s.results).to.be.an(\"object\");", " pm.expect(s.results.items).to.be.an(\"array\");", " });", " console.log(`Tamamlandı: ${s.resultCount} işletme (${s.inRegionCount} bölgede) · bu sayfa ${s.results.items.length}`);", " } else if (s.status === \"Queued\" || s.status === \"Running\") {", " console.log(`${s.status}: ${s.resultCount} işletme bulundu, 2 sn sonra tekrar...`);", " // In the Collection Runner: poll this request again until the search finishes.", " setTimeout(() => {}, 2000);", " pm.execution.setNextRequest(pm.info.requestName);", " }", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches/{{searchId}}?page=1&pageSize=100&inRegionOnly=false", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches", "{{searchId}}" ], "query": [ { "key": "page", "value": "1", "description": "1'den başlayan sonuç sayfası" }, { "key": "pageSize", "value": "100", "description": "Sayfa başına sonuç (1–1000)" }, { "key": "inRegionOnly", "value": "false", "description": "true: yalnızca istenen il/ilçedeki işletmeler. Varsayılan false: tüm sonuçlar (her birinde inRegion alanı var)." } ] }, "description": "Aramanın durumunu ve (varsa) sonuçlarını döner.\n\n- `Queued` → `results` null\n- `Running` → kısmi sonuçlar, sorgulamaya devam edin\n- `Completed` → nihai sonuçlar\n- `Failed` / `Cancelled` → `error` alanına bakın\n\n**Collection Runner** ile çalıştırırsanız bu istek, arama `Completed` olana kadar 2 saniye arayla kendini tekrarlar." }, "response": [ { "name": "200 · Çalışıyor (kısmi)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches/{{searchId}}?page=1&pageSize=100&inRegionOnly=false", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches", "{{searchId}}" ], "query": [ { "key": "page", "value": "1", "description": "1'den başlayan sonuç sayfası" }, { "key": "pageSize", "value": "100", "description": "Sayfa başına sonuç (1–1000)" }, { "key": "inRegionOnly", "value": "false", "description": "true: yalnızca istenen il/ilçedeki işletmeler. Varsayılan false: tüm sonuçlar (her birinde inRegion alanı var)." } ] }, "description": "Aramanın durumunu ve (varsa) sonuçlarını döner.\n\n- `Queued` → `results` null\n- `Running` → kısmi sonuçlar, sorgulamaya devam edin\n- `Completed` → nihai sonuçlar\n- `Failed` / `Cancelled` → `error` alanına bakın\n\n**Collection Runner** ile çalıştırırsanız bu istek, arama `Completed` olana kadar 2 saniye arayla kendini tekrarlar." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "body": "{\n \"id\": \"0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\",\n \"status\": \"Running\",\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"fromCache\": false,\n \"resultCount\": 186,\n \"inRegionCount\": 172,\n \"error\": null,\n \"createdAt\": \"2026-11-08T17:25:22Z\",\n \"completedAt\": null,\n \"results\": {\n \"page\": 1,\n \"pageSize\": 100,\n \"total\": 40,\n \"inRegionOnly\": false,\n \"items\": [\n {\n \"id\": 48213,\n \"rank\": 1,\n \"inRegion\": true,\n \"name\": \"Atölye Makas Kuaför\",\n \"category\": \"Kuaför\",\n \"categories\": [\n \"Kuaför\",\n \"Güzellik salonu\"\n ],\n \"rating\": 4.8,\n \"reviewCount\": 312,\n \"phone\": \"0532 ••• •• 41\",\n \"phoneIntl\": \"+90 532 ••• •• 41\",\n \"website\": \"https://atolyemakas.example\",\n \"email\": \"merhaba@atolyemakas.example\",\n \"emails\": [\n \"merhaba@atolyemakas.example\"\n ],\n \"instagram\": \"https://instagram.com/atolyemakas.ornek\",\n \"facebook\": null,\n \"linkedin\": null,\n \"tiktok\": null,\n \"youtube\": null,\n \"x\": null,\n \"address\": \"Örnek Sk. No: 12, Balat, 34087 Fatih/İstanbul\",\n \"neighborhood\": \"Balat\",\n \"district\": \"Fatih\",\n \"city\": \"İstanbul\",\n \"postalCode\": \"34087\",\n \"latitude\": 41.0293,\n \"longitude\": 28.9487,\n \"todayHours\": \"09:00–20:00\",\n \"openStatus\": \"Açık\",\n \"googlePlaceId\": \"ChIJ-ornek-place-id\",\n \"cid\": \"1234567890123456789\",\n \"mapsUrl\": \"https://www.google.com/maps/place/?q=place_id:ChIJ-ornek-place-id\"\n }\n ]\n }\n}" }, { "name": "200 · Tamamlandı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches/{{searchId}}?page=1&pageSize=100&inRegionOnly=false", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches", "{{searchId}}" ], "query": [ { "key": "page", "value": "1", "description": "1'den başlayan sonuç sayfası" }, { "key": "pageSize", "value": "100", "description": "Sayfa başına sonuç (1–1000)" }, { "key": "inRegionOnly", "value": "false", "description": "true: yalnızca istenen il/ilçedeki işletmeler. Varsayılan false: tüm sonuçlar (her birinde inRegion alanı var)." } ] }, "description": "Aramanın durumunu ve (varsa) sonuçlarını döner.\n\n- `Queued` → `results` null\n- `Running` → kısmi sonuçlar, sorgulamaya devam edin\n- `Completed` → nihai sonuçlar\n- `Failed` / `Cancelled` → `error` alanına bakın\n\n**Collection Runner** ile çalıştırırsanız bu istek, arama `Completed` olana kadar 2 saniye arayla kendini tekrarlar." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "body": "{\n \"id\": \"0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\",\n \"status\": \"Completed\",\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"fromCache\": false,\n \"resultCount\": 186,\n \"inRegionCount\": 172,\n \"error\": null,\n \"createdAt\": \"2026-11-08T17:25:22Z\",\n \"completedAt\": \"2026-11-08T17:25:29Z\",\n \"results\": {\n \"page\": 1,\n \"pageSize\": 100,\n \"total\": 186,\n \"inRegionOnly\": false,\n \"items\": [\n {\n \"id\": 48213,\n \"rank\": 1,\n \"inRegion\": true,\n \"name\": \"Atölye Makas Kuaför\",\n \"category\": \"Kuaför\",\n \"categories\": [\n \"Kuaför\",\n \"Güzellik salonu\"\n ],\n \"rating\": 4.8,\n \"reviewCount\": 312,\n \"phone\": \"0532 ••• •• 41\",\n \"phoneIntl\": \"+90 532 ••• •• 41\",\n \"website\": \"https://atolyemakas.example\",\n \"email\": \"merhaba@atolyemakas.example\",\n \"emails\": [\n \"merhaba@atolyemakas.example\"\n ],\n \"instagram\": \"https://instagram.com/atolyemakas.ornek\",\n \"facebook\": null,\n \"linkedin\": null,\n \"tiktok\": null,\n \"youtube\": null,\n \"x\": null,\n \"address\": \"Örnek Sk. No: 12, Balat, 34087 Fatih/İstanbul\",\n \"neighborhood\": \"Balat\",\n \"district\": \"Fatih\",\n \"city\": \"İstanbul\",\n \"postalCode\": \"34087\",\n \"latitude\": 41.0293,\n \"longitude\": 28.9487,\n \"todayHours\": \"09:00–20:00\",\n \"openStatus\": \"Açık\",\n \"googlePlaceId\": \"ChIJ-ornek-place-id\",\n \"cid\": \"1234567890123456789\",\n \"mapsUrl\": \"https://www.google.com/maps/place/?q=place_id:ChIJ-ornek-place-id\"\n }\n ]\n }\n}" }, { "name": "404 · Bulunamadı", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches/{{searchId}}?page=1&pageSize=100&inRegionOnly=false", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches", "{{searchId}}" ], "query": [ { "key": "page", "value": "1", "description": "1'den başlayan sonuç sayfası" }, { "key": "pageSize", "value": "100", "description": "Sayfa başına sonuç (1–1000)" }, { "key": "inRegionOnly", "value": "false", "description": "true: yalnızca istenen il/ilçedeki işletmeler. Varsayılan false: tüm sonuçlar (her birinde inRegion alanı var)." } ] }, "description": "Aramanın durumunu ve (varsa) sonuçlarını döner.\n\n- `Queued` → `results` null\n- `Running` → kısmi sonuçlar, sorgulamaya devam edin\n- `Completed` → nihai sonuçlar\n- `Failed` / `Cancelled` → `error` alanına bakın\n\n**Collection Runner** ile çalıştırırsanız bu istek, arama `Completed` olana kadar 2 saniye arayla kendini tekrarlar." }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"title\": \"Bulunamadı\",\n \"status\": 404,\n \"detail\": \"Arama bulunamadı\",\n \"code\": null\n}" } ] } ] }, { "name": "2 · Hesap", "item": [ { "name": "Aramalarım", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 200\", () => pm.response.to.have.status(200));", " pm.test(\"Sayfalı liste\", () => pm.expect(pm.response.json().items).to.be.an(\"array\"));", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches?page=1&pageSize=20", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ], "query": [ { "key": "page", "value": "1" }, { "key": "pageSize", "value": "20" } ] }, "description": "Aramalarınız, en yeniden eskiye (sonuçlar olmadan)." }, "response": [ { "name": "200 · Liste", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/searches?page=1&pageSize=20", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ], "query": [ { "key": "page", "value": "1" }, { "key": "pageSize", "value": "20" } ] }, "description": "Aramalarınız, en yeniden eskiye (sonuçlar olmadan)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "body": "{\n \"items\": [\n {\n \"id\": \"0193a7c2-5d1e-7b3a-9f10-6a2c1e8d4b55\",\n \"status\": \"Completed\",\n \"keyword\": \"kuaför\",\n \"city\": \"İstanbul\",\n \"district\": \"Fatih\",\n \"fromCache\": false,\n \"resultCount\": 186,\n \"inRegionCount\": 172,\n \"error\": null,\n \"createdAt\": \"2026-11-08T17:25:22Z\",\n \"completedAt\": \"2026-11-08T17:25:29Z\",\n \"results\": null\n }\n ],\n \"page\": 1,\n \"pageSize\": 20,\n \"total\": 1\n}" } ] }, { "name": "Kota durumu", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 200\", () => pm.response.to.have.status(200));", " const q = pm.response.json();", " pm.test(\"dailyLimit = baseLimit + creditBalance\", () => pm.expect(q.dailyLimit).to.eql(q.baseLimit + q.creditBalance));", " console.log(`Bugün ${q.usedToday}/${q.dailyLimit} · kalan ${q.remaining}`);", "}" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/quota", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "quota" ] }, "description": "Bugünkü işletme kotası (panel ile ortak). `dailyLimit = baseLimit + creditBalance`; 00:00'da (TSİ) sıfırlanır." }, "response": [ { "name": "200 · Kota", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/quota", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "quota" ] }, "description": "Bugünkü işletme kotası (panel ile ortak). `dailyLimit = baseLimit + creditBalance`; 00:00'da (TSİ) sıfırlanır." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json; charset=utf-8" } ], "body": "{\n \"usedToday\": 1240,\n \"dailyLimit\": 10000,\n \"remaining\": 8760,\n \"resetsAt\": \"2026-11-08T21:00:00Z\",\n \"plan\": \"Enterprise\",\n \"planName\": \"Enterprise\",\n \"contactData\": true,\n \"apiAccess\": true,\n \"baseLimit\": 10000,\n \"creditBalance\": 0\n}" } ] } ] }, { "name": "3 · Hata örnekleri", "description": "Bilerek hatalı istekler: hata biçimini ve kodlarını görmek için.", "item": [ { "name": "Anahtar yok → 401", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 401\", () => pm.response.to.have.status(401));", " pm.test(\"code: api_key_missing\", () => pm.expect(pm.response.json().code).to.eql(\"api_key_missing\"));", "}" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/quota", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "quota" ] }, "description": "X-API-Key başlığı olmadan." } }, { "name": "Geçersiz anahtar → 401", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 401\", () => pm.response.to.have.status(401));", " pm.test(\"code: invalid_api_key\", () => pm.expect(pm.response.json().code).to.eql(\"invalid_api_key\"));", "}" ] } } ], "request": { "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "sb_live_gecersiz", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/v1/quota", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "quota" ] }, "description": "Bilinmeyen, süresi dolmuş ya da iptal edilmiş anahtar." } }, { "name": "İl eksik → 400", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 400\", () => pm.response.to.have.status(400));", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "city zorunludur." } }, { "name": "Geçersiz il → 400", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const rateLimited = pm.response.code === 429 && (() => { try { return pm.response.json().code; } catch (e) { return null; } })() === \"rate_limited\";", "if (!rateLimited) {", " pm.test(\"HTTP 400\", () => pm.response.to.have.status(400));", " pm.test(\"code: invalid_city\", () => pm.expect(pm.response.json().code).to.eql(\"invalid_city\"));", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"keyword\": \"kuaför\",\n \"city\": \"Istnbul\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{baseUrl}}/api/v1/searches", "host": [ "{{baseUrl}}" ], "path": [ "api", "v1", "searches" ] }, "description": "city, 81 ilden biri olmalı." } } ] } ] }