Overview

View as Markdown

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:

1{
2  "status": "ERROR",
3  "error": {
4    "code": "ERROR_CODE_HERE",
5    "message": "Hata kodunun detaylı tanımı burada yer alır"
6  },
7  "metadata": {
8    "instance": "/path",
9    "timestamp": "2024-03-20T15:30:45Z"
10  }
11}

Hata Kodları

HTTP StatusError CodeAçıklama
400VALIDATION_ERRORValidasyon hatası (eksik veya geçersiz parametreler)
401AUTHENTICATION_ERRORKimlik doğrulama hatası (geçersiz veya eksik token)
404NOT_FOUNDKaynak bulunamadı
500CRM_ERRORCRM sistemi işlem hatası
500INTERNAL_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.