> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rehber: hasta formu gönderme

> Form şablonundan hastaya özel link oluşturmayı, linki göndermeyi ve doldurulan yanıtları okumayı anlatır.

Bu rehber, kliniğinizdeki bir Form Şablonu'ndan hastaya özel bir link oluşturmayı, linki hastaya ulaştırmayı ve hasta formu doldurduktan sonra yanıtları API'den okumayı anlatır. Anamnez ve onam formları gibi bilgileri randevudan önce toplamak için kullanın.

## Senaryo

Bir hasta randevu aldı. Entegrasyonunuz hastaya anamnez formunu göndermek ve hasta doldurunca yanıtları kendi sisteminize almak istiyor.

```mermaid theme={null}
sequenceDiagram
    participant E as Entegrasyonunuz
    participant F as Flextell API
    participant H as Hasta
    E->>F: Form şablonlarını listele
    E->>F: Hasta için link oluştur
    F-->>E: token ve url
    E->>H: url'yi gönder
    H->>F: Formu aç ve gönder
    E->>F: Doldurulan formu oku
    F-->>E: status ve yanıtlar
```

Ön koşullar:

* Erişim token'ınız `form_templates:read`, `form_templates:write` ve `customer_forms:read` scope'larına sahip olmalı. Tek bir formun yanıtlarını okumak için ayrıca `customers:read` gerekir. Scope'lar için [scope'lar](/api/kimlik-dogrulama/scopelar) sayfasına bakın.
* Her istekte `X-Tenant` başlığını gönderin. Ayrıntı için [klinikler ve X-Tenant](/api/klinikler-ve-x-tenant) sayfasına bakın.
* Token'ın kullanıcısı gerekli izinlere sahip olmalı (aşağıdaki tablo).

| İşlem | Scope | İzin |
| - | - | - |
| Şablonları listeleme ve okuma | `form_templates:read` | `View:FormTemplate` (**Görüntüle**) |
| Link oluşturma | `form_templates:write` | `GenerateLink:FormTemplate` (**Bağlantı Oluştur**) |
| Doldurulan formları listeleme | `customer_forms:read` | `View:CustomerForm` |
| Bir hastanın formlarını okuma | `customer_forms:read` ve `customers:read` | `View:Customer` ve `View:CustomerForm` |

