Alpiko API v1

Kendi yazılımınızın, randevu programınızın ya da yapay zekâ ajanınızın Alpiko’yu kullanması için: yapay zekâ cevabı, bilgi tabanı, randevu, SMS doğrulama kodu. Makine okunur tanım: openapi.json

Üye ol ve ücretsiz dene

1. panel.alpiko.com.tr adresinde Üye ol (e-posta onayı gerekir; kart istenmez).
2. 7 gün ve 50 yapay zekâ yanıtı ücretsiz. Süre ya da hak dolunca API 402 payment_required döner; panelden kontör yükleyerek devam edersiniz.
3. Panelde anahtar üretin (aşağıda).

Başlarken

1. Alpiko panelinde Randevular → Dışarıdan bağlanma (API) → Yeni anahtar üret. Anahtar yalnız bir kez gösterilir.
2. Her isteğe Authorization: Bearer alp_live_… başlığını ekleyin.
3. Adres: https://rbtugfywsrhfxjeiffes.supabase.co/functions/v1/public-api/v1/…

Anahtar yalnız sunucunuzdan kullanılmalı (tarayıcıya, mobil uygulamaya gömmeyin). Her anahtar tek bir işletmeye bağlıdır; başka işletmenin verisine erişemez. Sınır: dakikada 60 istek (aşılırsa 429).

Yapay zekâ ile sohbet chat:write

POST /v1/chat Müşterinizin (ya da yapay zekâ ajanınızın) sorusunu işletmenizin bilgi tabanı ve ayarlarıyla cevaplar. Aynı user_id aynı konuşmayı sürdürür; konuşmalar panelde gelen kutusunda görünür. Her bot yanıtı bir kontör/deneme hakkı düşer.

curl -X POST -H "Authorization: Bearer $ALPIKO_KEY" -H "content-type: application/json" \
  -d '{"user_id":"musteri-123","message":"Cumartesi açık mısınız?"}' \
  "$BASE/v1/chat"

{ "replies":["Cumartesi 10:00–17:00 arası açığız."], "handoff":false, "appointment":false }

message en çok 1000 karakter. user_id sizin kullanıcı kimliğiniz (1-64 karakter). Bir user_id günde en çok 40 mesaj gönderebilir; işletme günlük 600 mesaj ve maliyet sınırına tabidir (429). handoff:true ise konuşma insana devredildi.

Bilgi tabanı sorgusu knowledge:read

GET /v1/knowledge?q=çalışma saatleri Yayındaki bilgi kayıtlarından en uygun 10 tanesini döner: {"data":[{"key","content","language"}]}

Boş saatler

GET /v1/availability?date=2026-10-26&duration=30

curl -H "Authorization: Bearer $ALPIKO_KEY" \
  "$BASE/v1/availability?date=2026-10-26&duration=45"

{ "date":"2026-10-26","timezone":"Europe/Istanbul","duration_min":45,"slot_step_min":30,"capacity":1,
  "slots":["2026-10-26T06:00:00.000Z","2026-10-26T06:30:00.000Z", …] }

Saatler UTC verilir. Çalışma saatleri ve kapasite panelden ayarlanır.

Randevu oluştur

POST /v1/appointments

curl -X POST -H "Authorization: Bearer $ALPIKO_KEY" -H "content-type: application/json" \
  -d '{"start":"2026-10-26T10:00:00+03:00","duration_min":45,"status":"confirmed",
       "customer":{"name":"Ayşe Yılmaz","phone":"+905321234567"},
       "service":"Cilt bakımı","external_id":"SIZIN-123"}' \
  "$BASE/v1/appointments"

Randevu oku, güncelle, iptal et

Durumlar: request, confirmed, cancelled, completed, no_show.

Bildirimler (webhook)

Panelde Bildirim adresi (webhook) ekleyin. Randevu oluşunca, değişince ya da iptal edilince adresinize POST gelir. Olaylar: appointment.created, appointment.updated, appointment.cancelled (ve test için ping). Başka kaynaktan (bot, panel, telefon, API) gelen her değişiklik bildirilir; kendi yazdığınız randevunun bildirimini source: "api" ile ayırabilirsiniz.

POST https://sirketiniz.com/alpiko-bildirim
Alpiko-Event: appointment.created
Alpiko-Delivery: 5b0c…            (tekrar eden bildirimi ayıklamak için)
Alpiko-Signature: t=1761300000,v1=9f2c…

{ "event":"appointment.created","id":"…","status":"request","start":"2026-10-26T07:00:00+00:00",
  "end":"2026-10-26T08:00:00+00:00","duration_min":60,"service":"Cilt bakımı","staff":null,"note":null,
  "source":"telefon","external_id":null,"customer":{"name":"Ayşe Yılmaz","phone":"+905321234567"} }

İmzayı doğrulama

İmza, t + "." + ham gövde metninin, ekranda bir kez gösterilen whsec_… anahtarıyla HMAC-SHA256 özetidir (hex). Gövdeyi değiştirmeden, ham haliyle kullanın; t değeri 5 dakikadan eskiyse reddedin.

const crypto = require("crypto");
function dogru(rawBody, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  if (Math.abs(Date.now()/1000 - Number(t)) > 300) return false;
  const beklenen = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(beklenen), Buffer.from(v1));
}

2xx dönün; aksi halde 1 dk, 5 dk, 30 dk, 2 sa, 6 sa arayla toplam 6 kez denenir. Art arda 50 hata olursa adres kapatılır. Adres yalnız https:// olabilir; yerel/özel ağ adresleri kabul edilmez. Yönlendirme (3xx) izlenmez. Bildirimler en az bir kez ulaşır (bazen iki kez gelebilir): Alpiko-Delivery ile tekrarı atlayın.

Doğrulama kodu (OTP) SMS'i

Kendi SMS firma hesabınız (panelde Hizmetler → SMS) üzerinden 6 haneli tek kullanımlık kod gönderir ve doğrular. Kod 5 dakika geçerlidir; aynı numaraya 10 dakikada en çok 3 kod gönderilir; 5 yanlış denemede kod kilitlenir. Anahtarın otp:send izni olmalıdır (yeni anahtarlarda hazırdır).

curl -X POST "$BASE/v1/otp/send" -H "Authorization: Bearer $ANAHTAR" -H "Content-Type: application/json" \
  -d '{"phone":"+905321234567"}'
# → { "ok": true, "id": 12, "expires_in": 300 }

curl -X POST "$BASE/v1/otp/verify" -H "Authorization: Bearer $ANAHTAR" -H "Content-Type: application/json" \
  -d '{"phone":"+905321234567","code":"123456"}'
# → { "ok": true, "valid": true }   (yanlışsa: { "ok": false, "valid": false, "reason": "wrong_code", "tries_left": 4 })

Telefon +90… gibi ülke koduyla ya da Türkiye için 05321234567 biçiminde yazılır. Mesaj metnini panelde {{code}} içeren bir şablonla değiştirebilirsiniz.

Hatalar

{ "error": { "code": "slot_unavailable", "message": "Bu saat dolu…" } }

Güvenlik

Anahtarlarınız bizde yalnız şifreli özet olarak durur; kaybederseniz yenisini üretin, eskisini panelden iptal edin. Şüphe ederseniz hemen iptal edin: iptal anında geçerlidir.

Sorular için: ceo@alpiko.com.tr