Geliştirici

Rotiva API Dokümanı

Rotiva genel API'siyle kendi yazılımınızdan (ERP, muhasebe, e-ticaret) sevkiyat havuzuna teslimat gönderebilir, teslimat durumunu ve müşteri listenizi sorgulayabilirsiniz. Tüm cevaplar JSON'dır.

Taban adres: https://www.rotiva.cloud/api/v1

Kimlik doğrulama

API anahtarınızı Rotiva panelinde Ayarlar → Entegrasyonlar → API erişimi bölümünden oluşturursunuz. Anahtar yalnızca oluşturulduğu anda bir kez gösterilir; her istekte Authorization başlığıyla gönderilir:

Authorization: Bearer rtv_sizin_anahtariniz
# veya
X-Api-Key: rtv_sizin_anahtariniz

Anahtar firmanıza bağlıdır: yalnızca kendi firmanızın verilerine erişir. Geçersiz/iptal edilmiş anahtar 401, hız sınırı aşımı 429 döner. Hatalar her uçta aynı biçimdedir:

{ "hata": "Açıklayıcı Türkçe hata mesajı" }

Hız sınırları: okuma uçları dakikada 60 istek, teslimat oluşturma dakikada 20 kayıt ile sınırlıdır.

Uçlar

GET/musteriler

Müşteri listesi

Firmanızın aktif müşterilerini döner. Teslimat oluşturmak için gereken musteri_id buradan bulunur (API üzerinden yeni müşteri açılamaz — adres/koordinat doğruluğu için müşteri kartları panelden yönetilir).

Parametreler: arama (isteğe bağlı; ad/adres/telefonda Türkçe-duyarsız arama), limit (varsayılan 50, en çok 100).

curl "https://www.rotiva.cloud/api/v1/musteriler?arama=mado" \
  -H "Authorization: Bearer rtv_..."

# 200
{
  "musteriler": [
    {
      "id": "9b2f…",
      "ad": "Mado Çorum Şubesi",
      "adres": "Gazi Cad. No:12 Çorum",
      "telefon": "0532 111 22 33",
      "yetkili_kisi": "Ahmet Bey",
      "aktif": true,
      "created_at": "2026-05-14T08:21:00Z"
    }
  ]
}

POST/teslimatlar

Teslimat oluştur

Sevkiyat havuzuna yeni bir teslimat ekler; sürücüleriniz kaydı havuzda görür, yöneticiler panelde takip eder. kalemler verirseniz kayıt sipariş kalemleriyle açılır (sürücü teslim ekranında ürün listesi görür, kısmi teslim izlenir).

Gövde alanları: musteri_id (zorunlu), aciklama, koli_sayisi, son_teslim_zamani (ISO 8601), oncelik (dusuk | normal | yuksek | acil), kalemler[] (urun, adet, birim: adet | koli).

curl -X POST "https://www.rotiva.cloud/api/v1/teslimatlar" \
  -H "Authorization: Bearer rtv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "musteri_id": "9b2f…",
    "aciklama": "Sabah sevkiyatı",
    "oncelik": "normal",
    "son_teslim_zamani": "2026-08-25T18:00:00+03:00",
    "kalemler": [
      { "urun": "Dondurma 5L Kayısı", "adet": 3, "birim": "koli" },
      { "urun": "Külah 500lü", "adet": 2, "birim": "adet" }
    ]
  }'

# 201
{
  "id": "4d81…",
  "durum": "bekliyor",
  "created_at": "2026-08-24T09:12:44Z",
  "takip_linki": "https://rotiva.cloud/t/aB3kT9xQ"
}

takip_linki müşteriyle paylaşabileceğiniz herkese açık canlı takip sayfasıdır. Müşteri bulunamazsa 422 döner.

GET/teslimatlar

Teslimat listesi

Parametreler: durum (acik varsayılan — teslim edilmemiş kayıtlar; kapali — teslimi yazılmış kayıtlar), limit (varsayılan 50, en çok 100).

curl "https://www.rotiva.cloud/api/v1/teslimatlar?durum=acik&limit=20" \
  -H "Authorization: Bearer rtv_..."

# 200
{
  "teslimatlar": [
    {
      "id": "4d81…",
      "tip": "teslimat",
      "durum": "bekliyor",
      "koli_sayisi": null,
      "aciklama": "Sabah sevkiyatı",
      "oncelik": "normal",
      "son_teslim_zamani": "2026-08-25T15:00:00Z",
      "teslim_zamani": null,
      "created_at": "2026-08-24T09:12:44Z",
      "musteri": { "id": "9b2f…", "ad": "Mado Çorum Şubesi" }
    }
  ]
}

GET/teslimatlar/{id}

Teslimat durumu

Tek teslimatın güncel durumunu, teslim bilgilerini ve (varsa) sipariş kalemlerini teslim işaretleriyle döner.

curl "https://www.rotiva.cloud/api/v1/teslimatlar/4d81…" \
  -H "Authorization: Bearer rtv_..."

# 200
{
  "id": "4d81…",
  "tip": "teslimat",
  "durum": "teslim_edildi",
  "teslim_zamani": "2026-08-24T14:03:20Z",
  "teslim_notu": "Depoya bırakıldı",
  "kalemler": [
    { "urun": "Dondurma 5L Kayısı", "adet": 3, "birim": "koli", "teslim_adet": 3 }
  ],
  "takip_linki": "https://rotiva.cloud/t/aB3kT9xQ",
  "musteri": { "id": "9b2f…", "ad": "Mado Çorum Şubesi" }
}

durum değerleri: bekliyor · secildi · yolda · teslim_edildi · kismi_teslim · teslim_edilemedi

Sık sorulanlar

API üzerinden müşteri oluşturabilir miyim?

Hayır. Teslimat, haritada doğru bir koordinat ister; adres → koordinat dönüşümü panelde adres otomatik tamamlamayla yapılır. Müşterilerinizi bir kez panelden ekleyin, API'den musteri_id ile eşleyin.

Teslimat tamamlanınca bildirim (webhook) alabilir miyim?

Webhook desteği henüz yok — durumu GET /teslimatlar/{id} ile sorgulayabilirsiniz. İhtiyacınız varsa bize yazın; yol haritamızda önceliklendirelim.

Sorum var / hata buldum

Panelden Ayarlar → Destek üzerinden veya destek@rotiva.cloud adresinden ulaşın.

Henüz Rotiva kullanmıyor musunuz?

Ücretsiz deneme hesabı açın, API anahtarınızı dakikalar içinde oluşturun.

Ücretsiz deneyin