wisecolt/ytp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ytp/docs/API.md
szbk 63abf6eaff Readme index'ler eklendi.
2025-11-03 23:12:45 +03:00

11 KiB
Raw Permalink Blame History

YTP API Dokümantasyonu

Yakıt Takip Sistemi REST API endpoints ve WebSocket olayları için kapsamlı dokümantasyon.

📋 İçerik

🔧 Genel Bakış

Base URL

http://localhost:5005/api

İstek Formatı

  • Content-Type: application/json
  • Authorization: X-Session-Token header

Yanıt Formatı

{
  "message": "Başarılı mesaj",
  "data": { ... },
  "error": "Hata mesajı (varsa)"
}

🔐 Kimlik Doğrulama

POST /auth/login

Kullanıcı girişi için endpoint.

İstek:

{
  "username": "admin",
  "password": "Admin!123"
}

Başarılı Yanıt (200):

{
  "token": "a1b2c3d4e5f6...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "displayName": "Istasyon Admini"
  }
}

Hata Yanıtları:

  • 400 - Kullanıcı adı veya şifre eksik
  • 401 - Kullanıcı adı veya şifre hatalı
  • 500 - Sunucu hatası

POST /auth/logout

Oturumu kapatma.

Headers:

X-Session-Token: <token>

Yanıt (200):

{
  "message": "Oturum kapatildi."
}

GET /session

Mevcut oturum bilgilerini getirme.

Headers:

X-Session-Token: <token>

Yanıt (200):

{
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "displayName": "Istasyon Admini"
  }
}

👑 Admin API

Mal Sorumluları Yönetimi

GET /inventory-managers

Tüm mal sorumlularını listeler.

Yetki: Admin

Yanıt (200):

