Entegrasyon rehberi

Bu doküman, sistemi satın alan bir firmanın (mobilyacı) tasarım aracını kendi web sitesine veya yazılımına nasıl bağlayacağını anlatır. Firma panelindeki Entegrasyon sayfası aynı bilgileri, firmanın kendi anahtarlarıyla hazır kod örnekleri olarak gösterir.

Üç yol var:

Yol Ne zaman Çizim nerede yapılır Sipariş nerede oluşur
1. Gömme kodu Firmanın kendi sitesi var Bizim sunucumuzda (iframe) Ayara göre: bizde, firmanın sitesinde ya da hiç
2. Hazır firma sitesi Firmanın sitesi yok Bizim sunucumuzda Bizde (firma panelinde)
3. REST API Firma kendi arayüzünü / yazılımını kullanıyor Bizim sunucumuzda (hesap + SVG çizim) Firmanın sisteminde

Her durumda fiyat, kesim listesi, aksesuar listesi ve çizimler firmanın kendi malzeme, fiyat ve üretim kurallarıyla hesaplanır.


1. Gömme kodu

Sitenin tasarım aracının görüneceği yere şu kodu ekleyin (WordPress'te "Özel HTML" bloğu):

<div id="furn-designer"></div>
<script src="https://furn.catlibtech.com/embed.js" data-key="pk_FIRMA_ANAHTARI" data-target="#furn-designer" async></script>
Özellik Açıklama
data-key Firmanın herkese açık anahtarı (pk_...). Gizli değildir.
data-target Aracın yerleşeceği eleman. Yoksa script'in olduğu yere eklenir.
data-min-height En küçük yükseklik (px, varsayılan 720). Araç içeriğe göre büyür.
data-product banyo: banyo dolabı tasarımı (lavabo dolabı, ayna dolabı, boy dolabı); gardirop: gardırop (menteşeli veya sürgülü kapaklı). Verilmezse mutfak. Her ürün için ayrı sayfada ayrı kod kullanılabilir; gömülü araçta ürün değiştirme düğmesi yoktur.
data-mode inline (varsayılan, sayfaya gömülü), button (düğme ve tam ekran pencere) veya popup (yalnızca sizin bağlantılarınız açar). Aşağıya bakın.

Düğmeyle tam ekran açma

Sayfanızda yer ayırmak istemezseniz araç bir düğmeyle tam ekran pencerede açılır:

<script src="https://furn.catlibtech.com/embed.js" data-key="pk_FIRMA_ANAHTARI" data-mode="button" data-button-text="Mutfağını tasarla" async></script>

Kendi düğmeleriniz veya menü bağlantılarınız varsa data-mode="popup" ile yalnızca script'i ekleyin ve bağlantılara data-furn-open yazın (değer verilmezse data-product, o da yoksa mutfak açılır):

<script src="https://furn.catlibtech.com/embed.js" data-key="pk_FIRMA_ANAHTARI" data-mode="popup" async></script>

<a href="#" data-furn-open>Mutfağını tasarla</a>
<a href="#" data-furn-open="banyo">Banyo dolabını tasarla</a>
<a href="#" data-furn-open="gardirop">Gardırobunu tasarla</a>
Özellik Açıklama
data-button-text Düğme yazısı. Varsayılan ürüne göre "Mutfağını tasarla", "Banyonu tasarla" veya "Gardırobunu tasarla".
data-button-color Düğme rengi (ör. #8a5a2b).
data-button-class Kendi CSS sınıfınız; verilirse hazır düğme stili kullanılmaz.
data-target button modunda düğmenin yerleşeceği eleman.

JavaScript ile de açılır: FurnDesigner.open(), FurnDesigner.open('banyo'), FurnDesigner.open('gardirop'), FurnDesigner.close(). Pencere Esc tuşuyla, "Kapat" düğmesiyle veya dışına tıklanınca kapanır; kapatmak tasarımı silmez, yeniden açıldığında müşteri kaldığı yerden devam eder. Telefonlarda pencere tüm ekranı kaplar.

Güvenlik

Panelde Entegrasyon → Aracı gömebilecek siteler alanına kendi sitenizi yazın (ör. https://www.firmaniz.com). Yazılırsa araç yalnızca bu sitelerde açılır (Content-Security-Policy: frame-ancestors) ve olaylar yalnızca bu sitelere gönderilir. Boş bırakılırsa her site gömebilir.

Sipariş modları

Mod Davranış
Sipariş bu sistemde oluşsun Müşteri iletişim bilgilerini girip siparişi verir. Sipariş firma panelinde görünür, kapora havale/EFT ile alınır. Gömülü araçta üyelik istenmez.
Sonuçları siteme gönder Sipariş bizde oluşmaz. Müşteri "Tasarımı gönder" deyince sonuç sayfanıza olay olarak gelir; kesim listesi ve fiyat dahil tüm veri API ve webhook ile alınır. Tasarım bir süre (varsayılan 30 gün) saklanır.
Sadece görüntüle Müşteri yalnızca tasarlar ve çizimi görür.

Fiyat gösterilsin kapatılırsa müşteri fiyat görmez (firma API'de yine görür).

Olaylar

Araç bulunduğu sayfaya postMessage ile olay gönderir. embed.js bunları iki şekilde sunar (DOM olayları document'e kadar yükselir; document.addEventListener('furn:order', ...) her modda çalışır):

window.FurnDesigner.on('result', function (data) {
  // data.code         -> tasarım kodu (API ile tüm veriyi almak için)
  // data.accessKey    -> bu tasarımın gizli erişim anahtarı (SVG/CSV linkleri için)
  // data.simulationUrl-> fotoğraf üzerindeki simülasyon görseli
  // data.price        -> { total, deposit, currency } (fiyat gösterimi açıksa)
  // data.modules      -> [{ label, type, description }]
});

document.getElementById('furn-designer').addEventListener('furn:order', function (e) {
  console.log('Sipariş', e.detail.code, e.detail.total);
});
Olay Ne zaman Veri
ready Araç yüklendi { mode }
step Adım değişti { step: "photo" \| "wall" \| "design" \| "quote" \| "order" }
quote Fiyat yeniden hesaplandı { total, currency, valid } (fiyat gösterimi açıksa)
result "Sonuçları siteme gönder" modunda tasarım gönderildi yukarıdaki gibi
order "Bu sistemde sipariş" modunda sipariş verildi { code, total, deposit }
open / close Tam ekran pencere açıldı / kapandı (button ve popup modları) { product } / {}

Tipik akış ("sipariş bizde oluşmasın"): sayfanız result olayını alır, code değerini kendi sunucunuza gönderir; sunucunuz GET /api/v1/designs/{code} ile fiyatı, parça ve aksesuar listesini alır ve siparişi kendi sisteminizde oluşturur.


2. Hazır firma sitesi ve kendi alan adı

Her firmanın sitesi hemen https://furn.catlibtech.com/f/firma-adi adresinde yayındadır: kapak, hakkımızda, hizmetler, galeri, iletişim, tasarım aracı, müşteri üyeliği ve sipariş takibi. İçerik firma panelinde Ayarlar → Web sitesi ve Firma ve ödeme bilgileri sayfalarından düzenlenir.

Firmanın kendi alan adında (ör. www.firmaniz.com) açmak için:

  1. Alan adının DNS kaydını platformun sunucusuna yönlendirin (hosting firmanızın verdiği IP için A kaydı ya da CNAME).
  2. Hosting panelinde (Plesk vb.) bu alan adını platform sitesine alan adı takma adı (alias) olarak ekleyin ve SSL sertifikası (Let's Encrypt) alın.
  3. Platform yönetiminde Firmalar → firma → Alan adları alanına firmaniz.com, www.firmaniz.com yazın.

Sistem gelen isteğin alan adına bakarak firmanın sitesini gösterir. Müşteri oturumları her alan adında ayrıdır.


3. REST API

  • Taban adres: https://furn.catlibtech.com/api/v1
  • Kimlik doğrulama: Authorization: Bearer fk_... (veya X-Api-Key: fk_...). Anahtarlar panelde Entegrasyon → API anahtarları bölümünden oluşturulur ve yalnızca bir kez gösterilir. Anahtarı yalnızca sunucunuzda saklayın.
  • İstek ve yanıtlar JSON, ölçüler tasarımda cm, hesap sonuçlarında mm.
  • Hız sınırı: anahtar başına dakikada 120 istek. Aşılırsa 429.
  • Hata biçimi: { "error": "kod", "message": "Türkçe açıklama" }.

Uç noktalar

Metot Adres Açıklama
GET /catalog Modül tipleri, genişlikler, açılış tipleri, malzemeler, kapak modelleri, kulplar, tezgah görünümleri (?productLine=bathroom veya wardrobe ile o hattın kuralları)
POST /designs/calculate Kaydetmeden hesapla
POST /designs Tasarımı kaydet (panelde açılıp düzenlenebilir)
GET /designs/{kod} Kayıtlı tasarım veya sipariş
PUT /designs/{kod} Tasarımı güncelle (sipariş olmamışsa)
GET /designs/{kod}/elevation.svg Ölçülü ön görünüş çizimi (?wall=1 ikinci duvar, ?wall=-1 ada)
GET /designs/{kod}/plan.svg Üstten plan: duvarlar, köşe dolapları, ada (üst dolaplar kesikli)
GET /designs/{kod}/cutlist.csv Kesim listesi (?view=modules ile modül bazlı)
GET /orders Siparişler (?status=Quote&since=2026-01-01&limit=100)
PUT /orders/{kod}/status Sipariş durumunu güncelle
GET /appointments/kinds Randevu türleri, kurallar (Randevular)
GET /appointments/days, /appointments/slots Boş günler ve saatler
POST /appointments Randevu oluştur
GET /appointments, /appointments/{kod} Randevular
PUT /appointments/{kod}/status Randevu durumunu güncelle

/catalog yanıtında her modül tipinin kabul ettiği açılışlar moduleTypes[].openings içindedir (klapa yalnızca üst dolap ve üst kutuda; çekmece, dolgu ve boşlukta açılış yok). Gardırop kataloğunda maxWalls 1'dir ve corners boştur (null).

SVG ve CSV adresleri API anahtarı yerine ?k=ERISIM_ANAHTARI ile de açılır (<img src="..."> içinde kullanmak için). Erişim anahtarı tasarım yanıtında accessKey alanındadır.

Tasarım belgesi (sürüm 2)

Bir mutfak, soldan sağa sıralı duvarlardan (tek duvar, L veya U), komşu duvarlar arasındaki köşe birleşimlerinden ve isteğe bağlı bir adadan oluşur. Odanın içinden bakıldığında walls[i] duvarının sağ ucu walls[i+1] duvarının sol ucuyla iç köşede birleşir; joints[i] o köşede ne yapılacağını söyler.

{
  "version": 2,
  "options": { "bodyMaterial": "GOVDE-BEYAZ", "counterToWallGapCm": 60, "countertop": "beyaz" },
  "photos": [ { "width": 1600, "height": 1200 } ],
  "walls": [
    {
      "name": "Pencere duvarı",
      "widthCm": 300, "heightCm": 260,
      "photo": 0,
      "corners": [[280,167],[1367,220],[1340,1000],[300,1047]],
      "lower": [
        { "type": "drawer", "widthCm": 60, "drawers": 3, "front": "KAPAK-MESE", "handle": "KULP-128" },
        { "type": "gap", "widthCm": 60, "label": "Bulaşık makinesi", "counter": true },
        { "type": "base", "widthCm": 60 }
      ],
      "upper": [ { "type": "wall", "widthCm": 60, "opening": "flap", "style": "CAMLI" } ]
    },
    {
      "widthCm": 240, "heightCm": 260,
      "lower": [ { "type": "base", "widthCm": 80, "opening": "double" }, { "type": "tall", "widthCm": 60 } ],
      "upper": [ { "type": "wall", "widthCm": 60 } ]
    }
  ],
  "joints": [
    { "lower": { "type": "l", "sizeCm": 90, "accessory": "carousel" }, "upper": { "type": "diagonal", "sizeCm": 60 } }
  ],
  "island": {
    "wall": 0, "offsetCm": 60, "gapCm": 110, "finishPanels": true,
    "modules": [ { "type": "drawer", "widthCm": 60 }, { "type": "base", "widthCm": 90 } ]
  }
}
Alan Açıklama
walls[].widthCm, heightCm İşaretlenen alanın gerçek ölçüsü (alt kenar zemin). Köşeye komşu duvarlarda alan köşeye kadar uzanmalıdır.
walls[].photo, corners İsteğe bağlı: fotoğraf sırası (photos listesinde) ve o fotoğrafta alanın köşeleri (sol üst, sağ üst, sağ alt, sol alt; piksel). Tek fotoğrafta birden çok duvar işaretlenebilir ya da her duvar kendi fotoğrafını kullanabilir.
walls[].lower / upper Duvarın kendi modülleri, soldan sağa. Köşe dolaplarından kalan alana dizilir; üst sıra boy dolaplarının üstünü atlar.
type base alt dolap, drawer çekmeceli alt dolap, tall boy dolabı, wall üst dolap, filler dolgu paneli, gap boşluk
widthCm Dolaplarda katalogdaki genişliklerden biri; dolgu ve boşlukta serbest
front, style, handle Katalog kodları. Boşsa firmanın varsayılanı. Kulpsuz için "none".
opening auto, left, right, double, flap (yalnızca üst dolap), open (kapaksız)
drawers Çekmece sayısı (2–4)
joints[].lower / upper Köşe düzeni (aşağıdaki tablo). Verilmezse alt ve üstte L köşe kullanılır.
island Ada: wall önünde durduğu duvar, offsetCm o duvarın sol ucundan başlangıcı, gapCm tezgah önü ile ada arası geçit, finishPanels arka ve yanlarda kapak malzemesinden bitiş paneli. Modüller kapak tarafından bakıldığında soldan sağa.

Köşe tipleri (type):

Tip Sıra Ne üretilir
l alt, üst İki gövdeli L köşe dolabı (iki arkalık), katlanır iki kanatlı kapak, tek kulp. sizeCm her kolun köşeden ölçüsü (katalogdaki listeden). owner: ana gövdenin duvarı (a sol, b sağ), hinge: gövdeye takılan kanadın duvarı. Altta accessory: "carousel" ile karusel.
blind alt, üst Kör köşe: owner duvarındaki sizeCm genişliğinde dolap köşenin içine uzanır; diğer sıra köşeden derinlik + kapak payı kadar sonra 5 cm dolgu ile başlar. Altta accessory: "magic" ile sihirli köşe.
dead alt, üst Ölü köşe: köşe boş kalır, iki sıra da dolgu panelle biter.
diagonal yalnız üst 45° kapaklı çapraz köşe dolabı (beşgen taban/tavan/raf).
none alt, üst Köşe dolabı yok; iki sıra köşede birbirine çarpmamalıdır.

Sürüm 1 belgeler (tek wall ve lower/upper) hâlâ kabul edilir ve otomatik olarak sürüm 2'ye çevrilir; yanıtlarda tasarım her zaman sürüm 2 döner.

Ürün hattı: mutfak, banyo ve gardırop

productLine belgenin ürün hattıdır: kitchen (varsayılan), bathroom veya wardrobe. Banyo dolapları ve gardıroplar aynı belgeyle ve aynı motorla, firmanın Banyo kuralları ve Gardırop kuralları ölçüleriyle hesaplanır:

{
  "version": 2,
  "productLine": "bathroom",
  "walls": [ { "widthCm": 160, "heightCm": 250,
    "lower": [ { "type": "sink", "widthCm": 80 }, { "type": "drawer", "widthCm": 40 }, { "type": "gap", "widthCm": 40, "label": "Çamaşır makinesi" } ],
    "upper": [ { "type": "mirror", "widthCm": 80 }, { "type": "wall", "widthCm": 40 } ] } ]
}
Tip Ne üretilir
sink Lavabo dolabı (mutfakta eviye dolabı): üstte ön ve arka kuşak, arkalık yok (tesisat için), raf yok, yalnızca kapak. Mutfakta da kullanılabilir.
mirror Ayna dolabı: üst sırada, üst dolap derinliğinde; kapakları varsayılan olarak firmanın ayna kapak malzemesidir (AYNA-KAPAK, katalogda yoksa normal kapak). Klapa açılış olmaz.
  • Banyo kurallarında alt dolaplar varsayılan olarak duvara asılıdır: baza ve ayak yoktur, her dolaba askı aparatı eklenir. layout.plinthHeightMm bu durumda dolabın yerden yüksekliğidir (varsayılan 38 cm).
  • Boy dolabı da aynı yükseklikte asılır ve ayna dolaplarının üst hizasına kadar çıkar.
  • Banyo tasarımında ada olmaz (400 island_not_allowed). Tanınmayan ürün hattı 400 invalid_product_line döner.
  • Otomatik doldurma banyoda ana duvara önce lavabo dolabını (60 cm), üstüne ayna dolabını koyar; dishwasherGapCm banyoda çamaşır makinesi boşluğudur.

Gardırop

Gardırop tek duvara yerleşir (ada ve köşe yok). Alt sıra bölmelerdir, üst sıra tavana kadar uzanan üst kutulardır:

{
  "version": 2,
  "productLine": "wardrobe",
  "options": { "doors": "sliding", "slidingDoorCount": 3, "slidingFront": "KAPAK-BEYAZ-PARLAK" },
  "walls": [ { "widthCm": 250, "heightCm": 260,
    "lower": [ { "type": "wardrobe", "widthCm": 100, "interior": "hanging" },
               { "type": "wardrobe", "widthCm": 100, "interior": "drawers", "drawers": 3 },
               { "type": "wardrobe", "widthCm": 50, "interior": "shelves" } ],
    "upper": [ { "type": "topbox", "widthCm": 100 }, { "type": "topbox", "widthCm": 100, "opening": "flap" }, { "type": "topbox", "widthCm": 50 } ] } ]
}
Alan Açıklama
type: "wardrobe" Gardırop bölmesi: bazalı, tam boy gövde (varsayılan 220 cm, derinlik 60 cm).
interior hanging (şapka rafı ve askı borusu), double-hanging (iki askı, ortada sabit raf), shelves (ayarlı raflar, yaklaşık 35 cm arayla), drawers (altta drawers adet iç çekmece, üstünde raf ve askı).
type: "topbox" Üst kutu: bölmelerin üstünde, tavana kadar (en fazla 60 cm, tavana 1 cm); açılış auto, left, right, double, flap. Tavana kadar 20 cm'den az yer varsa hata verir.
options.doors hinged (varsayılan: her bölmenin kendi kapakları, tam boy) veya sliding.
options.slidingDoorCount Sürgülü kapak sayısı 2–6; verilmezse hiçbir kapak 100 cm'yi geçmeyecek şekilde.
options.slidingFront Sürgülü kapak malzemesi; verilmezse varsayılan kapak.
  • Sürgülü kapaklar ilk bölmeden son bölmeye kadar uzanır (aralarında gap olamaz), 3 cm bindirir ve sırayla arka ve ön rayda durur. Yanıtta type: "sliding-door" modülleri (SK1, SK2…) olarak gelir; fiyatta tek satırdır ("Sürgülü kapak sistemi"). Bölmelerin kendi kapağı olmaz.
  • İç düzen yanıttaki her bölmede interior ve interiorElements (kind: fixedShelf, shelf, rail, drawer; yMm gövde altından) olarak döner. Çizimlerde interior anahtarlı ayrı bir İç düzen çizimi vardır.
  • Aksesuarlar: askı borusu (spec = boy, mm) ve iki tutucu, sürgü rayı (alt ve üst, spec = boy), kapak başına tekerlek takımı, iç çekmece rayları. Birimi m olan aksesuarın fiyatı boyla çarpılır (ör. 2 500 mm ray × metre fiyatı).
  • Gardırop tasarımında mutfak ve banyo modülleri, mutfak ve banyoda gardırop modülleri kullanılamaz (type-line hatası); birden çok duvar 400 too_many_walls döner.

Otomatik doldurma

Marangozun hiç çizim yapmadan başlaması için duvar ölçüsünü verip autoFill ekleyin:

curl -X POST https://furn.catlibtech.com/api/v1/designs/calculate \
  -H "Authorization: Bearer fk_..." -H "Content-Type: application/json" \
  -d '{ "design": { "walls": [ { "widthCm": 360, "heightCm": 260 } ] },
        "autoFill": { "includeUpper": true, "includeTall": true, "includeDrawer": true, "dishwasherGapCm": 60 } }'

L veya U mutfakta önce duvarları ve köşe tiplerini verin; otomatik doldurma köşe dolaplarından kalan alanları doldurur. En uzun duvara çekmece ve bulaşık makinesi boşluğu, boy dolabı son duvarın sağ ucuna konur.

Sonra dönen design üzerinde istediğiniz değişikliği yapıp tekrar hesaplatın ya da POST /designs ile kaydedip panelde Tasarımı düzenle ekranında değiştirin (editUrl).

Hesap sonucu (özet)

{
  "valid": true,
  "issues": [ { "severity": "warning", "code": "...", "message": "..." } ],
  "suggestions": [ { "row": "lower", "moduleWidthCm": 0, "fillerWidthCm": 4, "message": "Alt sırada 4 cm boşluk var: dolgu paneli önerilir." } ],
  "design": { "...": "otomatik doldurulmuşsa son hali" },
  "layout": {
    "walls": [ { "index": 0, "title": "Duvar 1", "widthMm": 3000, "lowerStartMm": 0, "lowerLimitMm": 2100, "zones": [ ... ] } ],
    "corners": [ { "joint": 0, "row": "lower", "type": "l", "label": "K1", "description": "L köşe dolabı 90×90 cm, katlanır kapak" } ],
    "island": { "wall": 0, "lengthMm": 1500, "overallLengthMm": 1536, "overallDepthMm": 596 },
    "plan": { "walls": [ ... ], "shapes": [ { "kind": "base", "label": "A1", "points": [ { "x": 0, "z": 0 }, ... ] } ] },
    "modules": [ { "label": "A1", "type": "drawer", "wall": 0, "xMm": 0, "yMm": 100, "widthMm": 600, "group": null, "fronts": [ ... ] } ]
  },
  "price": { "lines": [ ... ], "subtotal": 38954, "vat": 7791, "total": 46745, "deposit": 14024, "currency": "TL", "totalCost": 29966 },
  "cutList": [ { "part": "Yan", "material": "GOVDE-BEYAZ", "thicknessMm": 18, "cutLengthMm": 720, "cutWidthMm": 552, "quantity": 8,
                 "bandedLengthEdges": 1, "bandedWidthEdges": 0, "edgeBand": "BANT-04", "grainLocked": false, "modules": ["A1","A2"] } ],
  "partsByModule": [ { "module": "A1", "parts": [ ... ] } ],
  "accessories": [ { "kind": "Hinge", "name": "Menteşe", "code": "MENTESE", "quantity": 22 } ],
  "totals": { "parts": 82, "areaM2": 21.79 },
  "elevationSvg": "<svg ...>",
  "overlaySvg": "<svg ...>",
  "drawings": [ { "key": "plan", "title": "Plan", "svg": "<svg ...>" }, { "key": "w0", "title": "Duvar 1", "svg": "<svg ...>" } ],
  "overlaySvgs": [ "<svg ...>", null ]
}
  • Köşe düzenleri birden çok modül üretir (L köşede K1a ve K1b iki gövde, kör köşede dolap ve dolgu). Bunlar aynı group değerini taşır ve fiyatta tek satırdır.
  • Kesim listesinde çapraz köşe dolabının taban, tavan ve rafı beşgendir: ölçü dikdörtgenin ölçüsüdür, notta 45° kesilecek köşe ve bantlı kenar uzunluğu yazar.
  • Ada bitiş panelleri ve bazası ADA ve BAZA etiketli genel parçalardır.
  • plan koordinatları mm'dir: x sağa, z odanın içine doğru; üç ve daha fazla duvarda ortadaki duvar üstte çizilir.

Kesim listesinde boy her zaman desen (damar) yönüdür. cutLengthMm / cutWidthMm kesim ölçüsüdür (kalın bantlar düşülmüş); lengthMm / widthMm bitmiş ölçüdür. bandedLengthEdges boy yönündeki bantlı kenar sayısıdır.

Sipariş durumu

curl -X PUT https://furn.catlibtech.com/api/v1/orders/K7F3QX9M/status \
  -H "Authorization: Bearer fk_..." -H "Content-Type: application/json" \
  -d '{ "status": "InProduction", "note": "Kesime girdi", "notify": true }'

Durumlar: Quote (teklif, kapora bekleniyor), DepositReceived, SiteMeasurement, InProduction, Delivered, Cancelled.

Randevular

Müşteriler sitenizdeki Randevu al sayfasından yerinde ölçü, mağaza ziyareti veya görüşme randevusu alır; türler, çalışma saatleri, kapasite ve kapalı günler panelde Ayarlar → Randevu sayfasındadır. Aynı randevular API ile de alınır ve yönetilir. Saatler Türkiye saatidir ("2026-11-10T14:00"); startsAtUtc aynı anın UTC karşılığıdır.

Üç adımda randevu:

# 1. Türler ve kurallar
curl https://furn.catlibtech.com/api/v1/appointments/kinds -H "Authorization: Bearer fk_..."
# 2. Boş günler, sonra seçilen günün boş saatleri
curl "https://furn.catlibtech.com/api/v1/appointments/days?kind=olcu" -H "Authorization: Bearer fk_..."
curl "https://furn.catlibtech.com/api/v1/appointments/slots?kind=olcu&date=2026-11-10" -H "Authorization: Bearer fk_..."
# 3. Randevuyu oluştur
curl -X POST https://furn.catlibtech.com/api/v1/appointments \
  -H "Authorization: Bearer fk_..." -H "Content-Type: application/json" \
  -d '{ "kind": "olcu", "start": "2026-11-10T14:00", "name": "Ayşe Yılmaz", "phone": "05321234567",
        "email": "ayse@ornek.com", "address": "Atatürk Cad. No 5", "city": "Kadıköy", "projectCode": "K7F3QX9M" }'
Alan Açıklama
kind kinds listesindeki key (varsayılanlar: olcu yerinde ölçü, magaza mağaza ziyareti, gorusme telefon/online görüşme).
start slots yanıtındaki start (Türkiye saati) ya da saat dilimli ISO zaman (2026-11-10T11:00:00Z).
name, phone Zorunlu. Yerinde ölçüde address da zorunludur.
email İsteğe bağlı; verilirse müşteriye onay e-postası ve takvim dosyası gider.
projectCode İsteğe bağlı: randevunun ilgili olduğu tasarım veya sipariş.
notify false verilirse müşteriye e-posta gitmez (varsayılan true). Firmaya bildirim her zaman gider.
  • Yanıt 201: { code, kind, kindName, place, status, statusText, start, end, startsAtUtc, endsAtUtc, contact, source, projectCode, manageUrl, createdAt }. manageUrl, müşterinin randevusunu görüp iptal edebileceği ve takvimine ekleyebileceği bağlantıdır.
  • Saat bu arada dolduysa 409 slot_taken; geçersiz tür, saat veya eksik bilgi 400.
  • Durum Requested (firma onayı bekliyor) olur; panelde "otomatik onay" açıksa doğrudan Confirmed. API randevuları, sitede online randevu kapalı olsa da alınır (en az önceden bildirim ve en fazla gün kuralları yine geçerlidir).
  • Durum değiştirme: PUT /appointments/{kod}/status gövdesi { "status": "Confirmed", "note": "...", "notify": true }. Durumlar: Requested, Confirmed, Completed, Cancelled, NoShow. Onay ve iptalde notify ile müşteriye e-posta gider.

4. Webhook

Panelde bir webhook adresi girilirse şu olaylarda o adrese POST (JSON) gönderilir:

Olay (X-Furn-Event) Ne zaman
order.created Bu sistemde sipariş oluştu
design.created "Sonuçları siteme gönder" modunda müşteri tasarımı gönderdi
order.status_changed Sipariş durumu değişti
appointment.created Randevu alındı (site, panel veya API)
appointment.status_changed Randevu onaylandı, iptal edildi, tamamlandı veya gelinmedi

Gövde: { "type": "...", "createdAt": "...", "data": { ... } }. Randevu olaylarında data, GET /appointments/{kod} yanıtıyla aynıdır. Sipariş ve tasarım olaylarında data, GET /designs/{kod} yanıtındaki proje verisiyle aynıdır (fiyat, parçalar, aksesuarlar, dosya linkleri). files içinde duvar başına ön görünüşler (elevationSvgs), plan (planSvg) ve fotoğraflar (photos; saklama süresi dolunca boşalır, photosDeletedAt dolar) bulunur.

İmza: X-Furn-Signature: sha256=<gövdenin HMAC-SHA256 değeri> (anahtar: paneldeki webhook imza anahtarı). Doğrulama örnekleri:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, 'whsec_...');
if (!hash_equals($expected, $_SERVER['HTTP_X_FURN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);
const sig = 'sha256=' + crypto.createHmac('sha256', 'whsec_...').update(rawBody).digest('hex');
const given = Buffer.from(req.headers['x-furn-signature'] || '');
const ok = given.length === Buffer.byteLength(sig) && crypto.timingSafeEqual(Buffer.from(sig), given);
var body = await new StreamReader(Request.Body).ReadToEndAsync();
var expected = "sha256=" + Convert.ToHexStringLower(HMACSHA256.HashData(Encoding.UTF8.GetBytes("whsec_..."), Encoding.UTF8.GetBytes(body)));
var ok = CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(Request.Headers["X-Furn-Signature"].ToString()));

Webhook isteği 6 saniye içinde yanıt bekler ve tekrar denenmez; kritik veriyi GET /api/v1/designs/{kod} ile her zaman tekrar alabilirsiniz.