Geliştiriciler

takv.im için bir şeyler yap

Kendi uygulamanı yaz. Kullanıcılar takv.im hesaplarını ona bağlasın. API anahtarı yok, başvuru formu yok. Uygulamanı kaydedip hemen denemeye başlayabilirsin.

Ne yapabilirsin

Şu an bir kullanıcının randevularını okuyabilirsin. Mesela randevuları kendi takvim uygulamanda gösterebilir ya da müşteri programına yazdırabilirsin. Randevu oluşturmak ve silmek yok.

ChatGPT ve Claude gibi yapay zekâ asistanları için ayrı bir yol var: MCP. Aynı izin ekranını kullanır.

Başka bir şeye ihtiyacın olursa takv.im ekibine e-posta ile yaz. Neye ihtiyacın olduğunu öğrenmek istiyoruz.

Nasıl çalışır

Dört adım. Hepsi standart OAuth 2.1, bildiğin kütüphaneler çalışır.

1. Uygulamanı kaydet (bir kere)

POST https://takv.im/oauth/mcp/register
Content-Type: application/json

{
  "client_name": "Uygulamamın adı",
  "redirect_uris": ["https://uygulamam.com/takvim/donus"],
  "client_uri": "https://uygulamam.com",
  "policy_uri": "https://uygulamam.com/gizlilik",
  "contacts": ["destek@uygulamam.com"],
  "token_endpoint_auth_method": "none"
}

