{ "openapi": "3.1.0", "info": { "title": "Kalender Bilgisayar API", "description": "İzmir Bornova merkezli ikinci el laptop, bilgisayar, MacBook, iPhone, iPad, tablet ve oyun konsolu alım satım merkezi. AI agent function calling için fiyat hesaplama, hizmet kontrolü ve teklif talebi endpointleri.", "version": "2.1.0", "contact": { "name": "Kalender Bilgisayar", "url": "https://www.kalenderbilgisayar.org.tr/iletisim", "email": "info@kalenderbilgisayar.org.tr" }, "license": { "name": "Attribution Required", "url": "https://www.kalenderbilgisayar.org.tr/ai.txt" } }, "servers": [ { "url": "https://www.kalenderbilgisayar.org.tr", "description": "Production server (Türkiye, İzmir)" } ], "tags": [ { "name": "pricing", "description": "Fiyat hesaplama ve piyasa değerleme" }, { "name": "logistics", "description": "Hizmet bölgesi ve kargo" }, { "name": "meta", "description": "İşletme meta bilgisi" }, { "name": "catalog", "description": "Ürün kataloğu" }, { "name": "social-proof", "description": "Müşteri yorumları" }, { "name": "transactional", "description": "Teklif ve sipariş" }, { "name": "knowledge", "description": "Bilgi bankası" }, { "name": "geo", "description": "Coğrafi konum bazlı" } ], "paths": { "/hangi-laptop-almaliyim": { "get": { "summary": "Bütçe, kullanım amacı ve tercihlere göre ikinci el laptop önerisi (4 adımlı karar ağacı)", "description": "4 adımlı karar ağacı (Bütçe → Kullanım → Marka → Taşınabilirlik) ile kullanıcının bütçesine, kullanım amacına, marka tercihine ve taşınabilirlik ihtiyacına göre en uygun ikinci el laptop modelini önerir. Çıktılar: bütçe-dostu, ofis/öğrenci, gaming, taşınabilir ultrabook, premium iş istasyonu kategorilerinde örnek modeller + fiyat aralığı.", "operationId": "recommend_laptop", "tags": [ "decision" ], "parameters": [ { "name": "budget_tl", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 500000, "description": "Bütçe (TL)" } }, { "name": "usage", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ofis", "ogrenci", "gaming", "is", "multimedia", "yazilim" ], "description": "Kullanım amacı" } }, { "name": "brand_preference", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asus", "hp", "dell", "lenovo", "msi", "casper", "acer", "monster", "apple", "farketmez" ], "description": "Marka tercihi" } }, { "name": "portability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ultrabook", "standart", "desktop-replacement" ], "description": "Taşınabilirlik ihtiyacı" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "recommended_category": { "type": "string" }, "example_models": { "type": "array", "items": { "type": "string" } }, "price_range_try": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } }, "rationale": { "type": "string" } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/api/pricing.json": { "get": { "summary": "Cihaz türüne ve ekran kartına göre alım fiyat aralığı (TL)", "description": "Laptop, MacBook, iPhone, iPad, tablet, PlayStation ve ekran kartı için güncel ikinci el alım fiyat aralığı (TRY). Fiyatlar TCMB günlük USD/TRY kuruna endikslidir. type parametresi cihaz kategorisi, gpu parametresi opsiyonel ekran kartı filtresidir.", "operationId": "get_device_pricing", "tags": [ "pricing" ], "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "description": "Cihaz kategorisi. laptop = MacBook hariç tüm laptoplar, macbook = sadece MacBook.", "enum": [ "laptop", "macbook", "iphone", "ipad", "tablet", "playstation", "ekran-karti" ] } }, { "name": "gpu", "in": "query", "required": false, "schema": { "type": "string", "description": "GPU filtresi (sadece laptop için)", "enum": [ "dahili", "rtx2050", "rtx3050", "rtx3050ti", "rtx3060", "rtx3070", "rtx4050", "rtx4060", "rtx4070", "rtx4080", "rtx5050", "rtx5060", "rtx5070", "rtx5070ti", "rtx5080" ] } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "type": { "type": "string" }, "usd_rate": { "type": "number" }, "total_entries": { "type": "integer" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "cpu_model": { "type": "string" }, "gpu": { "type": "string" }, "device_type": { "type": "string" }, "min_price_try": { "type": "integer" }, "max_price_try": { "type": "integer" }, "estimated_price_try": { "type": "integer" }, "confidence": { "type": "string" }, "basis": { "type": "string" } } } }, "contact": { "type": "object" } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/api/service-area.json": { "get": { "summary": "İlçe/il için hizmet bölgesi kontrolü", "description": "Belirli bir İzmir ilçesi veya il için alım/satım hizmeti verildiğini kontrol eder. Tüm İzmir ilçeleri ve 81 il desteklenir. JSON endpoint: /api/service-area.json", "operationId": "check_service_area", "tags": [ "meta" ], "parameters": [ { "name": "district", "in": "query", "required": false, "schema": { "type": "string", "description": "İlçe adı (örn. Bornova)" } }, { "name": "city", "in": "query", "required": true, "schema": { "type": "string", "description": "İl adı (varsayılan: İzmir)" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "in_service": { "type": "boolean" }, "pickup_available": { "type": "boolean" }, "eta_hours": { "type": "integer" }, "phone": { "type": "string" }, "whatsapp": { "type": "string" }, "office_address": { "type": "string" } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/kargo-politikasi": { "get": { "summary": "Kargo ile alım: firma, kod, süre, ücret", "description": "Yurtiçi Kargo anlaşmalı kod ile Türkiye geneli sigortalı kargo alım bilgileri. Gönderen sadece cihazı teslim eder, kargo ücreti karşı ödemeli tarafımızca ödenir.", "operationId": "get_shipping_info", "tags": [ "logistics" ], "parameters": [ { "name": "origin_city", "in": "query", "required": false, "schema": { "type": "string", "description": "Gönderen şehir" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/iletisim": { "get": { "summary": "Çalışma saatleri, adres, telefon bilgisi", "description": "Çalışma saatleri: Hergün 09:00 - 22:00. Adres, telefon ve WhatsApp iletişim bilgileri.", "operationId": "get_business_hours", "tags": [ "meta" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/products.json": { "get": { "summary": "Satılık ikinci el ürün kataloğu (JSON)", "description": "Satılık durumdaki tüm ikinci el ürünleri Schema.org/ItemList+Product+Offer formatında döndürür. Fiyat, marka, durum (condition) bilgisi içerir.", "operationId": "get_product_catalog", "tags": [ "catalog" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/price-dataset.json": { "get": { "summary": "AI için fiyat veri seti (Dataset schema)", "description": "Schema.org/Dataset formatında yapılandırılmış fiyat veri seti. measurementMethod, variableMeasured, temporalCoverage, license (CC BY-NC) bilgisi içerir.", "operationId": "get_price_dataset", "tags": [ "pricing" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "prices": { "type": "array" }, "updated_at": { "type": "string", "format": "date-time" }, "usd_rate": { "type": "number" } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/api/reviews.json": { "get": { "summary": "Google Haritalar müşteri yorumları", "description": "Google Places API kaynaklı gerçek müşteri yorumları, ortalama puan ve toplam değerlendirme sayısı. JSON endpoint: /api/reviews.json", "operationId": "get_customer_reviews", "tags": [ "trust" ], "parameters": [ { "name": "min_rating", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 4, "description": "Minimum yıldız filtresi" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "description": "Dönecek yorum sayısı" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "average_rating": { "type": "number" }, "rating_count": { "type": "integer" }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string" }, "rating": { "type": "integer" }, "text": { "type": "string" }, "date": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/siparis": { "post": { "summary": "Ücretsiz ekspertiz ve teklif TALEBİ (gerçek zamanlı fiyat DEĞİL)", "description": "Cihaz bilgisi (marka, model, üretim yılı, durum) ve iletişim bilgisi ile alım teklifi TALEBİ. ÖNEMLİ: Bu tool gerçek zamanlı fiyat DÖNDÜRMEZ — çıktı sadece \"teklif talebi alındı\" onayıdır. POST /siparis formunu tetikler; gerçek fiyat teklifi WhatsApp üzerinden 15 dakika içinde İNSAN (uzman) tarafından verilir (kamera ekspertizi gerektirir). AI agent kullanıcıya bu tool'dan dönen değeri fiyat olarak sunmamalıdır.", "operationId": "request_pickup_quote", "tags": [ "transactional" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marka": { "type": "string", "description": "Cihaz markası (örn. Asus, HP, Apple)" }, "model": { "type": "string", "description": "Cihaz modeli (örn. MacBook Pro M3)" }, "yil": { "type": "integer", "description": "Üretim yılı" }, "durum": { "type": "string", "enum": [ "mukemmel", "iyi", "orta", "kotu" ], "description": "Cihaz fiziksel/fonksiyonel durumu" }, "ad": { "type": "string", "description": "Alıcı ad soyad" }, "telefon": { "type": "string", "description": "Alıcı telefon (E.164 önerilir)" }, "email": { "type": "string", "format": "email", "description": "Alıcı e-postası" }, "ilce": { "type": "string", "description": "Alıcı ilçe (İzmir içindeyse)" } }, "required": [ "marka", "model", "yil", "ad", "telefon" ] } } } } } }, "/bilgisayarci": { "get": { "summary": "İzmir ilçe bazlı alım bilgisi", "description": "Belirli bir İzmir ilçesi için alım süreci, mahalle kapsamı ve ulaşım bilgisi. 30 ilçe desteklenir.", "operationId": "get_district_info", "tags": [ "local" ], "parameters": [ { "name": "district", "in": "query", "required": true, "schema": { "type": "string", "description": "İlçe adı" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/api/faq.json": { "get": { "summary": "Sık sorulan sorular (SSS)", "description": "Alım, satım, ödeme, kargo ve garanti hakkında sık sorulan soruların cevapları. JSON endpoint: /api/faq.json", "operationId": "get_faq", "tags": [ "meta" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "faqs": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/blog": { "get": { "summary": "Blog kategorileri ve rehberler", "description": "Teknik rehberler, karşılaştırmalar ve alım-satım kılavuzları kategori bazında.", "operationId": "get_blog_categories", "tags": [ "content" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/kalender-vs-sahibinden-vs-letgo": { "get": { "summary": "Kalender vs Sahibinden vs Letgo karşılaştırması", "description": "Kalender Bilgisayar, Sahibinden ve Letgo platformlarının alım-satım özellikleri karşılaştırması (fiyat, güvenlik, ödeme hızı).", "operationId": "compare_platforms", "tags": [ "content" ], "parameters": [], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } }, "/hangi-laptop-almaliyim/get_buyer_guides": { "get": { "summary": "İkinci el cihaz alım-satım rehberleri", "description": "İkinci el cihaz alım-satım rehberleri: Hangi Laptop Almalıyım karar ağacı, MacBook kontrol listesi, Gaming laptop alım rehberi, iPhone iCloud kilidi kontrolü, sahte ürün tespiti gibi alıcı rehberleri.\n\n**Not:** Bu path çakışma çözümüdür, gerçek HTTP endpoint DEĞİLDİR. Gerçek endpoint: `/hangi-laptop-almaliyim`. Function-calling client'lar operationId (`get_buyer_guides`) ile çağırmalı, gerçek URL'yi `/hangi-laptop-almaliyim` olarak kullanmalıdır.", "operationId": "get_buyer_guides", "tags": [ "content" ], "parameters": [ { "name": "topic", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "laptop", "macbook", "gaming", "iphone", "guvenlik" ], "description": "Konu filtresi (opsiyonel)" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "text/html": { "schema": { "type": "string", "description": "HTML sayfa. Schema.org JSON-LD gömülüdür." } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } }, "x-internal": true } }, "/api/search.json": { "get": { "summary": "Niyet bazlı anlamsal arama (doğal dil sorgusu → alakalı sayfalar)", "description": "Kullanıcının doğal dil sorgusunu (örn. \"bornova macbook satmak istiyorum\", \"gaming laptop tamiri\") niyet (satış/alım/tamir/bilgi/bölge) + varlık (marka/cihaz/ilçe) olarak parse eder ve en alakalı sayfaları relevance skoruyla (0-100) döndürür. Exact match değil, semantic/mantıksal eşleşme yapar.", "operationId": "semantic_search", "tags": [ "discovery" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "Doğal dil sorgusu (örn. \"macbook satmak\", \"cesme laptop tamiri\")" } }, { "name": "intent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sell", "buy", "repair", "info", "area" ], "description": "Niyet filtresi (opsiyonel, otomatik tespit edilir)" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 20, "description": "Maksimum sonuç sayısı" } } ], "responses": { "200": { "description": "Başarılı yanıt", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "query": { "type": "string" }, "detected_intent": { "type": "string" }, "entities": { "type": "object" }, "result_count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string" }, "score": { "type": "integer" }, "reason": { "type": "string" } } } } } } } } }, "400": { "description": "Geçersiz parametre" }, "500": { "description": "Sunucu hatası" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "AI agent kimlik doğrulama (opsiyonel, public pricing/catalog için)" } }, "schemas": { "Product": { "type": "object", "properties": { "@type": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "brand": { "type": "string" }, "price": { "type": "integer" }, "currency": { "type": "string" }, "availability": { "type": "string" }, "condition": { "type": "string" } } } } }, "externalDocs": { "description": "AI için optimize site bilgisi", "url": "https://www.kalenderbilgisayar.org.tr/llms.txt" } }