API Genel Bakış

Loyetta API, JSON formatında istek gövdesi kabul eden ve JSON formatında yanıt döndüren RESTful bir API'dir.

Base URL

Tüm API istekleri, size özel tenant domain'ine yapılmalıdır:

Örneğin, subdomain'iniz marka ise, production base URL'iniz şöyle olur:

İstek Formatı

Başlıklar (Headers)

Tüm istekler aşağıdaki başlıkları içermelidir:

Örnek İstek

curl -X GET https://acme.prod.loyetta.com/api/v1/user/profile \
  -H "Authorization: Bearer {musteri-tokeni}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

İstek Gövdesi

POST, PUT ve PATCH istekleri için verileri JSON nesnesi olarak gönderin:

curl -X POST https://acme.prod.loyetta.com/api/v1/example \
  -H "Authorization: Bearer {musteri-tokeni}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "field": "value",
    "another_field": 123
  }'

Yanıt Formatı

Tüm başarılı yanıtlar bir JSON nesnesi döndürür. Yapı endpoint'e göre değişir, ancak genellikle istenen veriyi doğrudan veya data anahtarı içinde sarar.

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Örnek"
  }
}

Tarih ve Saat Formatı

API içindeki tüm tarih ve saat alanları kesinlikle Coordinated Universal Time (UTC) cinsinden temsil edilir ve ISO 8601 standardına göre formatlanır.

API, yerel saat dilimi farklarını (örneğin +03:00) saklamaz veya döndürmez. İstemci uygulamalar (client), istek gönderirken yerel saati UTC'ye çevirmekten ve yanıtları görüntülerken UTC'yi tekrar yerel saate dönüştürmekten sorumludur.

Kullanılan format YYYY-MM-DDTHH:mm:ss.uuuuuuZ şeklindedir:

Saat Dilimi Dönüşüm Örneği

Eğer bir olay İstanbul (GMT+3) saatine göre 17:38:00'da gerçekleşiyorsa, API ile etkileşime geçmeden önce bu saatin 14:38:00 UTC'ye (3 saat çıkarılarak) dönüştürülmesi gerekir.

Veri Gönderme (Request)

API'ye veri gönderirken yerel saatinizi mutlaka UTC'ye çevirmelisiniz. Örnek: İstanbul saatiyle 17:38 için bir randevu oluşturma.

curl -X POST [https://acme.prod.loyetta.com/api/v1/appointments](https://acme.prod.loyetta.com/api/v1/appointments) \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 123,
    "appointment_time": "2025-09-01T14:38:00.000000Z"
  }'

---

Sayfalama (Pagination)

Liste döndüren endpoint'ler sayfalamayı destekler. Sayfa numarasını ve sayfa boyutunu kontrol etmek için query parametrelerini kullanın.

Query Parametreleri

Örnek İstek

curl -X GET "https://marka.prod.loyetta.com/api/v1/products?page[number]=2&page[size]=10" \
  -H "Authorization: Bearer {musteri-tokeni}" \
  -H "Accept: application/json"

Sayfalanmış Yanıt

Sayfalanmış endpoint'ler data, links ve meta nesneleri içeren bir yanıt döndürür:

{
  "data": [
    { "id": 1, "name": "Öğe 1" },
    { "id": 2, "name": "Öğe 2" }
  ],
  "links": {
    "first": "https://marka.prod.loyetta.com/api/v1/products?page[number]=1",
    "last": "https://marka.prod.loyetta.com/api/v1/products?page[number]=5",
    "prev": "https://marka.prod.loyetta.com/api/v1/products?page[number]=1",
    "next": "https://marka.prod.loyetta.com/api/v1/products?page[number]=3"
  },
  "meta": {
    "current_page": 2,
    "from": 11,
    "last_page": 5,
    "path": "https://marka.prod.loyetta.com/api/v1/products",
    "per_page": 10,
    "to": 20,
    "total": 50
  }
}

Yanıt Alanları

Hata Yönetimi

Bir hata oluştuğunda, API uygun bir HTTP durum kodu ve message alanı içeren bir JSON yanıtı döndürür.

HTTP Durum Kodları

401 Unauthorized

Authorization başlığı eksik olduğunda veya sağlanan token geçersiz olduğunda döndürülür.

{
  "message": "Unauthenticated."
}

404 Not Found

İstenen kaynak (kullanıcı, ürün, sipariş vb.) mevcut olmadığında döndürülür.

{
  "message": "Not found."
}

422 Validation Error

İstek gövdesi doğrulamayı geçemediğinde döndürülür. Yanıt, hangi alanların neden başarısız olduğuna dair detaylı bilgi içerir.

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "points": [
      "The points field must be an integer.",
      "The points field must be at least 0."
    ]
  }
}

errors nesnesi, alan adlarını anahtar olarak içerir ve her değer, o alan için doğrulama hata mesajlarının bir dizisidir.

500 Internal Server Error

Sunucuda beklenmeyen bir hata oluştuğunda döndürülür. Bunu sürekli alıyorsanız, lütfen destek ile iletişime geçin.

{
  "message": "Server Error."
}