Kurallar

Para ve hacim dizedir

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

float olarak değil, decimal olarak ayrıştırın. Para birimi USD. Gigabayt = 10^9 bayt.

Zaman

Açık ofsetli ISO-8601, her zaman UTC: 2026-08-28T14:03:11+00:00.

Genişleyebilen numaralandırmalar

Sipariş durumu, işlem türü, olay türü, paket durumu, kind, family değerleri v1 içinde önceden haber verilmeden genişleyebilir - tanımadığınız bir değere dayanıklı olun. Filtrelerde tanınmayan değer “filtresiz” olarak okunur.

Sayfalama

Parametre	Anlamı
offset	kaç satırın atlanacağı; varsayılan 0
limit	1..200, varsayılan 50 (GET /api/v1/packages için 200)

İkisi de reddedilmez, sınırlara kırpılır ve gövdede kırpılmış halleriyle döner. Yanıt total taşır.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

Yazılmaya devam eden listelerde offset bir konumu gösterir: tam dışa aktarmada id ile tekilleştirin. Sıralama sabittir - en yeniler üstte.

Olay günlüğü farklı okunur: ?after=<id>, yanıt next_after taşır.

Idempotency

Para düşen işlemler şu başlığı gerektirir: POST /api/v1/packages (satın alma), POST /api/v1/packages/{id}/topup (trafik hacmi ekleme) ve POST /api/v1/packages/{id}/prolong (adres uzatma).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

En fazla 255 karakterlik bir dize; baştaki ve sondaki boşluklar kırpılır.

Aynı anahtar ve aynı gövdeyle tekrar, aynı yanıtı döndürür. Anahtarı istekten önce üretin ve tekrarlarda, zaman aşımından sonraki tekrar dahil, yeniden kullanın.

Anahtar 24 saat hatırlanır: bir gün sonra aynı anahtar yeni bir işlem başlatır.

Retler:

• 422 - idempotency_key_required (başlık yok), idempotency_key_invalid (boş veya 255’ten uzun), idempotency_key_reused (aynı anahtar farklı gövdeyle)
• 409 - idempotency_in_progress (önceki istek hâlâ yürütülüyor - biraz sonra aynı anahtarla tekrarlayın)
• 500 - operation_indeterminate (sonucu belirsiz bir işlemin anahtarıyla tekrar - Retler sayfasına bakın)

Geo kataloğu önbelleği

Geo kataloğu seviyeleri ETag döndürür - katalog sürümünün opak bir özeti. Bunu If-None-Match içinde gönderin, gövdesiz 304 alırsınız. Aynı sürümün okunabilir hali gövdede version alanındadır.

Sürümleme

v1 içinde önceden haber verilmeden yayınlanır: yanıtta yeni alan, yeni isteğe bağlı parametre, genişleyebilen numaralandırmada yeni değer, yeni uç nokta, mevcut bir durumda yeni hata kodu.

Yalnızca yeni sürümle: alanın kaldırılması veya yeniden adlandırılması, türün daraltılması, istekte yeni zorunlu alan, tanımlı bir durum için durum kodunun veya hata kodunun değişmesi, varsayılan değerin değişmesi.

Kullanımdan kaldırma: Deprecation ve Sunset başlıkları, kapatmadan en az 6 ay önce.