Cevapta client_id gelir, onu sakla. Yönlendirme adresi https ile başlamalı (denemek için http://localhost olur). client_uri (siten), policy_uri (gizlilik sayfan) ve contacts (e-postan) zorunlu değil ama yaz: kullanıcı izin ekranında görür, doğrulama için de gerekir.

2. Kullanıcıyı takv.im'e gönder

https://takv.im/oauth/authorize?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=YONLENDIRME_ADRESI
  &scope=bookings:read
  &state=RASTGELE_DEGER
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

PKCE (S256) zorunlu. Kullanıcı giriş yapar, izinleri görür, istemediğinin işaretini kaldırabilir ve onaylar. Sonra code ve state ile senin adresine döner.

state, bu akışın CSRF korumasıdır. Her bağlantı isteği için tahmin edilemez rastgele bir değer üret, oturumunda sakla ve state olarak gönder. Kullanıcı dönünce gelen state sakladığınla aynı değilse isteği reddet. Biz değeri hiç değiştirmeden geri veririz, hata ve vazgeçme durumunda da.

3. Kodu jetona çevir

POST https://takv.im/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=CLIENT_ID&code=KOD
&redirect_uri=YONLENDIRME_ADRESI&code_verifier=VERIFIER

access_token 1 saat geçerli. refresh_token 30 gün geçerli ve her kullanımda yenilenir: yeni geleni kaydet, eskisi artık çalışmaz. Yenilemek için grant_type=refresh_token&client_id=…&refresh_token=… gönder.

4. API'yi çağır

GET https://takv.im/api/v1/bookings?from=2026-11-01&to=2026-12-01
Authorization: Bearer ERISIM_JETONU

{
  "timezone": "Europe/Istanbul",
  "has_more": false,
  "bookings": [
    {
      "id": 4821,
      "status": "confirmed",
      "type": { "id": 17, "name": "İlk görüşme" },
      "starts_at": "2026-11-05T10:00:00+03:00",
      "ends_at": "2026-11-05T10:30:00+03:00",
      "join_url": "https://meet.google.com/abc-defg-hij",
      "guest": { "name": "Ayşe Örnek", "email": "ayse@example.com" }
    }
  ]
}

from ve to: tarih aralığı. Varsayılan şimdiden 90 gün sonrasına kadar, en fazla 366 gün.
status: confirmed, pending, cancelled, rescheduled (virgülle). Varsayılan confirmed,pending.
limit (en fazla 200) ve offset: sayfalama. has_more başka sayfa olup olmadığını söyler.
Misafirin notu, özel soru cevapları ve ödeme bilgisi dönmez.
GET https://takv.im/api/v1/me bağlı hesabı gösterir.
Hatalar: 401 jeton geçersiz ya da kullanıcı bağlantıyı kesti (jetonu yenile), 403 izin yok, 429 çok istek.

İzinler

İstediğin izinler scope alanına boşlukla yazılır. REST API şu an yalnızca bookings:read ile çalışır. Diğer izinler MCP araçları içindir.

bookings:read: Randevularını görebilir: ne zaman, hangi görüşme, durumu, toplantı bağlantısı, misafirin adı ve e-postası. Değiştiremez ya da silemez.
customers:read: Müşterilerini ve randevu geçmişlerini görebilir. Notlar bu izne dahil değil.
customers:notes: Müşteri notlarını okuyabilir. Notlara sağlık gibi hassas bilgi yazdıysan işaretleme: notlar asistanı sunan şirkete gider. Yalnızca doğrulanmış uygulamalara verilir.
customers:write: Müşterilerine not ekleyebilir, müşteri grubu oluşturabilir ve müşteriyi gruba ekleyebilir. Müşteri silemez.
account:read: Profilini, görüşme türlerini (fiyat ve özel sorular dahil) ve müsaitlik saatlerini görebilir.
account:write: Profilini (ad, renk, fotoğraf, karşılama penceresi), görüşme türlerini (fiyat ve özel sorular dahil) ve müsaitlik saatlerini oluşturabilir ve değiştirebilir.
account:delete: Görüşme türü, görüşme türü sorusu ve müsaitlik istisnası silebilir. Bir görüşme türü silinince o türdeki randevu kayıtları da silinir. Yalnızca doğrulanmış uygulamalara verilir.
feedback:write: Sen istersen takv.im ekibine geri bildirim ya da istek gönderebilir.

Sınırlar

Her bağlantı için dakikada 120 istek.
Kullanıcı bağlantıyı istediği an Ayarlar sayfasındaki Güvenlik bölümünden keser. Jeton hemen çalışmaz olur.

Entegrasyonunu takv.im'e ekle

Uygulamanı yaptın ve takv.im kullanıcılarının bilmesini mi istiyorsun? Bize e-posta yaz. Doğrulanan uygulamalarda izin ekranında "takv.im bu uygulamayı tanıyor" yazar. Doğrulanan uygulamaları ileride Entegrasyonlar sayfasında göstermeyi de düşünüyoruz.

E-postada şunları yaz:

Uygulamanın adı ve sitesi.
Uygulaman takv.im kullanıcılarına ne sağlıyor?
Neden takv.im'e eklememiz gerekiyor? Kullanıcılarımız bunu neden ister, benzerlerinden farkı ne?
Uygulamanın client_id değeri.
Gizlilik sayfasının adresi. Bu zorunlu.
Hangi izni neden istediğin.
Sana ulaşabileceğimiz e-posta.

E-posta adresimizi yalnızca takv.im üyelerine gösteriyoruz. Görmek için giriş yap ya da ücretsiz kaydol.

Giriş yap Ücretsiz kaydol

Onay (doğrulama)

Onay beklemezsin. Uygulamanı kaydettiğin an çalışır. Yalnızca kullanıcıyı korumak için doğrulanmamış uygulamalarda şunlar olur:

İzin ekranında sarı bir uyarı çıkar.
Not okuma ve silme izinleri verilmez.

Doğrulama istersen bu ikisi kalkar ve izin ekranında "takv.im bu uygulamayı tanıyor" yazar.

takv.im, hangi uygulamanın hangi kullanıcıyla ne zaman bağlandığını ve ne yaptığını kayıt altında tutar. Kurallara uymayan uygulama engellenir.

Doğrulama nasıl istenir

Doğrulama ve takv.im'e ekletme başvurusu aynı e-postayla yapılır. Ne yazacağını yukarıda anlattık.

Neye bakıyoruz

Site gerçekten var ve çalışıyor.
Gizlilik sayfası verinin nasıl kullanıldığını anlatıyor.
İstediğin izinler işine yetiyor, fazlası yok.
Adın başka bir markayı taklit etmiyor.
Yönlendirme adresi sana ait bir alan adında.

Her başvuruya elle bakılır, biraz sürebilir. Doğrulama kaydettiğin client_id için geçerlidir. Yönlendirme adresini değiştirmek istersen yeni kayıt yaparsın ve doğrulama baştan istenir.

Geliştirici kuralları

Uygulamanı kaydettiğinde bu kuralları kabul etmiş olursun.

takv.im'den aldığın veriyi yalnızca kullanıcının senden istediği iş için kullan.
Veriyi satma, kiralama, reklam için kullanma ve yapay zekâ modeli eğitmek için kullanma.
Kullanıcı bağlantıyı kesince ya da hesabını silince, o kullanıcının takv.im verisini 30 gün içinde sil.
Misafirlerin adı ve e-postası kişisel veridir (KVKK). Kendi gizlilik sayfanda takv.im'den veri aldığını yaz.
Jetonları güvenli sakla. Bir sızıntı ya da veri ihlali olursa takv.im ekibine e-posta ile hemen haber ver.
takv.im'miş gibi ya da takv.im'in onayladığı bir uygulamaymış gibi görünme. Adı ve logoyu taklit etme.
İstek sınırlarını aşmaya ya da korumaları atlamaya çalışma.
Bu kurallara uymayan ya da zarar verdiği anlaşılan uygulamayı önceden haber vermeden engelleyebiliriz. Engellenen uygulamanın tüm bağlantıları hemen kesilir.

takv.im ücretsiz ve geliştirme aşamasındadır. Bu sayfadaki uçlar, izinler ve sınırlar değişebilir, hizmet durabilir. Uygulamanın kullanıcıya ve misafirlere karşı sorumluluğu sana aittir. takv.im, kanunun izin verdiği ölçüde, uygulamaların yaptıklarından ve verdikleri zarardan sorumlu değildir.

Yalnızca kendi hesabın için

Başkasının hesabına bağlanmayacaksan OAuth'a gerek yok. Giriş yap, Ayarlar sayfasındaki API bölümünden kişisel bir anahtar oluştur. İsteklere Authorization: Bearer ANAHTAR başlığını ekle. /api/v1 ve /mcp adreslerinde çalışır.

Anahtar yalnızca oluştururken bir kez gösterilir, sonra değiştirilemez. Silmek için adını elle yazman gerekir.

Logo

"takv.im'e bağlan" düğmesinde logomuzu kullanabilirsin: SVG ve PNG. Uygulamanın kendi logosu gibi gösterme.

Keşif belgeleri

oauth-authorization-server: adresler, desteklenen yöntemler
oauth-protected-resource: API ve izinleri