> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ops-apidoc.hugin.co/llms.txt.
> For full documentation content, see https://ops-apidoc.hugin.co/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ops-apidoc.hugin.co/_mcp/server.

# Overview

Ops API, Hugin'in iş ortakları ile operasyonel süreçleri yüksek verimlilik ile yönetebilmesini sağlayan restful web servisidir.

## 🔐 Kimlik Doğrulama

Tüm endpoint'ler (login ve health check hariç) **Bearer token** ile kimlik doğrulama gerektirir.

### Token Alma

1. `POST /api/v1/login` endpoint'ini kullanarak giriş yapın

2. Response'da dönen token'ı alın

3. Diğer tüm isteklerde `Authorization: Bearer {token}` header'ını kullanın

**Token Özellikleri:**

* Token güvenlik sebebi ile inactivity durumunda time-out a düşer, bu tip durumunlarda tüm fonksiyonlar aynı hatayı döner, bu durumu yöneterek yeni token almanız gerekmektedir.

* Token, Postman ortamında otomatik olarak environment variable'a kaydedilir (`auth_token`)

***

## 🔄 İş Akışları

### Senaryo 1: Müşteri Bankaya İlk Kez Gidiyor

1. **Banka ön sipariş oluşturur** (`POST /api/v1/leads`)

   * **Seçenek A:** Terminal numarası ile birlikte sipariş oluşturur

   * **Seçenek B:** Sipariş oluşturur, sonra cihaz atamasını kontrol eder (`GET /api/v1/leads`)

2. **Hugin kurulum yapar**

3. **Müşteri cihazı alır**

### Senaryo 2: Müşteri Cihazı Aldıktan Sonra Bankaya Gidiyor

1. **Müşteri cihazın mali ID'sini bildirir**

2. **Banka terminal kurulum talebi verir** (`POST /api/v1/cases`)

***

## ❌ Hata Yönetimi

Tüm hatalar standart JSON formatında döner:

```javascript
{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Hata kodunun detaylı tanımı burada yer alır"
  },
  "metadata": {
    "instance": "/path",
    "timestamp": "2024-03-20T15:30:45Z"
  }
}

```

```python
{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Hata kodunun detaylı tanımı burada yer alır"
  },
  "metadata": {
    "instance": "/path",
    "timestamp": "2024-03-20T15:30:45Z"
  }
}

```

```java
{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Hata kodunun detaylı tanımı burada yer alır"
  },
  "metadata": {
    "instance": "/path",
    "timestamp": "2024-03-20T15:30:45Z"
  }
}

```

```curl
{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Hata kodunun detaylı tanımı burada yer alır"
  },
  "metadata": {
    "instance": "/path",
    "timestamp": "2024-03-20T15:30:45Z"
  }
}

```

```bash
{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Hata kodunun detaylı tanımı burada yer alır"
  },
  "metadata": {
    "instance": "/path",
    "timestamp": "2024-03-20T15:30:45Z"
  }
}

```

### Hata Kodları

| HTTP Status | Error Code             | Açıklama                                             |
| ----------- | ---------------------- | ---------------------------------------------------- |
| 400         | `VALIDATION_ERROR`     | Validasyon hatası (eksik veya geçersiz parametreler) |
| 401         | `AUTHENTICATION_ERROR` | Kimlik doğrulama hatası (geçersiz veya eksik token)  |
| 404         | `NOT_FOUND`            | Kaynak bulunamadı                                    |
| 500         | `CRM_ERROR`            | CRM sistemi işlem hatası                             |
| 500         | `INTERNAL_ERROR`       | İç sunucu hatası                                     |

***

## 🔑 Önemli İş Kuralları

### Mali ID Validasyonu

* F, 00 veya HN ile başlamalıdır

* FT, FU ve FV ile başlayanlar BKM Techpos sistemi üzerinden giriş yapmalıdır

* 10-12 karakter uzunluğunda olmalıdır

### Terminal Kontrolü

* Cihaz üzerinde çalışan terminal varsa, başka terminal numarası ile iş emri açılamaz

* Ancak mevcut terminal için versiyon güncelleme, banka silme, eğitim, arıza, bakım talepleri açılabilir

### TCKN/VKN Validasyonu

* **TCKN:** 11 haneli, doğrulama yapılır

* **VKN:** 10 haneli, doğrulama yapılır

* Lead oluşturulurken en az biri (TCKN veya VKN) zorunlu

### Terminal ID ile Sipariş

* Terminal ID ile kayıt için sadece 1 adet sipariş geçilebilir (`leadQuantity` > 1 olamaz)

* Eğer terminal ID zaten varsa, mevcut sipariş döner (yeni sipariş oluşturulmaz)

***

## 🌐 API Versiyonu ve Base URL

* **Mevcut Versiyon:** v1

* **Base URL:** `{{base_url}}/api/v1`

* **Environment Variable:** Collection'da `base_url` environment variable'ı kullanılmaktadır

***

## 📝 Notlar

* Her endpoint'in detaylı dokümantasyonu için ilgili request'in description bölümüne bakın

* Request ve response örnekleri her endpoint'te mevcuttur

* Collection runner ile tüm endpoint'leri test edebilirsiniz

* GMP3 cihazlar için özel alanlar (DeviceBrand, DeviceModel, IsGMP3) kullanılır

***

## 🚀 Başlangıç

1. Environment'ı ayarlayın (`base_url` variable'ını tanımlayın)

2. Login endpoint'i ile giriş yapın

3. Dönen token otomatik olarak `auth_token` variable'ına kaydedilir

4. Diğer endpoint'leri kullanmaya başlayın

**Daha fazla bilgi için:** Her endpoint'in kendi description bölümünde detaylı parametre açıklamaları, iş kuralları ve örnek kullanımlar bulunmaktadır.