Analytics API v1

Kimlik Doğrulama

Tüm isteklerde HTTP header'ına API anahtarınızı eklemeniz gerekmektedir:

x-api-key: <API_KEY>

API anahtarınız yalnızca size atanmış projelere erişim sağlar. Atanmamış bir projectId ile istek atarsanız 403 alırsınız.

Base URL

Ortam	URL
Production	`https://remote.saharobotik.com/api/client/analytics`
Staging	`https://staging.saharobotik.com/api/client/analytics`

Swagger Dokümantasyonu

Ortam	URL
Production	`https://remote.saharobotik.com/api/swagger/client/analytics`
Staging	`https://staging.saharobotik.com/api/swagger/client/analytics`

Rate Limit

Her endpoint için dakikada maksimum 6 istek yapılabilir.
Limit aşıldığında 429 Too Many Requests hatası döner ve 60 saniye sonra limit sıfırlanır.

Endpoint Özeti

Analytics

Method	Path	Açıklama
`POST`	`/nltx/summary/{projectId}`	Projeye ait özet istatistik verisi
`POST`	`/nltx/summary/{projectId}/robot/{robotId}`	Belirli bir robota ait özet istatistik verisi
`POST`	`/nltx/positions/{projectId}/robot/{robotId}`	Robot pozisyon verileri
`POST`	`/nltx/analyzes/{projectId}/latests`	Projenin son analiz sonuçları (max 10)
`GET`	`/nltx/anomalies/{projectId}/anomaly/{anomalyId}`	Belirli anomali detayı
`GET`	`/nltx/deliveries/average`	Tüm projelerin ortalama teslimat süreleri
`GET`	`/nltx/data/{projectId}/most-delivered-locations`	En çok teslimat yapılan konumlar (son 3 ay)

Tablet Konfigürasyon

Method	Path	Açıklama
`GET`	`/projects/{projectId}/tablet-config/activated`	Projenin aktif tablet konfigürasyonu

Not: Analytics endpoint'lerinde (summary, analyzes, anomaly vb.) response içindeki project_id string olarak gelir (ör. "123"). Tablet config endpoint'inde project_id number olarak gelir (ör. 7). URL'deki {projectId} her zaman sayısal kullanılır. Karşılaştırırken String(project_id) kullanın.

Proje özet istatistikleri

POST /nltx/summary/{projectId}

Projeye ait özet istatistik verisi döndürür.

Request body

{
  "interval": "week"
}

interval değerleri (zorunlu):

week — son 1 hafta (-1w)
month — son 1 ay (-1m)

Response

{
  "last_km": 1250.5,
  "last_wh": 340.2,
  "last_iah": 280.1,
  "data_km": [
    { "date": "2026-06-10T00:00:00Z", "value": 12.3 },
    { "date": "2026-06-11T00:00:00Z", "value": 15.7 }
  ],
  "data_km_avg": 14.0,
  "data_wh": [
    { "date": "2026-06-10T00:00:00Z", "value": 5.2 },
    { "date": "2026-06-11T00:00:00Z", "value": 6.1 }
  ],
  "data_wh_avg": 5.65,
  "data_iah": [
    { "date": "2026-06-10T00:00:00Z", "value": 4.1 },
    { "date": "2026-06-11T00:00:00Z", "value": 4.8 }
  ],
  "data_iah_avg": 4.45,
  "data_logs": [
    { "date": "2026-06-10T00:00:00Z", "code": "ROBOT_DELIVERY_TASK_SUCCESS", "value": 42 }
  ],
  "data_logs_avg": [
    { "code": "ROBOT_DELIVERY_TASK_SUCCESS", "value": 38 }
  ],
  "today": "2026-06-17T00:00:00Z",
  "interval": ["2026-06-10T00:00:00Z", "2026-06-11T00:00:00Z"],
  "most_delivered_locations": [
    { "key": "Masa 5", "value": 120 }
  ]
}

Robot özet istatistikleri

POST /nltx/summary/{projectId}/robot/{robotId}

Belirli bir robota ait özet istatistik verisi döndürür.

Request body

{
  "interval": "week"
}

interval değerleri (zorunlu):

week — son 1 hafta (-1w)
month — son 1 ay (-1m)

Response

Summary endpoint'i ile aynı yapıda özet istatistik verisi döner.

Robot pozisyon verileri

POST /nltx/positions/{projectId}/robot/{robotId}

Robot pozisyon verileri döndürür.

Request body

{
  "interval": "week",
  "code": "ROBOT_FAILURE",
  "map": "map_name"
}

interval, code ve map alanlarının tamamı zorunludur.

interval değerleri:

week — son 1 hafta (-1w)
month — son 1 ay (-1m)

code değerleri: ROBOT_FAILURE, ROBOT_NAV_STUCK, ROBOT_LOC_LOST, ROBOT_INTERNET_CONN_FAILED, vb.

Response

[
  { "x": 12.34, "y": 56.78, "yaw": 1.57 }
]

Son analiz sonuçları

POST /nltx/analyzes/{projectId}/latests

Projenin son analiz sonuçlarını döndürür (max 10).

Request body gerekmez. Sadece projectId path parametresi yeterlidir.
POST istekleri 201 status kodu ile yanıt verir (NestJS varsayılanı).

