Logistica REST API

Sürüm v1 · JSON · HTTPS

TMS, ERP ya da kendi yazılımınızdan ilan açın, teklifleri yönetin, anlaşma durumlarını ve araç konumlarını aktarın. Olaylar webhook ile anında sisteminize gelir.

Başlangıç

Temel adres: https://alfaloji.forum/api/v1. Anahtarı Entegrasyonlar sayfasından firma sahibi oluşturur; anahtar yalnızca bir kez gösterilir. “Okuma” anahtarları yalnızca GET isteği yapabilir. Anahtar başına dakikada 120 istek sınırı vardır (X-RateLimit-Remaining başlığı).

Tarihler ISO 8601 (UTC) döner; gönderirken saat dilimi belirtebilir ya da ilanın timezone alanına göre yerel saat yazabilirsiniz. Numaralar platformdaki gibidir: ilan için UUID, teklif T-…, anlaşma A-…, firma F-….

Kimlik doğrulama

curl https://alfaloji.forum/api/v1/me \
  -H "Authorization: Bearer lgk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Anahtar, oluşturan kişinin firmadaki yetkisiyle çalışır. Kişi firmadan ayrılır ya da yetkisi düşerse anahtar çalışmayı durdurur; yeni anahtar oluşturun. Anahtarı istemci tarafı koda (tarayıcı, mobil uygulama) koymayın.

Yanıtlar ve hatalar

Başarılı yanıtlar {"data": …}, hatalar {"error": {"code", "message"}} biçimindedir. Mesaj dili Accept-Language başlığına göre (tr, en, ru) seçilir.

HTTP	Kod	Anlamı
401	unauthorized, invalid_key	Anahtar yok, geçersiz ya da iptal edilmiş.
403	insufficient_scope, forbidden	Okuma anahtarıyla yazma ya da yetkisiz işlem.
403	plan_required	API erişimi firmanızın üyelik paketine dahil değil (Kurumsal paket).
404	not_found	Kayıt yok ya da firmanıza ait değil.
422	validation, confirmation_required	Alan hatası ya da iş kuralı (ör. doğrulanmamış firma).
429	rate_limited	`Retry-After` saniye sonra tekrar deneyin.

Hesap

GET	`/me`	Anahtarın bağlı olduğu firma, yetki kapsamı ve kullanıcı.
GET	`/events`	Webhook olay türlerinin listesi.

İlanlar

GET	`/listings`	Firmanızın ilanları. Filtre: status, kind, limit, offset.
POST	`/listings`	İlan oluşturur. "publish": true ile hemen yayımlar.
GET	`/listings/{id}`	Tek ilan.
PATCH	`/listings/{id}`	İlanı günceller; yayındaysa yeni sürüm olur ve teklif verenlere bildirilir.
POST	`/listings/{id}/publish`	Taslağı yayımlar.
POST	`/listings/{id}/close`	İlanı yayından kaldırır; açık teklifler kapanır.
GET	`/listings/{id}/offers`	İlana gelen teklifler.

Pazar yeri

GET	`/market/listings`	Yayındaki ilanlarda arama. Filtre: kind, from, to, vehicle, mode, date, sort, limit.
GET	`/market/listings/{id}`	Yayındaki tek ilan. Başka firmaya aitse “company.trust” güven özetini içerir.
POST	`/market/listings/{id}/offers`	Teklif verir: price, currency, vat (excl/incl), payment_term (prepaid, net15, net30, net45, net60), valid_hours (6, 24, 48, 72, 168), note.

Teklifler

GET	`/offers`	direction=incoming\|outgoing, status=open\|accepted\|rejected\|withdrawn\|closed.
GET	`/offers/{id}`	Tek teklif (T-…). Tüm teklif yanıtlarında karşı firmanın güven özeti “trust” alanında gelir (seviye: trusted\|new\|caution, dayanak satırları, sayılar); ödeme veya taşıma garantisi değildir.
POST	`/offers/{id}/accept`	Teklifi kabul eder, anlaşma oluşturur. Gövde: {"confirm": true} zorunlu.
POST	`/offers/{id}/reject`	reason: price_too_high, date_unsuitable, vehicle_unsuitable, other_solution, other; note.
POST	`/offers/{id}/withdraw`	Kendi teklifinizi geri çeker.

Anlaşmalar ve konum

