Logistica REST API
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])
offer.createdYeni teklif geldi offer.acceptedTeklifiniz kabul edildi offer.rejectedTeklifiniz reddedildi offer.withdrawnTeklif geri çekildi deal.createdAnlaşma oluştu deal.stage_changedTaşıma durumu değişti deal.completedAnlaşma tamamlandı deal.cancelledAnlaşma iptal edildi deal.disputedİtiraz açıldı message.createdYeni mesaj listing.publishedİlan yayımlandı listing.closedİlan kapandı rental.requestedKiralama talebi rental.acceptedKiralama onaylandı rental.declinedKiralama reddedildi rental.cancelledKiralama iptal/geri çekildi tender.awardedİhale kazanıldı escrow.fundedGüvenceli ödeme yatırıldı escrow.releasedGüvenceli ödeme serbest bırakıldı escrow.refundedGü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).