MaxiFilo REST API

Filo yönetimi, servis talepleri ve evrak işlemleri için RESTful API

Base URL: https://uat-api.maxifilo.com.tr/api

API Açıklaması

MaxiFilo REST API, araç filosu yönetimi, servis talep takibi, evrak ve fatura işlemlerini programatik olarak gerçekleştirmenizi sağlar. Token tabanlı kimlik doğrulama kullanır.

REST Mimarisi

HTTP metodları: GET (okuma), POST (oluşturma/güncelleme)
JSON request/response formatı
Bearer token ile yetkilendirme
RESTful URL yapısı: /v1/kaynak/alt_kaynak

JSON Response Formatı

Başarılı yanıtlar data objesi içerir. Hata durumunda error veya message alanı döner. Sayfalama için meta.pagination kullanılır.

Authentication

API erişimi için önce POST /v1/token ile access token alın. Sonraki tüm isteklerde Authorization: Bearer {access_token} header'ı kullanın.

POST/v1/token

Auth: Gerekmez

Kullanıcı adı ve şifre ile access token alır.

Request Body

{
  "kullanici_adi": "test",
  "sifre": "Test_123123"
}

Başarılı Response

{
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "cari_id": 123
  }
}

POST/v1/token/refresh

Auth: Gerekmez

Refresh token ile yeni access token alır.

Request Body

{
  "refresh_token": "{{refresh_token}}"
}

Authorization kullanımı:
Authorization: Bearer {access_token}

Ortak Endpoint

Kimlik doğrulaması gerektirmeyen ortak servisler.

GET/v1/health

Açıklama

Sunucu sağlık kontrolü. API'nin ayakta olduğunu doğrulamak için kullanılır. Monitoring ve load balancer sağlık kontrollerinde kullanılabilir.

Yetkilendirme

Yok Bearer token gerekmez.

Olası Yanıtlar

200 OK — Sunucu çalışıyor

Tanımlar

Sistemdeki referans verilerini (dropdown, filtre vb.) almak için kullanılan endpoint'ler. Tüm tanım endpoint'leri Bearer Token gerektirir ve aynı response formatını kullanır.

GET/v1/tanimlar/talep_turleri

Açıklama

Servis talebinin türünü belirten tanımlar (Bakım, Hasar, Arıza vb.). SERVIS_BOLUM tablosundan beslenir. Dosya arama filtresinde talep_turu_id olarak kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Örnek Yanıt

{
  "data": [
    {
      "id": "BAKIM",
      "name": "Bakım"
    },
    {
      "id": "HASAR",
      "name": "Hasar"
    },
    {
      "id": "ARIZA",
      "name": "Arıza"
    }
  ]
}

Hata Kodları

401 Unauthorized — Token eksik veya geçersiz

GET/v1/tanimlar/surecler

Açıklama

Talep süreç durumları (Araç Bekliyor, Onayda, vb.). SUREC tablosundan beslenir. Dosya aramada surec_id filtresi olarak kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Örnek Yanıt

{
  "data": [
    {
      "id": 1,
      "name": "Araç Bekliyor"
    },
    {
      "id": 2,
      "name": "Onayda"
    }
  ]
}

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/servis_bolumleri

Açıklama

Servis bölümleri listesi. Talep türlerinden farklı olarak servis içi organizasyonel sınıflandırma için kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/yakit_turleri

Açıklama

Araç yakıt türleri (Benzin, Dizel, LPG, Elektrik vb.). YAKIT tablosundan. Dosya detayında araç bilgisi olarak kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/vites_turleri

Açıklama

Vites türleri (Manuel, Otomatik, Yarı Otomatik). VITES tablosundan. Dosya detayında araç bilgisi olarak kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/hizmet_turleri

Açıklama

Hizmet türleri listesi. HIZMET tablosundan. Servis hizmet sınıflandırması için kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/evrak_turleri

Açıklama

Evrak türleri (Ekspertiz Raporu, Fatura, vb.). Evraklar ve fotoğraflar endpoint'lerindeki evrak_tipi_id ile eşleştirilir.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/resim_turleri

Açıklama

Fotoğraf/resim türleri kategorileri. EVRAK tablosundan (EVRAK_BOLUM_ID=1). Fotoğraflar endpoint'inde sınıflandırma için kullanılır.

Yetkilendirme

Bearer Token Zorunlu

Hata Kodları

401 Unauthorized

GET/v1/tanimlar/markalar

Araç marka listesi. MARKA tablosundan.

GET/v1/tanimlar/modeller?marka_id=1

Markaya göre model listesi. marka_id query parametresi zorunlu.

GET/v1/tanimlar/segmentler

Araç segment listesi.

GET/v1/tanimlar/model_yillari