{
  "managers": [
    {
      "id": 3,
      "username": "malsorum1",
      "displayName": "Mal Sorumlusu 1",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}

POST /inventory-managers

Yeni mal sorumlusu oluşturur.

Yetki: Admin

İstek:

{
  "username": "malsorum2",
  "password": "Mal@123",
  "displayName": "Mal Sorumlusu 2"
}

Yanıt (201):

{
  "manager": {
    "id": 4,
    "username": "malsorum2",
    "displayName": "Mal Sorumlusu 2",
    "role": "inventory_manager"
  }
}

PUT /inventory-managers/:id

Mal sorumlusunu günceller.

Yetki: Admin

İstek:

{
  "displayName": "Güncellenmiş İsim",
  "password": "YeniŞifre123"
}

DELETE /inventory-managers/:id

Mal sorumlusunu siler.

Yetki: Admin

Yanıt (204) - No Content

Araç Yönetimi

GET /vehicles

Tüm araçları listeler.

Yetki: Admin

Yanıt (200):

{
  "vehicles": [
    {
      "id": 1,
      "brand": "Ford",
      "model": "Transit",
      "year": 2021,
      "plate": "34 AYT 312",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}

POST /vehicles

Yeni araç oluşturur.

Yetki: Admin

İstek:

{
  "brand": "Ford",
  "model": "Transit",
  "year": 2021,
  "plate": "34 AYT 312"
}

Yanıt (201):

{
  "vehicle": {
    "id": 2,
    "brand": "Ford",
    "model": "Transit",
    "year": 2021,
    "plate": "34 AYT 312"
  }
}

PUT /vehicles/:id

Araç bilgilerini günceller.

Yetki: Admin

DELETE /vehicles/:id

Araç kaydını siler.

Yetki: Admin

Birlik Yönetimi

GET /units

Tüm birlikleri listeler.

Yetki: Admin

Yanıt (200):

{
  "units": [
    {
      "id": 1,
      "name": "Merkez Birlik",
      "address": "Cumhuriyet Mah. İstasyon Cad. No:12/1 İstanbul",
      "stk": "STK-4589",
      "btk": "BTK-9021",
      "contactName": "Yzb. Murat Kaya",
      "contactRank": "Yuzbasi",
      "contactRegistry": "MK4587",
      "contactIdentity": "25478963210",
      "contactPhone": "+90 532 456 78 12",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}

POST /units

Yeni birlik oluşturur.

Yetki: Admin

İstek:

{
  "name": "Doğu Lojistik Birimi",
  "address": "Sanayi Mah. Depo Sok. No:8 Erzurum",
  "stk": "STK-7865",
  "btk": "BTK-6674",
  "contactName": "Uzm. Cav. Esra Yilmaz",
  "contactRank": "Uzman Cavus",
  "contactRegistry": "EY3345",
  "contactIdentity": "19876543219",
  "contactPhone": "+90 532 998 11 44"
}

PUT /units/:id

Birim bilgilerini günceller.

Yetki: Admin

DELETE /units/:id

Birim kaydını siler.

Yetki: Admin

Personel Yönetimi

GET /fuel-personnel

Tüm yakıt personelini listeler.

Yetki: Admin

Yanıt (200):

{
  "personnel": [
    {
      "id": 1,
      "fullName": "Astsb. Cahit Demir",
      "rank": "Astsubay",
      "registryNumber": "CD5561",
      "identityNumber": "14523698741",
      "phone": "+90 532 223 45 67",
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ]
}

POST /fuel-personnel

Yeni personel oluşturur.

Yetki: Admin

İstek:

{
  "fullName": "Sv. Uzm. Er Ali Korkmaz",
  "rank": "Sozlesmeli Er",
  "registryNumber": "AK7812",
  "identityNumber": "32987456100",
  "phone": "+90 555 893 22 10"
}

PUT /fuel-personnel/:id

Personel bilgilerini günceller.

Yetki: Admin

DELETE /fuel-personnel/:id

Personel kaydını siler.

Yetki: Admin

⚡ Yakıt Sorumlusu API

GET /fuel/resources

Yakıt fişi oluşturmak için gerekli kaynakları getirir.

Yetki: Yakıt Sorumlusu

Yanıt (200):

{
  "forces": ["MSB", "K.K.K.", "Dz.K.K.", "Hv.K.K.", "SGK", "Gnkur. Bşk.", "Hrt.Gn.K."],
  "vehicles": [
    {
      "id": 1,
      "brand": "Ford",
      "model": "Transit",
      "year": 2021,
      "plate": "34 AYT 312"
    }
  ],
  "units": [
    {
      "id": 1,
      "name": "Merkez Birlik",
      "address": "Cumhuriyet Mah. İstasyon Cad. No:12/1 İstanbul"
    }
  ],
  "personnel": [
    {
      "id": 1,
      "fullName": "Astsb. Cahit Demir",
      "rank": "Astsubay",
      "registryNumber": "CD5561",
      "phone": "+90 532 223 45 67"
    }
  ],
  "inventoryManagers": [
    {
      "id": 3,
      "displayName": "Mal Sorumlusu 1"
    }
  ]
}

GET /fuel-slips

Tüm yakıt fişlerini listeler.

Yetki: Yakıt Sorumlusu

Yanıt (200):

{
  "slips": [
    {
      "id": 1,
      "slipNumber": 1,
      "createdAt": "2024-01-01T10:00:00Z",
      "slipDate": "2024-01-01",
      "force": "MSB",
      "unitId": 1,
      "unitName": "Merkez Birlik",
      "vehicleId": 1,
      "vehicleDescription": "Ford Transit",
      "plate": "34 AYT 312",
      "fuelAmountNumber": 50,
      "fuelAmountText": "Elli",
      "fuelType": "Benzin",
      "receiverId": 1,
      "receiverName": "Astsb. Cahit Demir",
      "receiverRank": "Astsubay",
      "receiverRegistry": "CD5561",
      "receiverPhone": "+90 532 223 45 67",
      "giverId": 2,
      "giverName": "Sv. Uzm. Er Ali Korkmaz",
      "giverRank": "Sozlesmeli Er",
      "giverRegistry": "AK7812",
      "giverPhone": "+90 555 893 22 10",
      "notes": "Normal ikmal",
      "inventoryManagerId": 3,
      "inventoryManagerName": "Mal Sorumlusu 1",
      "fuelManagerId": 2,
      "status": "pending",
      "rejectionReason": null
    }
  ]
}

POST /fuel-slips

Yeni yakıt fişi oluşturur.

Yetki: Yakıt Sorumlusu

İstek:

{
  "date": "2024-01-01",
  "force": "MSB",
  "unitId": 1,
  "vehicleId": 1,
  "fuelAmountNumber": 50,
  "fuelAmountText": "Elli",
  "fuelType": "Benzin",
  "receiverId": 1,
  "giverId": 2,
  "receiverPhone": "+90 532 223 45 67",
  "giverPhone": "+90 555 893 22 10",
  "notes": "Normal ikmal",
  "inventoryManagerId": 3
}

Yanıt (201):

{
  "slip": {
    "id": 2,
    "slipNumber": 2,
    // ... diğer fiş bilgileri
  }
}

GET /fuel-slips/:id/pdf

Yakıt fişini PDF formatında indirir.

Yetki: Yakıt Sorumlusu

Yanıt (200) - PDF dosyası Content-Type: application/pdf Content-Disposition: inline; filename=akaryakit-senedi-0002.pdf

📋 Mal Sorumlusu API

GET /fuel-slips/assigned

Kullanıcıya atanan yakıt fişlerini listeler.

Yetki: Mal Sorumlusu

Yanıt (200):

{
  "slips": [
    {
      "id": 1,
      "slipNumber": 1,
      "status": "pending",
      // ... diğer fiş bilgileri
    }
  ]
}

PATCH /fuel-slips/:id/status

Yakıt fişini onaylar veya reddeder.

Yetki: Mal Sorumlusu

İstek (Onay):

{
  "status": "approved"
}

İstek (Red):

{
  "status": "rejected",
  "reason": "Araç bakımda olduğu için ikmal yapılamaz"
}

Yanıt (200):

{
  "slip": {
    "id": 1,
    "status": "approved",
    "rejectionReason": null
  }
}

🔌 WebSocket Olayları

Bağlantı

const socket = io('http://localhost:5005', {
  auth: {
    token: '<session-token>'
  }
});

Mal Sorumlusu Olayları

fuelSlip:new

Yeni yakıt fişi atandığında tetiklenir.

socket.on('fuelSlip:new', (slip) => {
  console.log('Yeni fiş:', slip);
});

fuelSlip:status

Fiş durumu güncellendiğinde tetiklenir.

socket.on('fuelSlip:status', (slip) => {
  console.log('Fiş durumu güncellendi:', slip.status);
});

Yakıt Sorumlusu Olayları

fuelSlip:status

Fiş durumu güncellendiğinde tetiklenir.

socket.on('fuelSlip:status', (slip) => {
  console.log('Fiş durumu:', slip.status, 'Sebep:', slip.rejectionReason);
});

⚠️ Hata Kodları

HTTP Durum Kodları

  • 200 - Başarılı
  • 201 - Oluşturuldu
  • 204 - İçerik Yok
  • 400 - Geçersiz İstek
  • 401 - Yetkisiz
  • 403 - Yasak
  • 404 - Bulunamadı
  • 409 - Çakışma
  • 500 - Sunucu Hatası

Hata Mesajları

{
  "message": "Kullanici adi ve sifre zorunlu.",
  "error": "Validation error"
}

Yaygın Hata Senaryoları

  • Session expired: Token geçersiz veya süresi dolmuş
  • Insufficient permissions: İstek için yetki yok
  • Resource not found: İstenen kaynak bulunamadı
  • Validation failed: Gerekli alanlar eksik veya geçersiz
  • Database constraint: Veritabanı kısıtlaması ihlali

📝 Örnek Kod

JavaScript/Node.js

const axios = require('axios');

class YTPClient {
  constructor(baseURL) {
    this.client = axios.create({
      baseURL,
      headers: {
        'Content-Type': 'application/json'
      }
    });
  }

  async login(username, password) {
    const response = await this.client.post('/auth/login', {
      username,
      password
    });

    this.token = response.data.token;
    this.client.defaults.headers['X-Session-Token'] = this.token;

    return response.data.user;
  }

  async createFuelSlip(slipData) {
    const response = await this.client.post('/fuel-slips', slipData);
    return response.data.slip;
  }

  async getFuelSlips() {
    const response = await this.client.get('/fuel-slips');
    return response.data.slips;
  }
}

// Kullanım
const client = new YTPClient('http://localhost:5005/api');
await client.login('yakitsorum', 'Yakit@123');
const slips = await client.getFuelSlips();

curl Örnekleri

# Giriş
curl -X POST http://localhost:5005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin!123"}'

# Yeni araç ekleme
curl -X POST http://localhost:5005/api/vehicles \
  -H "Content-Type: application/json" \
  -H "X-Session-Token: YOUR_TOKEN" \
  -d '{"brand":"Ford","model":"Transit","year":2021,"plate":"34 AYT 312"}'

# Yakıt fişlerini listeleme
curl -X GET http://localhost:5005/api/fuel-slips \
  -H "X-Session-Token: YOUR_TOKEN"

Not: Bu API dokümantasyonu geliştirme sürecinde güncellenebilir. Değişiklikler için release notlarını kontrol edin.

Reference in New Issue View Git Blame Copy Permalink