> ## 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.
# Veri biçimleri
> Tarih ve saat, saat dilimi, para ve ondalık sayı, telefon ve girdi normalleştirme kurallarını anlatır.
Bu sayfa, istek gövdesine ve sorgu parametrelerine yazdığınız değerlerin nasıl yorumlandığını ve yanıtlarda nasıl geri döndüğünü anlatır. Kurallar tüm kaynaklar için geçerlidir. Bir alanın tam türü için ilgili kaynağın şemasına bakın.
## Tarih ve saat biçimi
Flextell iki tür zaman değeri kullanır: an (tarih ve saat) ve takvim tarihi.
| Tür | Biçim | Örnek | Nerede |
| - | - | - | - |
| An | ISO 8601, saat farkı (offset) ile | `2026-10-12T14:30:00+03:00` | `*_at` alanlarının çoğu, randevu zamanları |
| Takvim tarihi | `Y-m-d` | `2026-10-12` | Fatura `issue_date`, hasta `date_of_birth`, tatil `date` |
Yanıtlardaki anlar klinik saat diliminde, açık saat farkıyla ve kesirli saniye olmadan gelir.
Takvim tarihleri saat dilimine göre kaydırılmaz. `starts_at` ve `billing_started_at` gibi bazı `*_at` adlı alanlar da aslında takvim tarihidir. Alan adına değil, şemadaki türe bakın.
Her `*_at` alanının saat içerdiğini varsaymayın. Takvim tarihi dönen alanlarda saat dilimi dönüşümü uygulanmaz.
## Saat dilimi
Flextell zamanları UTC olarak saklar. Klinik saat dilimi, klinik ayarlarındaki varsayılan saat dilimidir. Varsayılan değer `Europe/Istanbul`'dur. Geçersiz ya da boş bir değer UTC'ye döner.
### Yanıtlarda
`X-Tenant` ile çağırdığınız klinik rotalarında:
* Anlar klinik saat diliminde döner (`2026-03-01T12:00:00+03:00`).
* Saat dilimi adı yanıt gövdesindeki `meta.timezone` alanında ve `X-Timezone` başlığında bulunur. Hata yanıtları ve sayfalama `meta` nesnesi dahil tüm JSON nesnelerinde bu alan yer alır.
Klinik bağlamı olmayan rotalarda (`/v1/account/*`, `/v1/general/*`, herkese açık formlar, `/v1/channels/capabilities`) `meta.timezone` ve `X-Timezone` yoktur. Anlar UTC olarak, mikro saniyeli biçimde döner:
```text theme={null}
2026-06-03T09:00:00.000000Z
```
### İstekte
* Saat farkı içeren bir değer olduğu gibi kabul edilir: `2026-10-12T14:30:00+03:00`.
* Saat farkı içermeyen bir değer, bu dönüşümü uygulayan isteklerde klinik saat diliminde yorumlanır ve UTC olarak saklanır.
Saat farkını her zaman açıkça yazmanızı öneririz. Böylece klinik saat dilimi ayarı değerin anlamını değiştirmez.
Zaman ayarlarında iki istisna vardır. Sohbet ayarlarındaki `ai_reply_windows.*.start_time` ve `end_time` UTC `HH:mm` olarak okunur ve yazılır. `reminders.send_time` ise klinik saat olarak okunur ve yazılır.
Klinik seçimi için bkz. [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant). Başlıkların tam listesi için bkz. [İstek başlıkları](/api/istekler/basliklar).
## Para ve ondalık sayılar
Tek bir para biçimi yoktur. Her alanın türünü OpenAPI şemasında `string` ya da `number` olarak okuyun.
| Biçim | Örnek | Hangi kaynaklarda |
| - | - | - |
| İki ondalıklı string | `"120.00"` | Abonelik proformaları (`gross_amount`, `net_amount`, `total_amount`, `paid_amount`, `outstanding_amount` vb.), faturalar (`amount_tax_exclusive`, `amount_tax_total`, `amount_payable`, `invoice_amount`), hesap işlemleri (`debit`, `credit`, `amount`) |
| JSON sayı | `1500.5` | Satışlar (`exchange_rate`, `total_price`, `remaining_balance`, `total_collected`; tutarlar 2 ondalığa yuvarlanır), ürünler (`price`, `tax_rate`) |
Ondalık ayırıcı her zaman noktadır. Para birimi tutarın kendisinden anlaşılmaz. Tutarı, kaydın para birimi alanıyla birlikte yorumlayın.
### İstekte tutar gönderme
Tutarlar `numeric` olarak doğrulanır, yani nokta ondalıklı olmalıdır. Hasta ve hesap işlemlerinin tutarları ek olarak bir ayrıştırıcıdan geçer. Ayrıştırıcı, **string** olarak gönderilen ve tek ayırıcıdan sonra tam üç hane içeren değeri binlik ayırıcılı sayar:
| Gönderilen | Okunan |
| - | - |
| `"1.500"` | 1500 |
| `"15,000"` | 15000 |
| `"15,50"` | 15.50 |
Tutarı string olarak gönderirseniz `"1.500"` değeri 1,5 değil 1500 olarak okunur. Tutarları JSON sayı olarak (`1.5`) ya da noktalı ondalık olarak (`"1.50"`) gönderin.
Stok miktarları ve banka hesabı açılış bakiyesi gibi bazı alanlarda JSON sayısı en kısa ondalık string'e çevrilir. Üstel gösterim (`1e3`) `decimal` kuralından geçmez ve reddedilir.
Bazı yazma isteklerinde tutar dışındaki an alanları da klinik saatinden UTC'ye çevrilir: `transaction_date` (hesap ve hasta işlemleri, satış ödemeleri), `sale_date` (satışlar), `due_at` (lead görevleri) ve `valid_until` (teklifler). Geçersiz değer doğrulamada reddedilir.
## Telefon numaraları
Flextell telefon numaralarını doğrulamadan önce normalleştirir ve **yalnızca rakam** olarak saklar. Başında `+` yoktur.
| Gönderdiğiniz | Saklanan |
| - | - |
| `+90 555 123 4567` | `905551234567` |
| `0555 123 4567` | `905551234567` |
| `5551234567` | `905551234567` |
Kurallar:
* Rakam olmayan her karakter silinir.
* 10 haneli ve `5` ile başlayan numaraya `90` eklenir.
* 11 haneli ve `0` ile başlayan numaranın başındaki `0` atılıp `90` eklenir.
* Diğer numaralar ülke koduyla birlikte olduğu gibi kalır. Yurt dışı numaraları ülke koduyla gönderin.
Benzersizlik normalleştirilmiş değer üzerinden denetlenir. Aynı numarayı farklı yazımlarla göndermek çakışmayı engellemez. Hasta `phone_number` alanı normalleştirmeden sonra en çok 20, lead `phone_number` alanı en çok 50 karakterdir. Hasta oluştururken telefon zorunludur.
Yanıtlarda da numara aynı biçimde, `+` olmadan döner. Gösterim için başına `+` ekleyin.
Bir lead'in hastası kullanıcıya görünür değilse yanıttaki telefon ve e-posta kısmen maskelenir ve nesne `is_masked: true` ile işaretlenir. Ayrıntı için bkz. [İzinler ve görünürlük](/api/izinler-ve-gorunurluk).
Kaynak ayrıntıları için bkz. [Hastalar](/api/kaynaklar/hastalar) ve [Lead'ler](/api/kaynaklar/leadler).
## Girdi normalleştirme
Değerler doğrulamadan önce şu işlemlerden geçer:
1. **Boşluk kırpma.** Tüm string girdilerin başındaki ve sonundaki boşluklar silinir.
2. **Boş string.** `""` değeri `null` olur. Zorunlu bir alana `""` göndermek doğrulamadan geçmez. Boş yazılabilir (nullable) bir alana `""` göndermek `null` göndermek gibi alanı temizler.
3. **Boolean.** Kabul edilen değerler `true`, `false`, `1`, `0`, `"1"` ve `"0"`'dır. `"true"` ve `"false"` string'leri yalnızca bunu destekleyen isteklerde kabul edilir. Sorgu parametrelerinde `1` ve `0` kullanın.
4. **Bilinmeyen parametreler.** Tanınmayan ya da kaldırılmış parametreler hata vermeden yok sayılır. Yanlış yazılmış bir filtre sonucu daraltmaz.
5. **Kısmi güncelleme.** Güncellemeler `PUT` ile yapılır. Göndermediğiniz alanlar değişmez. Boş yazılabilir bir alana `null` göndermek onu temizler. Tek `PATCH` rotası `/v1/invoices/accounts/{id}/default-series`'tir.
6. **Yol kimlikleri.** `{id}` sayısal olmalıdır. Sayısal olmayan bir değer 404 döner. `0` gibi geçersiz bir kimlik bazı rotalarda 422 döner.
7. **İlişki parametresi yok.** `include`, `with` ve `fields` parametreleri yoktur. Her endpoint sabit bir ilişki kümesi döner.
Doğrulama hatalarının biçimi için bkz. [Hatalar](/api/istekler/hatalar). Filtre ve sıralama için bkz. [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama).
## Null değerler
* Yanıtlarda alanlar çoğunlukla her zaman bulunur. Değeri yoksa `null` döner (`deleted_at: null` gibi).
* İlişki nesneleri istisnadır. Endpoint bir ilişkiyi yüklemiyorsa o ilişkinin anahtarı yanıtta **hiç yer almaz**. Anahtar yokluğunu `null` ile karıştırmayın.
* Hata yanıtlarında `errors` ve `data` anahtarları değer yoksa çıkarılır.
* Toplu işlem sonuçlarında boş `error_code` ve `message` alanları çıkarılır.
* Boş bir nesne bazı alanlarda `{}` yerine `[]` olarak gelebilir (örneğin boş `relation_summary`). Nesne bekleyen alanlarda diziyi de kabul edin.
Yanıt zarfının tam yapısı için bkz. [Yanıt yapısı](/api/istekler/yanit-yapisi).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.