Ana içeriğe geç

Sipariş Listesi API (get-reports)

get-reports endpoint'i, verilen tarih aralığında oluşturulmuş tüm SMS siparişlerinin agrega özet listesini döner. Her sipariş için sayaçlar (toplam / teslim edilen / edilemeyen / bekleyen), zaman damgaları ve sender bilgisi tek yanıtta gelir; mesaj-bazında alıcı kırılımı bu yanıtta yoktur — onun için sipariş başına get-report kullanılır.

Bu endpoint, panelin Raporlar → Toplu SMS Geçmişi ekranının arkasındaki listeleme sorgusudur. Tipik kullanım: dashboard, dönemsel analitik, "son hafta gönderimlerini listele" gibi sorular.

Önemli ön koşul: Panel'de API erişimi

Bu endpoint'i çağırmadan önce panelinizde API kullanımına izin ver seçeneğinin aktif olması gerekir.

Ayar yeri: panel.iletimerkezi.com → Ayarlar → Güvenlik → Erişim İzinleri

Aktif değilse istek 401 — Üyelik bilgileri hatalı ile döner. Detay: authentication.md

Endpoint

| Alan | Değer | |---|---| | Method | POST | | URL | https://api.iletimerkezi.com/v1/get-reports/json | | Content-Type | application/json | | Auth | API Key + Hash (request.authentication) |

Request

Şema

request
├─ authentication
│  ├─ key (string, zorunlu)
│  └─ hash (string, zorunlu)
└─ filter
   ├─ start (string, zorunlu)  — başlangıç tarihi, format Y-m-d (ör. 2026-04-01)
   ├─ end (string, zorunlu)    — bitiş tarihi, format Y-m-d
   └─ page (integer, opsiyonel) — varsayılan 1

Tarih aralığı limiti: start ve end arasındaki fark maksimum 10 gün. Daha geniş aralık için ardışık çağrı yapılmalı (2026-04-01..2026-04-10, sonra 2026-04-11..2026-04-20 gibi). Limit aşılırsa istek 458 — Tarih aralığı hatalı ile döner.

Tam örnek

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "filter": {
      "start": "2026-04-22",
      "end": "2026-04-29",
      "page": 1
    }
  }
}

Response

Başarılı (200)

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "count": 2,
    "orders": [
      {
        "id": 312988299,
        "status": 114,
        "total": 1,
        "delivered": 1,
        "undelivered": 0,
        "waiting": 0,
        "submitAt": "2026-04-29 21:49:42",
        "sendAt": "2026-04-29 21:49:42",
        "sender": "eMarka Test"
      },
      {
        "id": 313003818,
        "status": 114,
        "total": 1,
        "delivered": 1,
        "undelivered": 0,
        "waiting": 0,
        "submitAt": "2026-04-30 06:57:45",
        "sendAt": "2026-04-30 06:57:45",
        "sender": "eMarka Test"
      }
    ]
  }
}

Alanlar:

  • response.count (integer): Yanıttaki sipariş sayısı (mevcut sayfadaki). Tarih aralığındaki toplam sipariş sayısı değildir; sayfalama için page arttırılarak ardışık çağrı yapılır.
  • response.orders[] (array): Sipariş listesi. Her eleman:
    • id (integer): Sipariş ID. Detay raporu için get-report'a verilir.
    • status (integer): Sipariş genel durumu (113 / 114 / 115).
    • total (integer): Siparişteki toplam mesaj sayısı.
    • delivered (integer): Teslim edilmiş mesaj sayısı.
    • undelivered (integer): Teslim edilemeyen mesaj sayısı.
    • waiting (integer): Hâlâ kuyrukta bekleyen mesaj sayısı.
    • submitAt (string): API'nin isteği aldığı an, format YYYY-MM-DD HH:MM:SS.
    • sendAt (string): Operatöre verildiği an. İleri tarihli sipariş değilse submitAt ile aynıdır.
    • sender (string): Sipariş için kullanılan sender ID.

Mesaj-bazında alıcı kırılımı (message[] array, number, status per-recipient) bu endpoint'te yoktur. Tek sipariş için detay rapor gerekiyorsa get-report kullanın; çok-siparişli dashboard için bu endpoint daha verimlidir (tek istek = N sipariş özeti).

Boş liste (200)

Tarih aralığında sipariş yoksa veya sayfalamada son sayfayı geçtiyseniz:

{
  "response": {
    "status": { "code": 200, "message": "İşlem başarılı" },
    "count": 0,
    "orders": []
  }
}

count: 0 ve boş orders dizisi sayfalama döngüsü için doğal terminator'dır.

Sipariş durum kodları (order.status)

| Kod | Anlam | |---|---| | 113 | Sipariş gönderimi devam ediyor | | 114 | Sipariş gönderimi tamamlandı | | 115 | Sipariş gönderilemedi |

Hata yanıtları

401 — Üyelik bilgileri hatalı

Detay: authentication.md.

458 — Tarih aralığı hatalı

İki olası neden:

  1. start veya end formatı Y-m-d (örn. 2026-04-22) değil.
  2. start ile end arasındaki fark 10 günden büyük.

Geniş bir dönemi kapsamak için tarihleri 10 günlük dilimlere bölün ve döngüyle çağırın.

Diğer hata kodları

400, 404 için tablo: error-codes.md.

Kod örnekleri

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/get-reports/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "filter": { "start": "2026-04-22", "end": "2026-04-29", "page": 1 }
    }
  }'

Common Pitfalls

  • get-reports ≠ get-report. Endpoint isimleri tek harfle ayrılır ama davranış farklıdır. get-report (tekil) tek sipariş için mesaj-bazında detay verir; get-reports (çoğul) tarih aralığında N sipariş için agrega özet döner. Mesaj kırılımı sadece tekil endpoint'te.
  • 10 günlük tavan unutulmaz. Aylık veya kampanya dönemi raporu için döngü gerekir. 30 günlük tek istek 458 döner. İstemci tarafında dönemi 10'arlı dilimlere bölüp her dilim için ardışık istek atın.
  • Tarih formatı katı. Y-m-d (2026-04-22) zorunlu. 22/04/2026, 22-04-2026, 2026/04/22 kabul edilmez. JavaScript tarafında date.toISOString().slice(0, 10) güvenli.
  • count "toplam" değildir. response.count mevcut sayfadaki sipariş adedidir. Tarih aralığındaki toplam sipariş sayısını öğrenmek için count küçülene kadar page'i arttırın (boş orders veya count: 0 döndüğünde sayfalama biter).
  • waiting > 0 ise rapor henüz son değil. Anlık sorgularda yeni siparişlerin bir kısmı operatör kuyruğunda olabilir. Final rakamlar için ya kısa süre sonra tekrar sorgulayın ya da webhook ile delta güncelleyin.
  • status: 114 "her şey teslim" demek değil. Sadece "gönderim akışı bitti". Gerçek başarı için delivered ve undelivered sayaçlarına bakın. (Aynı semantic get-report'taki gibi.)
  • Numara görünmez, sender görünür. Bu endpoint alıcı numarayı listelemez (privacy + payload boyutu); sender ve sayaçlar yeterlidir. Alıcı bazlı denetim için tek tek get-report çağırın.

Related

Son güncelleme: 2026-04-30 · English version