Kurumsal · API

Kargo Skoru API belgesi

Gönderiyi çıkarmadan önce alıcının teslimat güven skorunu kendi sisteminden sorgula. Açık telefon numarası yanıtta dönmez; bildiren firmaların adı gizlidir.

Bearer anahtar
Tek ve toplu sorgu
Kişisel veri minimizasyonu

Kimlik doğrulama

Anahtarı uygulamada İşletmem › API erişimi bölümünden oluştur (Başlangıç, Pro, İşletme ve Kurumsal planlar; sahip ya da yönetici). Anahtar yalnız oluşturulurken bir kez gösterilir.
Her istekte Authorization: Bearer ksk_… başlığını gönder. İstersen anahtarı IP adreslerine kısıtlayabilirsin.
Etkin anahtar sayısı plana göre: Başlangıç 1, Pro 3, İşletme 5, Kurumsal 10 . İptal edilen anahtarla gelen istekler hemen reddedilir.

Temel adres: https://kargoskoru.com/api/b2b/v1
Biçim: JSON (Content-Type: application/json)
Hız sınırı: Anahtar başına dakikada Başlangıç 100, Pro 200, İşletme 300, Kurumsal 600 kayıt (toplu sorguda her kayıt sayılır)

POST /lookup — tek sorgu

curl -X POST https://kargoskoru.com/api/b2b/v1/lookup \
  -H "Authorization: Bearer ksk_…" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0532 123 45 67"}'

Yanıt:

{
  "ok": true,
  "data": {
    "found": true, "score": 34, "tier": "high", "tier_label": "Yüksek risk",
    "verdict": "Kapıda ödeme yerine ön ödeme iste.",
    "advice": ["…"], "safe_badge": false, "match": "phone",
    "own_decision": null,
    "stats": {"orders": 6, "bad": 3, "ok": 3, "firms": 2, "last": "2026-11-02"},
    "charged": "plan"
  }
}

POST /batch — toplu sorgu (en çok 100)

curl -X POST https://kargoskoru.com/api/b2b/v1/batch -H "Authorization: Bearer ksk_…" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"ref": "SIP-1001", "phone": "0532 123 45 67"}, {"ref": "SIP-1002", "phone": "0555 987 65 43"}]}'

Her kalem ref ile döner: {"ref", "ok": true, …tek sorgu alanları} ya da {"ref", "ok": false, "error": "PHONE_INVALID"}. meta.quota kalan hakkı gösterir.

Hata kodları

401 API_KEY_INVALID: Anahtar yok, yanlış ya da iptal edilmiş.
403 API_IP_FORBIDDEN: İstek, anahtarın izin verdiği IP'lerden gelmiyor.
402 PLAN_FEATURE_LOCKED: Firmanın planında API erişimi yok.
402 LOOKUP_QUOTA_EXCEEDED: Sorgu hakkı bitti.
422 PHONE_INVALID · VALIDATION: Telefon ya da gövde geçersiz.
429 RATE_LIMITED: Dakikalık sınır aşıldı; Retry-After başlığına uy.