Herkese açık hasta formları

Hasta formları (anamnez, onam formu vb.) hastanın giriş yapmadan doldurabileceği bir link ile paylaşılır. Kendi form sayfanızı yazmak isterseniz bu linkin arkasındaki açık API’yi kullanırsınız: bir GET ile formu okur, bir POST ile yanıtları gönderirsiniz. Bu uçlar OAuth gerektirmez. Authorization ve X-Tenant başlıkları gönderilmez; tek kimlik bilgisi yolundaki form token’ıdır.

Metot	Endpoint	Açıklama
`GET`	`/api/v1/public/forms/{token}`	Formun adını, açıklamasını ve sorularını döndürür.
`POST`	`/api/v1/public/forms/{token}`	Hastanın yanıtlarını kaydeder ve formu tamamlar.

Form linki

Form linkini klinik adına yetkili bir istemci oluşturur: POST /api/v1/form-templates/{id}/links. Bu çağrı form_templates:write scope’unu ve GenerateLink:FormTemplate iznini gerektirir. Ayrıntılar için Hasta formları ve Hasta formu gönderme sayfalarına bakın. Gövdede isteğe bağlı customer_id gönderebilirsiniz. Boş bırakırsanız link anonim olur: URL’yi bilen herkes formu doldurabilir ve yanıtlar hiçbir hastaya bağlanmaz. Yanıt 201 döner:

{
  "id": 123,
  "template_id": 45,
  "customer_id": null,
  "status": "pending",
  "token": "A1B2C3",
  "url": "https://.../forms/A1B2C3",
  "created_at": "2026-10-12T14:30:00+03:00"
}

Her çağrı yeni bir bekleyen (pending) form oluşturur. token, 6 karakterlik rastgele büyük harf ve rakam dizisidir. Açık uçların yoluna {token} olarak aynen yazılır.

url, hastanın tarayıcıda açacağı Flextell form sayfasıdır. Bu sayfayı kullanırsanız aşağıdaki uçları çağırmanız gerekmez. Kendi sayfanızı yazıyorsanız yalnızca token değerini alıp açık API’yi kullanın.

Formu okuma

curl https://app.flextell.ai/api/v1/public/forms/A1B2C3

Başarılı yanıt 200 döner ve Cache-Control: no-store başlığı taşır.

Alan	Tür	Açıklama
`token`	string	Form token’ı.
`status`	string	Her zaman `pending`. Tamamlanmış form `409` döndürür.
`name`	string	Form şablonunun adı.
`description`	string	Şablon editöründe yazılan giriş metni, HTML olarak. Betikler, olay işleyicileri ve güvenli olmayan URL’ler sunucuda temizlenir. HTML olarak gösterin.
`questions`	array	Soru listesi.

Yanıt klinik, hasta veya personel bilgisi içermez.

Soru nesnesi

Alan	Tür	Açıklama
`id`	integer	Soru kimliği. Yanıt gönderirken anahtar olarak kullanılır.
`order`	integer	Görüntüleme sırası.
`label`	string	Soru metni.
`helper_text`	string veya null	Yardımcı metin.
`question_type`	string	`text`, `textarea`, `select`, `radio`, `checkbox`, `number`, `date` veya `boolean`.
`required`	boolean	Zorunlu soru.
`options`	array	Seçenekler: `id`, `label`, `order`. Seçim tipindeki sorularda kullanılır.
`visibility_rules`	array	Sorunun görünürlük kuralları.
`visibility_match_type`	string	Kuralların birleşimi: `all` her kural eşleşince, `any` biri eşleşince gösterir.

Her görünürlük kuralı id, depends_on_question_id, operator, value ve match_type alanlarını taşır. operator değerleri: equals, not_equals, in, not_in, greater_than, less_than, contains.

Kendi sayfanızda, bir sorunun kuralları sağlanmıyorsa o soruyu gizleyin. Sunucu gizli sorulardaki yanıtları doğrulamaz ve kaydetmez.

Formu gönderme

answers zorunludur ve anahtarları soru kimliği olan bir nesnedir.

curl -X POST https://app.flextell.ai/api/v1/public/forms/A1B2C3 \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "101": "Ayşe Yılmaz",
      "102": 205,
      "103": [301, 302],
      "104": "2026-10-12",
      "105": true
    }
  }'

Başarılı yanıt 200 döner ve Cache-Control: no-store başlığı taşır:

{ "message": "Formunuz başarıyla gönderildi." }

Yanıt değerleri