Model yılı listesi. Yanıt: id, name, model_yili

Dosya Endpointleri

Servis taleplerinin (dosya) arama, detay, evrak ve fatura işlemleri. Tüm dosya endpoint'leri Bearer Token gerektirir. Token'daki cari_id ile filo kapsamı belirlenir.

GET/v1/dosya/ara

Açıklama

Servis taleplerini filtreleyerek arar. Token'daki cari_id ile yetkili filo kapsamındaki talepler döner. Tarih filtreleri çift (başlangıç + bitiş) olarak uygulanır.

Yetkilendirme

Bearer Token Zorunlu

Query Parametreleri

Parametre	Tip	Açıklama
talep_tarihi_baslangic	date	Talep tarihi başlangıç (YYYY-MM-DD)
talep_tarihi_bitis	date	Talep tarihi bitiş
teslim_tarihi_baslangic	date	Teslim edildi tarihi başlangıç
teslim_tarihi_bitis	date	Teslim edildi tarihi bitiş
tahmini_teslim_tarihi_baslangic	date	Tahmini teslim tarihi başlangıç
tahmini_teslim_tarihi_bitis	date	Tahmini teslim tarihi bitiş
arac_gelis_tarihi_baslangic	date	Araç servise geliş tarihi başlangıç
arac_gelis_tarihi_bitis	date	Araç servise geliş tarihi bitiş
dosya_no	string	Dosya numarası (LIKE arama)
plaka	string	Araç plakası (LIKE arama)
surec_id	int	Süreç ID (tanimlar/surecler'den)
servis_id	int	Servis (cari) ID
talep_turu_id	string	Talep türü (BAKIM, HASAR, ARIZA vb.)
page	int	Sayfa no (default: 1)
page_size	int	Sayfa boyutu (default: 20, max: 100)

Örnek Yanıt

{
  "data": [
    {
      "id": 269,
      "dosya_no": "123123123",
      "arac": {
        "plaka": "41ZN123",
        "marka": "AUDI",
        "model": "A1 1.2 TFSI",
        "km": 45000,
        "talep_tarihi": "2025-01-15",
        "tahmini_teslim_tarihi": "2025-01-25"
      },
      "servis": {
        "servis_id": 10,
        "servis_adi": "RAK Otomotiv"
      },
      "surec_id": 3,
      "surec_adi": "Araç Bekliyor",
      "talep_turu_id": "ARIZA"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 45,
      "total_pages": 3
    }
  }
}

Hata Kodları

401 Unauthorized — 403 Forbidden (Geçerli filo kimliği yok) — 400 Bad Request

GET/v1/dosya/detay/{id}

Açıklama

Tek bir servis talebinin tüm detayını getirir. Araç bilgileri, servis, sürücü, şikayetler, yedek parçalar, işçilikler, talep notları dahil.

Path Parametresi

{id} — Dosya ID (numara) veya dosya_no (string)

Yetkilendirme

Bearer Token Zorunlu

Yanıt Alanları

id, dosya_no, talep_tarihi, arac_gelis_tarihi, tahmini_teslim_tarihi, teslim_tarihi, arac (plaka, marka, model, km, sasi_no, motor_no, yakit_turu, vites_turu), servis, talep_tipi, talep_sureci, surucu, sikayet_talep, cekici_talebi, ikame_var, yedek_parcalar (parca_kodu, parca_adi, adet, fiyat, iskonto, tedarikci_adi vb.), iscilikler, talep_notlari

Hata Kodları

401 Unauthorized — 403 Forbidden — 404 Not Found — 422 Validation Error (geçersiz id)

GET/v1/dosya/evraklar/{id}

Açıklama

Talep numarasına ait evrakları (PDF, resim vb.) base64 formatında döner. EVRAK_BOLUM_ID ≠ 1 olanlar (ekspertiz raporu, fatura örneği vb. belgeler). Sayfalama: page, page_size (default 50, max 100).

Path Parametresi

{id} — Talep ID veya dosya_no

Yanıt Yapısı (her öğe)

evrak_adi, evrak_tipi_id, evrak_tipi_adi, base64

Base64 Decode

İkili veri metin olarak taşınır. Decode ile orijinal dosyaya dönüştürülebilir:

// Tarayıcı (JavaScript)
var binary = atob(base64String);

// Node.js
var buffer = Buffer.from(base64String, 'base64');

// Python
import base64
binary = base64.b64decode(base64_string)

Hata Kodları

401 Unauthorized — 404 Not Found — 422 Validation Error

GET/v1/dosya/fotograflar/{id}

Açıklama

Talep numarasına ait fotoğrafları base64 formatında döner. EVRAK_BOLUM_ID=1 (resim türü). Evraklar endpoint'i ile aynı yapı. Sayfalama desteklenir.

Path Parametresi

{id} — Talep ID veya dosya_no

Yanıt Yapısı

evrak_adi, evrak_tipi_id, evrak_tipi_adi, base64

Hata Kodları

401 Unauthorized — 404 Not Found — 422 Validation Error

GET/v1/dosya/faturalar/{id}

Açıklama

Talep numarasına ait faturaları ve her faturaya bağlı evrakları (base64) döner. CARI_HAREKET tablosundan finans kalemleri 1,2 (fatura vb.). Sayfalama: page, page_size (default 20, max 100).

Path Parametresi

{id} — Talep ID veya dosya_no

Örnek Yanıt

{
  "data": [
    {
      "id": 1001,
      "kod": "CH001",
      "fatura_no": "FTR2025001",
      "fatura_tarih": "2025-01-20",
      "tutar": 5250.50,
      "kdv_tutar": 945.09,
      "evraklar": [
        {
          "evrak_adi": "fatura.pdf",
          "base64": "JVBERi0xLjQK..."
        }
      ]
    }
  ]
}

Hata Kodları

401 Unauthorized — 404 Not Found — 422 Validation Error

Araç Endpointleri

Filo araç listeleme, detay, oluşturma ve güncelleme. Bearer Token zorunludur. cari_id ve ruhsat sahibi token'dan alınır. Marka/model tsrb_kodu ile backend'de eşleştirilir. Tanım listeleri için Tanımlar bölümünü kullanın (segmentler, model_yillari, yakit_turleri, vites_turleri).

Araç Alanları

Alan	Tip	Açıklama
cari_id / cari	int / string	Token'dan gelir, yanıtta döner
ruhsat_sahibi_id / ruhsat_sahibi	int / string	Token cari'den otomatik atanır
plaka	string	Zorunlu (oluşturma), min 3 karakter
tsrb_kodu	string	Zorunlu (oluşturma), 4-7 haneli sayı; AracExcel ile aynı eşleşme
marka_id / marka	int / string	Yanıtta döner (TSRB'den hesaplanır)
model_id / model	int / string	Yanıtta döner (TSRB'den hesaplanır)
segment_id / segment	int / string	Zorunlu (oluşturma)
model_yili	int	Zorunlu (oluşturma)
yakit_id / yakit	int / string	Zorunlu (oluşturma)
vites_id / vites	int / string	Zorunlu (oluşturma)
sasi_no	string	Zorunlu (oluşturma)
motor_no	string	Zorunlu (oluşturma)
durum	int	Zorunlu (oluşturma): 0 = Pasif, 1 = Aktif
son_km	int	Zorunlu (oluşturma), 0 ve üzeri
tamamlanma_yuzdesi	float	Otomatik hesaplanır (create/update), yanıtta döner

GET/v1/arac

Token cari kapsamındaki araçları listeler.

Query: plaka, durum (0/1), page, page_size

GET/v1/arac/{id}

Tek araç detayını getirir. Araç token cari kapsamında değilse 404 döner.

POST/v1/arac

Zorunlu alanlar: plaka, tsrb_kodu (4-7 hane), model_yili, motor_no, sasi_no, durum, segment_id, yakit_id, vites_id, son_km. tsrb_kodu eşleşmesi AracExcel ile aynıdır: önce marka+tip birleşimi, 4 haneli kodda tip kodu. Ruhsat sahibi token cari_id'den otomatik doldurulur.

{
  "plaka": "34ABC123",
  "tsrb_kodu": "0521234",
  "model_yili": 2022,
  "motor_no": "CAX123456",
  "sasi_no": "WVWZZZ1KZAW123456",
  "durum": 1,
  "segment_id": 1,
  "yakit_id": 2,
  "vites_id": 1,
  "son_km": 45000
}

PUT/v1/arac/{id}

Mevcut aracı günceller. Gönderilen alanlar güncellenir; gönderilmeyenler korunur.

Global Response Formatı

Başarılı

{
  "success": true,
  "message": "İşlem başarılı",
  "data": {},
  "meta": {
    "timestamp": "2025-02-26T12:00:00+00:00",
    "pagination": { ... }
  }
}

Hata

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Hata mesajı"
  },
  "meta": {
    "timestamp": "2025-02-26T12:00:00+00:00"
  }
}

HTTP Status Kodları

Kod	Açıklama
`200`	OK - Başarılı
`201`	Created - Oluşturuldu
`400`	Bad Request - Geçersiz istek
`401`	Unauthorized - Yetkisiz (token eksik/geçersiz)
`404`	Not Found - Kaynak bulunamadı
`422`	Validation Error - Doğrulama hatası
`500`	Internal Server Error - Sunucu hatası