<Info>
  `ViewAllCustomers:Customer` izni olmayan kullanıcılar yalnızca kendilerine atanmış hastaların formlarını görür. Ayrıntı için [izinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.
</Info>

## Form şablonunu seçme

Şablonları `GET /api/v1/form-templates` ile listeleyin. `search`, `is_active` ve `sort_by` (`name`, `created_at`, `updated_at`, `is_active`) parametrelerini kullanabilirsiniz.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.flextell.ai/api/v1/form-templates?is_active=1&search=anamnez" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>"
  ```
</CodeGroup>

Yanıttaki her kayıtta `id`, `name`, `system_name`, `description` ve `is_active` alanları bulunur. Sorular listede gelmez. Soruları görmek için `GET /api/v1/form-templates/{id}` çağırın; yanıtta `questions[]` dizisi (`label`, `question_type`, `required`, `options[]`, `visibility_rules[]`) yer alır.

<Warning>
  Link oluşturma endpoint'i şablonun `is_active` değerini denetlemez. Pasif bir şablondan da link üretebilirsiniz. Yalnızca `is_active=1` olan şablonlardan link oluşturun.
</Warning>

Şablonların panelde nasıl hazırlandığı için [Form Şablonları](/panel/iletisim/form-sablonlari) sayfasına bakın.

## Link oluşturma

`POST /api/v1/form-templates/{id}/links` her çağrıda yeni bir `pending` form kaydı ve yeni bir token üretir.

<ParamField body="customer_id" type="integer">
  Linkin bağlanacağı hasta. Boş bırakırsanız link anonim olur ve URL'yi bilen herkes doldurabilir.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://app.flextell.ai/api/v1/form-templates/123/links" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Content-Type: application/json" \
    -d '{ "customer_id": 456 }'
  ```
</CodeGroup>

Başarılı yanıt `201` döner:

```json theme={null}
{
  "success": true,
  "data": {
    "id": 789,
    "template_id": 123,
    "customer_id": 456,
    "status": "pending",
    "token": "K7M2QX",
    "url": "https://<form-adresi>/forms/K7M2QX",
    "created_at": "2026-10-12T14:30:00+03:00"
  }
}
```

Hastaya göndereceğiniz adres `url` alanıdır; olduğu gibi kullanın. Yanıtta dönen `id`, doldurulan formu sonradan okurken kullanacağınız `customerFormId` değeridir. `token` 6 karakterli, büyük harf ve rakamlardan oluşur.

<Note>
  Yanıtlarını API'den okumak istiyorsanız `customer_id` göndermelisiniz. Anonim linklerle doldurulan formlar hiçbir liste endpoint'inde görünmez.
</Note>

## Linki hastaya gönderme

Flextell bu linki sizin yerinize hastaya iletmez. `url` değerini kendi kanalınızdan (e-posta, SMS, WhatsApp) gönderin. Hastanın Flextell'de açık bir sohbeti varsa linki mesaj olarak da gönderebilirsiniz; adımlar için [mesaj gönderme rehberine](/api/rehberler/mesaj-gonderme) bakın.

Hasta linki açtığında:

* Form tarayıcıda açılır; hastanın giriş yapması gerekmez. Token tek kimlik bilgisidir.
* Hasta soruları yanıtlayıp gönderir. Koşullu sorular, kural sağlanmadığında gizlenir.
* Form tek kullanımlıktır. Gönderilen form bir daha doldurulamaz.

Kendi form ekranınızı yapmak isterseniz kimlik doğrulamasız genel endpoint'ler vardır: `GET /api/v1/public/forms/{token}` ve `POST /api/v1/public/forms/{token}`. Ayrıntı için [herkese açık hasta formları](/api/webhooklar/herkese-acik-hasta-formlari) sayfasına bakın. Bu endpoint'ler IP başına varsayılan olarak dakikada 60 okuma ve 10 gönderim ile sınırlıdır; aşıldığında `429 TOO_MANY_REQUESTS` döner.

## Yanıtları okuma

Form doldurulduğunda `status` değeri `completed` olur ve `completed_at` dolar. Yeni tamamlanan formları yakalamak için listeyi `status=completed` ve `completed_at_from` ile belirli aralıklarla sorgulayın.

### Doldurulan formları listeleme

`GET /api/v1/customer-forms` kliniğin formlarını listeler.

| Parametre | Açıklama |
| - | - |
| `status` | `pending`, `completed` veya `reviewed`. Başka değer `422` döner. |
| `template_id` | Belirli bir şablonun formları. |
| `completed_at_from`, `completed_at_to` | Tamamlanma tarihi aralığı. |
| `search` | Hasta adı, telefon, e-posta, kimlik numarası veya şablon adı. |
| `sort_by`, `sort_order` | `sort_by` değerleri: `id`, `status`, `completed_at`, `created_at`, `updated_at`. Varsayılan sıralama `created_at` azalan. |
| `per_page`, `page` | Sayfalama. `per_page` 1 ile 100 arasındadır. |

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.flextell.ai/api/v1/customer-forms?status=completed&template_id=123" \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>"
  ```
</CodeGroup>

Listede yanıtlar yoktur. Kayıtlarda `id`, `template_id`, `customer_id`, `status`, `completed_at`, `template` ve `customer` bulunur. Panelde aynı liste **Form Şablonları → Doldurulan Formlar** altında görünür; panel yanıtları göstermez. Panel için [Doldurulan Formlar](/panel/iletisim/doldurulan-formlar) sayfasına bakın.

### Bir formun yanıtlarını okuma

Yanıtlar için hastanın formunu tek tek okuyun:

`GET /api/v1/customers/{customerId}/form/{customerFormId}`

Yanıtta `answers[]` dizisi, her kayıtta `answer` değeri ve ilgili `question` bulunur. `template.questions[]` soru metinlerini ve seçenekleri verir. Seçim ve radyo sorularında `answer` seçenek kimliğidir; onay kutusunda seçenek kimliklerinin listesidir. Evet/Hayır sorusunda "Hayır" `0` olarak gelir ve yanıtsız anlamına gelmez.

Bir hastanın tüm formlarını listelemek için `GET /api/v1/customers/{customerId}/form` kullanın (`status`, `template_id`, `sort_by`, `sort_order`, `per_page`, `page`). Bu liste Laravel sayfalama yapısında `data` içinde döner.

<Warning>
  Lead aşamasındaki kişiler için link oluşturabilirsiniz, ancak bu kişilerin formları `GET /customer-forms` listesinde çıkmaz. `GET /customers/{customerId}/form` boş liste, `GET /customers/{customerId}/form/{customerFormId}` ise `404` döner. Yanıtları okuyacaksanız kişinin hasta olarak kayıtlı olması gerekir.
</Warning>

Kaynağın tam şeması için [hasta formları](/api/kaynaklar/hasta-formlari) sayfasına bakın.

## Hata durumları

### Link oluşturma ve okuma

| Kod | HTTP | Ne zaman |
| - | - | - |
| `UNAUTHENTICATED` | 401 | Token eksik veya geçersiz. |
| `FORBIDDEN` | 403 | Token'da gerekli scope yok veya kullanıcıda `GenerateLink:FormTemplate` gibi gerekli izin yok. |
| `LEAD_NOT_ASSIGNED` | 403 | Başka bir satış temsilcisine atanmış (veya kimseye atanmamış) bir kişi için link oluşturuyorsunuz. Yanıtta `data.assigned_user` atanan kullanıcıyı verir. |
| `RESOURCE_NOT_FOUND` | 404 | Şablon bulunamadı (`Form şablonu bulunamadı`) ya da form bulunamadı (`Hasta formu bulunamadı`). |
| `CUSTOMER_ERASED` | 409 | Verileri imha edilmiş hasta için link oluşturuyorsunuz. |
| `VALIDATION_FAILED` | 422 | `customer_id` kliniğinizde yok (`Seçilen hasta bulunamadı.`) ya da liste filtresi geçersiz. |
| `TENANT_HEADER_REQUIRED` | 400 | `X-Tenant` başlığı eksik. |

Faturalama veya kurulum kilitleri (`SUBSCRIPTION_REQUIRED`, `ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT`, `SETUP_REQUIRED`) yetkili endpoint'lerde de geçerlidir. Bkz. [erişim kilitleri](/api/istekler/erisim-kilitleri) ve [hata kodları](/api/istekler/hata-kodlari).

### Hastanın formu açıp göndermesi

| Kod | HTTP | Ne zaman |
| - | - | - |
| `RESOURCE_NOT_FOUND` | 404 | Token bilinmiyor, şablon silinmiş ya da hasta silinmiş veya verisi imha edilmiş. Güvenlik nedeniyle tüm durumlar aynı yanıtı verir. |
| `CUSTOMER_FORM_ALREADY_COMPLETED` | 409 | Form daha önce doldurulmuş: `Bu form zaten doldurulmuş.` |
| `VALIDATION_FAILED` | 422 | Zorunlu görünür soru boş, seçenek kimliği geçersiz veya tarih `Y-m-d` biçiminde değil. Hatalar `answers.{question_id}` anahtarıyla gelir. |
| `TOO_MANY_REQUESTS` | 429 | IP başına istek sınırı aşıldı. |

<Tip>
  Hasta "Bu form zaten doldurulmuş" uyarısı alırsa yeni bir link oluşturun. Her çağrı yeni bir form kaydı açar; eski kaydın yanıtları yerinde kalır.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.