GET	`/deals`	Anlaşmalar. Filtre: status (active, completed, cancelled, dispute).
GET	`/deals/{id}`	Anlaşma, olay geçmişi, son konum ve ödeme güvencesi durumu.
POST	`/deals/{id}/stage`	{"stage": 1–4}. 1–3 taşıyıcı, 4 (tamamlanma teyidi) yük sahibi.
GET	`/deals/{id}/positions`	Konum izi.
POST	`/deals/{id}/positions`	Taşıyıcı sefer konumu gönderir: lat, lng, speed_kmh, heading, recorded_at ya da {"positions": […]} (en fazla 500).

Telematik ve kiralama

GET	`/telematics/vehicles`	Bağlı araçlar ve son konumları.
POST	`/telematics/positions`	“API ile itme” bağlantısındaki araçlar için toplu konum: {"positions":[{"vehicle","lat","lng","speed_kmh","heading","recorded_at"}]}.
GET	`/rentals`	Kiralama talepleri. direction=incoming\|outgoing.
GET	`/webhooks`	Tanımlı webhook’lar.

Webhook’lar

Entegrasyonlar sayfasından bir https adresi ve olaylar seçin. Her olay JSON olarak POST edilir; 10 saniye içinde 2xx dönmezseniz 6 kez, artan aralıklarla yeniden denenir. Aynı olay birden fazla gelebilir; id alanıyla tekilleştirin.

POST /logistica/webhook
X-Logistica-Event: deal.stage_changed
X-Logistica-Signature: t=1790260000,v1=5f1c…

{"id":"evt_…","event":"deal.stage_changed","created_at":"2026-09-24T10:15:00+00:00",
 "data":{"deal":{"id":"A-3110","stage":2,"stage_label":"Taşımada", …}}}

İmzayı doğrulayın: hex(HMAC_SHA256(imza_anahtarı, t + "." + ham_gövde)) == v1 ve t 5 dakikadan eski olmasın.

$sig = $_SERVER['HTTP_X_LOGISTICA_SIGNATURE'];
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $sig, $m);
$ok = abs(time() - (int)$m[1]) < 300
   && hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);

`offer.created`	Yeni teklif geldi
`offer.accepted`	Teklifiniz kabul edildi
`offer.rejected`	Teklifiniz reddedildi
`offer.withdrawn`	Teklif geri çekildi
`deal.created`	Anlaşma oluştu
`deal.stage_changed`	Taşıma durumu değişti
`deal.completed`	Anlaşma tamamlandı
`deal.cancelled`	Anlaşma iptal edildi
`deal.disputed`	İtiraz açıldı
`message.created`	Yeni mesaj
`listing.published`	İlan yayımlandı
`listing.closed`	İlan kapandı
`rental.requested`	Kiralama talebi
`rental.accepted`	Kiralama onaylandı
`rental.declined`	Kiralama reddedildi
`rental.cancelled`	Kiralama iptal/geri çekildi
`tender.awarded`	İhale kazanıldı
`escrow.funded`	Güvenceli ödeme yatırıldı
`escrow.released`	Güvenceli ödeme serbest bırakıldı
`escrow.refunded`	Güvenceli ödeme iade edildi

Örnek akış: TMS’ten yük ilanı

curl -X POST https://alfaloji.forum/api/v1/listings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "kind": "cargo", "title": "İstanbul → Münih tekstil",
  "origin": {"city": "İstanbul", "country": "Türkiye"},
  "destination": {"city": "Münih", "country": "Almanya"},
  "transport_mode": "FTL", "vehicle_type": "tent", "weight_kg": 18000,
  "available_from": "2026-10-01T08:00:00+03:00", "available_until": "2026-10-03T18:00:00+03:00",
  "timezone": "Europe/Istanbul", "price_type": "offer", "currency": "EUR", "publish": true }'

Teklifler offer.created webhook’uyla gelir. Uygun teklifi POST /offers/T-…/accept ile kabul edin; taşıyıcı yükleme ve teslimi bildirdikçe deal.stage_changed olayları, araç bağlandıysa GET /deals/A-… içinde son konum gelir.

Araç tipleri: tent (Tenteli), refrigerated (Frigorifik), box (Kapalı kasa), flatbed (Açık kasa), mega (Mega), container (Konteyner taşıyıcı), lowbed (Lowbed), tanker (Tanker).