Soru tipi	Beklenen değer
`text`	Metin, en çok 1000 karakter.
`textarea`	Metin, en çok 10000 karakter.
`select`, `radio`	O soruya ait tek bir seçenek `id`’si.
`checkbox`	O soruya ait, birbirinden farklı seçenek `id`’lerinin listesi. Zorunluysa en az bir değer.
`number`	Sayı.
`date`	`Y-m-d` biçiminde tarih, örneğin `2026-10-12`.
`boolean`	`true`, `false`, `1` veya `0`.

Kurallar:

Zorunlu (required) ve görünür her soru yanıtlanmalıdır.
Gizli sorular doğrulanmaz ve yanıtları atılır.
Başka şablona ait soru kimlikleri ve sayısal olmayan anahtarlar yok sayılır.
Gönderim tek seferliktir. Yanıtlar kaydedilince form completed olur ve completed_at dolar.
Aynı anda gelen iki gönderimden yalnızca biri kaydedilir.

Yanıt biçimleri

Hata gövdeleri API’nin genel hata yapısını izler. Ayrıntı için Hatalar sayfasına bakın. Hata mesajları Accept-Language başlığına göre yerelleştirilir.

HTTP	Kod	Ne zaman
404	`RESOURCE_NOT_FOUND`	Token bulunamadı, form şablonu silinmiş ya da hasta silinmiş veya KVKK kapsamında imha edilmiş. Mesaj: `Hasta formu bulunamadı`.
409	`CUSTOMER_FORM_ALREADY_COMPLETED`	Form daha önce doldurulmuş. Mesaj: `Bu form zaten doldurulmuş.`
422	`VALIDATION_FAILED`	Yanıtlar kurallara uymuyor.
429	`TOO_MANY_REQUESTS`	Oran sınırı aşıldı.

404 yanıtı, token’ın yanlış olmasıyla şablonun ya da hastanın silinmiş olması arasında ayrım yapmaz. Bu bilinçlidir: token tahmin etmeye çalışan biri hiçbir şey öğrenemez.

Doğrulama hataları

422 yanıtında hatalar answers.{soru_id} anahtarıyla gelir. Checkbox öğeleri için anahtar answers.{soru_id}.{n} olur. Alan adı olarak sorunun label değeri kullanılır. Örneğin zorunlu Ad Soyad sorusu boş bırakılırsa answers.101 anahtarı altında The Ad Soyad field is required. biçiminde bir mesaj gelir. Hata gövdesinin genel yapısı için Hatalar sayfasına bakın.

Tek kullanımlık formlar

Her link bir kez doldurulabilir.

Link oluşturulduğunda form pending durumundadır.
Başarılı bir POST formu completed yapar.
Bundan sonra aynı token ile hem GET hem POST 409 CUSTOMER_FORM_ALREADY_COMPLETED döndürür.

Hastaya yeniden doldurtmak için yeni bir link oluşturun. Başarısız (örneğin 422) bir gönderim formu tamamlamaz; hasta düzeltip yeniden gönderebilir.

Formu doldurmak hastanın ön görüşme (intake) durumunu değiştirmez. Bu uçlar kliniğin faturalama veya kurulum durumuna da bağlı değildir.

Oran sınırları

Sınırlar form token’ına değil, istemcinin IP adresine uygulanır. Token’lar kısa olduğu için sınır tüm token’ları birlikte sayar; böylece token tahmini engellenir.

Kapsam	Sınır
`GET` ve `POST`, tüm token’lar birlikte	IP başına dakikada 60
Yalnızca `POST` (ek olarak)	IP başına dakikada 10

Sınır aşılınca 429 TOO_MANY_REQUESTS döner. Yanıt, oran sınırı başlıklarını ve Retry-After değerini taşır; beklenen süre dolmadan yeniden denemeyin. Kimliği doğrulanmış API’nin sınırları farklıdır: Oran sınırları.

Form sayfasını sunucunuz üzerinden çağırırsanız tüm hastalar aynı IP’den görünür ve sınırı birlikte tüketir. Çağrıları hastanın tarayıcısından yapın.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

Herkese açık hasta formları

Form linki

Formu okuma

Soru nesnesi

Formu gönderme

Yanıt değerleri

Yanıt biçimleri

Doğrulama hataları

Tek kullanımlık formlar

Oran sınırları

İlgili sayfalar

Hasta formları

Hasta formu gönderme

​Form linki

​Formu okuma

​Soru nesnesi

​Formu gönderme

​Yanıt değerleri

​Yanıt biçimleri

​Doğrulama hataları

​Tek kullanımlık formlar

​Oran sınırları

​İlgili sayfalar

Hasta formları

Hasta formu gönderme

Form linki

Formu okuma

Soru nesnesi

Formu gönderme

Yanıt değerleri

Yanıt biçimleri

Doğrulama hataları

Tek kullanımlık formlar

Oran sınırları

İlgili sayfalar