anomaly_id değerini bu endpoint'ten alırsınız. Dolu ise anomali detayı için GET /nltx/anomalies/{projectId}/anomaly/{anomalyId} çağrılır.

Response

Analiz yoksa boş array döner:

[]

Analiz varsa en fazla 10 kayıt döner:

[
  {
    "id": "analysis-id-001",
    "project_id": "123",
    "robot_id": "robot-001",
    "calculator": "weekly",
    "score": {
      "value": 85,
      "based_on": 100
    },
    "metrics": [
      {
        "id": "metric-id-001",
        "key": "ODOM_KM",
        "point": 10,
        "weight": 1
      }
    ],
    "suggestions": [
      {
        "id": "suggestion-id-001",
        "key": "SUGGESTION_INCREASE_DISTANCE_TRAVELED",
        "code": "SUGGESTION_INCREASE_DISTANCE_TRAVELED",
        "severity": "medium"
      }
    ],
    "created_at": "2026-01-15T10:00:00Z",
    "start_date": "2026-01-08T00:00:00Z",
    "end_date": "2026-01-15T00:00:00Z",
    "anomaly_id": "anomaly-id-001",
    "previous_scores": [
      {
        "value": 80,
        "based_on": 100
      }
    ]
  }
]

Alan	Tür	Açıklama
`id`	`string`	Analiz kaydı ID'si
`project_id`	`string`	Proje ID'si
`robot_id`	`string`	Robot ID'si. Opsiyonel; proje bazlı analizlerde boş olabilir
`anomaly_id`	`string`	Anomali ID'si. Boş ise anomali yoktur
`score`	`object`	Analiz skoru
`metrics`	`array`	Metrik listesi
`suggestions`	`array`	Öneri listesi

Anomali detayı

GET /nltx/anomalies/{projectId}/anomaly/{anomalyId}

Belirli anomali detayını döndürür.

anomaly_id değeri analyzes/latests response'undan alınır.
projectId ile anomalyId eşleşmezse 404 döner.

Response

{
  "id": "anomaly-id-001",
  "project_id": "123",
  "robot_id": "robot-001",
  "detector": "threshold",
  "anomalies": [
    {
      "detector": "threshold",
      "key": "ODOM_KM",
      "code": "ANOMALY_ODOM_KM_IS_HIGHER_THAN_EXPECTED",
      "type": "too_high",
      "level": 2,
      "percentage": 35.5
    }
  ],
  "created_at": "2026-01-15T10:00:00Z"
}

Ortalama teslimat süreleri

GET /nltx/deliveries/average

Tüm projelerin ortalama teslimat sürelerini döndürür.

Bu endpoint URL'de projectId almaz. Sistemdeki tüm projelerin ortalama teslimat sürelerini döner (API key'e atanmış projeler filtrelenmez).

Response tipi: Record<string, string> — proje ID → süre string.

Response

{
  "42": "8m45s",
  "56": "12m30s"
}

En çok teslimat yapılan konumlar

GET /nltx/data/{projectId}/most-delivered-locations

En çok teslimat yapılan konumları döndürür (son 3 ay).

Son 3 aylık veriyi döner (backend sabit -3m). Yetkisiz projectId için 403 döner.

Response

[
  { "key": "Masa 5", "value": 120 },
  { "key": "Lobby", "value": 85 }
]

Aktif Tablet konfigürasyonu

GET /projects/{projectId}/tablet-config/activated

Projenin aktif tablet konfigürasyonunu döndürür.

Aktif konfigürasyon yoksa 404 ve Active tablet config not found mesajı döner.

Response

{
  "id": 96,
  "project_id": 7,
  "name": "Konfigürasyon Adı",
  "activated": true,
  "deleted": false,
  "checksum": "2a308a87",
  "created_at": "2023-03-29T20:29:57.539Z",
  "updated_at": "2026-04-29T06:27:25.566Z",
  "config": {
    "videos": {
      "home": {
        "enabled": true,
        "src": [
          "https://assets.saharobotik.com/video/.../video1.mp4",
          "https://assets.saharobotik.com/video/.../video2.mp4"
        ],
        "loop": true,
        "muted": true
      },
      "going": {
        "enabled": false
      },
      "sleeping": {
        "enabled": false
      },
      "pixelGoing": {
        "enabled": false
      },
      "pixelSleeping": {
        "enabled": false
      },
      "celebrating": {
        "enabled": false
      },
      "celebratingAtTheTarget": {
        "enabled": false
      }
    }
  }
}

Video Alanları

Alan	Tür	Açıklama
`config.videos.home.src`	`string \| string[]`	Pixel ekranında varsayılan video URL'leri (tek URL veya array)
`config.videos.home.enabled`	`boolean`	Opsiyonel. `false` ise video kapalı, yoksa veya `true` ise açık

videos alanı opsiyoneldir; projede video ayarlanmamışsa config içinde bulunmaz.

Hata Kodları

Kod	Açıklama
`400`	Geçersiz istek / NLTX servis hatası
`401`	API anahtarı geçersiz veya eksik
`403`	Bu projeye erişim yetkiniz yok
`404`	Kayıt bulunamadı
`429`	Rate limit aşıldı, 60 saniye bekleyin
`500`	Sunucu hatası

İçindekiler