# Başlangıç

Cubicl API'yını işlerinizi otomatize etmek veya Cubicl'ı kendi sisteminiz de dahil olmak üzere diğer yazılımlarla entegre etmek için kullanabilirsiniz. Görevleri, müşterileri, dosyaları ve diğer kayıtları listelemek, oluşturmak, düzenlemek ve silmek için HTTP istekleri gönderebilirsiniz. Bu doküman teknik bilgiler içerdiği için eğer bilginiz yoksa bu belgeyi bir geliştiriciye yönlendirmelisiniz.

## Protokol

Cubicl, RESTful tabanlı API kullanır. JSON, istek gövdesi ve yanıtlar için kullanılır. API URL'leri `https://cubicl.io/api/v1/` ile başlar. Örneğin bir görev oluşturmak için aşağıdaki URL'ye bir istek göndermelisiniz:

```
https://cubicl.io/api/v1/tasks
```

Atılan isteğin sonucu başarılı ise 200 kodu veya 2 ile başlayan HTTP durum kodları döner. Hata durumunda ise aşağıdaki HTTP durum kodları döner.

| 400 | Geçersiz İstek  | İstek parametreleri eksik veya yanlış biçimde.                                                                                             |
| --- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 | Yetkisiz        | Erişim jetonu geçersiz veya eksik.                                                                                                         |
| 403 | İzin Verilmedi  | İşlemi yapmak için gerekli izinlere sahip değilsiniz.                                                                                      |
| 404 | Bulunamadı      | Kaynak mevcut değil.                                                                                                                       |
| 405 | Yanlış metod    | Yanlış HTTP metodu (GET, POST vb.) kullandınız. İstek için hangi metodun kullanıldığını görmek için API dokümanına bakın.                  |
| 418 | Kahve Yok       | Kahve demlemeye çalışıyorsunuz ancak sunucu çaydanlık olduğu için bu isteğiniz yerine getirilemiyor.                                       |
| 422 | Geçersiz İstek  | Mümkün olmayan veya mantıklı olmayan bir şey yapmaya çalışıyorsunuz. Üzerinde çalıştığınız verileri kontrol edin.                          |
| 429 | Çok Fazla İstek | Kısa bir süre içinde çok fazla istek gönderdiniz. Bir dakika içinde 120'den fazla istek gönderemezsiniz. Biraz bekleyin ve tekrar deneyin. |
| 5xx | Sunucu Hatası   | Sunucuda bir hata oluştu.                                                                                                                  |

{% hint style="info" %}
Bir dakika içinde 60'tan fazla istek gönderemezsiniz. Bir döngü içinde göndermeyi planlıyorsanız, istekler arasına bir gecikme koyun.
{% endhint %}

## Erişim Jetonları

Cubicl, API erişimi için `Bearer kimlik doğrulama şemasını` kullanır. API'mize istek göndermek için [Entegrasyonlar](https://cubicl.io/integrations) sayfasından bir erişim jetonu oluşturmalısınız. İstek gönderirken, yetkilendirme adlı bir başlıkta erişim jetonunu şu şekilde gönderin:

```
Authorization: Bearer ERİŞİM_JETONUNUZ
```

{% hint style="danger" %}
Erişim jetonları, bir kullanıcı adına istek göndermenize (verilere erişme veya işlem yapma) izin verir. Dolayısıyla oluşturulan bu jetonlar hassas verilerdir ve parola olarak ele alınmaları gerekir. Bunları başkalarıyla **PAYLAŞMAYIN**. Bunları **PAYLAŞILAN VE HERKESİN GÖRDÜĞÜ PROJELERE EKLEMEYİN**. Cubicl arayüzünden bu jetonları kaldırarak erişimi kesebilirsiniz.
{% endhint %}

#### İzinler

Erişim jetonları bir kullanıcı adına erişime izin verdiğinden dolayı ilgili kullanıcının bu eylemi gerçekleştirmek için gerekli izinlere sahip olması gerekir. Kullanıcı izinleri, Cubicl arayüzünden ayarlanır. Erişim jetonları her kullanıcı için ayrı ayrı oluşturulur. Bundan dolayı, adına istek göndereceğiniz kullanıcının hesabında jeton oluşturmanız gerekir.

#### Ayrı Hesap

API istekleri aracılığıyla gerçekleştirilen görev oluşturma gibi eylemler, erişim jetonlarının sahibi tarafından yapılmış gibi görünmektedir. Otomatikleştirilmiş API işlemlerini kullanıcının kendi eylemlerinden ayırmanız gerekiyorsa, yalnızca API erişimi için yeni bir kullanıcı hesabı oluşturmayı düşünebilirsiniz. API entegrasyon uygulamanız, bir kullanıcıya vermek istediğiniz çok çeşitli izinler gerektiğinde de bu dikkate alınmalıdır. Normal bir kullanıcı hesabından hiçbir farkı olmadığı için bu hesaplar için de aylık veya yıllık abonelik ücretleri geçerlidir.

## Veriler ve Gösterimi

İlerleyen sayfalarda, API bağlantıları ile ilgili ayrıntıları göreceksiniz. Bir istekte gönderilen ve sunucudan dönen verilerin özellikleri ve formatı burada açıklanmaktadır.

#### Gösterim

Veriler, burada Typescript programlama dili ile gösterilmiştir. Aşağıda yorum satırlarıyla birlikte bir örnek verilmiştir.

```typescript
type Task = {
    // Özellik adları ve tipleri, anahtar-tip çiftleri olarak gösterilir
    name: string,
    activityCount: number,
    completed: boolean,
    // Nesne türleri, özelliklerinin her birinin tipini tanımlar
    progress: {
        totalSteps: number,
        completed: number,
    },
    // Dizi tiplerinde, tip adının yanında köşeli parantezler vardır. Özelliklerin
    // bir dizi nesneyi veya bir dizi diziyi de tutabileceğini unutmayın.
    assigneeIds: string[],
    // Bir alan boş olabiliyorsa, özellik adının yanında "?" eklenir.
    // Alan hem boş olabilir hem de farklı tipler içerebilirse "|"
    // sembolü ile gösterilir.
    archivedAt?: Date | null,
}
```

#### ID'ler

Kayıtların ID'si `string` tipinde `_id` ile gösterilir. Örnek:

```
627fd586f8b23768c7261a63
```

#### Tarih Değerleri

İsteklerdeki ve yanıtlardaki tarihler, **saniye** cinsinden `Unix Tarih Bilgisi` olarak gönderilir. Bundan dolayı API dokümanında tipi `number` olarak gösterilir.

#### Seyrek Veriler

Aksi belirtilmedikçe, oluşturma ve güncelleme istekleri yalnızca **gerekli** alanları zorunlu kılar. İsteklerde diğer alanların gönderilmesi gerekmez.

Sunucudan döndürülen kayıtlar, daha önce ayarlanmamışsa tüm alanları içermeyebilir. Kodunuz eksik alanları işleyebilmelidir. Bu durumda, bunları boş veya yanlış bir değer olarak kabul edin.

## Yardım

API dokümanı, erişim jetonu oluşturma ile ilgili herhangi bir sorunla karşılaşırsanız veya eksik bir uç noktasının eklenmesini istiyorsanız lütfen bizimle iletişime geçin.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kilavuz.cubicl.io/api-entegrasyonu/baslangic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.