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

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
ParametreTipAçıklama
talep_tarihi_baslangicdateTalep tarihi başlangıç (YYYY-MM-DD)
talep_tarihi_bitisdateTalep tarihi bitiş
teslim_tarihi_baslangicdateTeslim edildi tarihi başlangıç
teslim_tarihi_bitisdateTeslim edildi tarihi bitiş
tahmini_teslim_tarihi_baslangicdateTahmini teslim tarihi başlangıç
tahmini_teslim_tarihi_bitisdateTahmini teslim tarihi bitiş
arac_gelis_tarihi_baslangicdateAraç servise geliş tarihi başlangıç
arac_gelis_tarihi_bitisdateAraç servise geliş tarihi bitiş
dosya_nostringDosya numarası (LIKE arama)
plakastringAraç plakası (LIKE arama)
surec_idintSüreç ID (tanimlar/surecler'den)
servis_idintServis (cari) ID
talep_turu_idstringTalep türü (BAKIM, HASAR, ARIZA vb.)
pageintSayfa no (default: 1)
page_sizeintSayfa 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

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ı

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