Ortak kurallar

Biçimler

Alan adları snake_case olan JSON; kimlikler UUID; zamanlar UTC'de ISO 8601 (2026-10-05T12:00:00Z), tarihler 2026-10-05. Sabit bir listeden gelen değerler {"code": "in_progress", "name": "In Progress"} biçimindedir: kod hiç değişmez, ad Accept-Language'e uyar (tr Türkçe, diğerleri İngilizce).

Sayfalar

Listeler {"data": [...], "next_cursor": "…"} döner. Sonraki sayfayı cursor=<next_cursor> ile isteyin; son sayfada next_cursor: null olur. limit 1–200 (varsayılan 50). Sayfalarken diğer parametreleri değiştirmeyin.

Python

def every(path, token, **params):
    """bir listenin bütün kayıtları, sayfa sayfa"""
    cursor = None
    while True:
        query = {**params, "limit": 200, **({"cursor": cursor} if cursor else {})}
        page = requests.get(f"{API}{path}", params=query, timeout=30,
                            headers={"Authorization": f"Bearer {token}"}).json()
        yield from page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            return

Node.js

async function* every(path, token, params = {}) {
  let cursor = null;
  do {
    const query = new URLSearchParams({...params, limit: '200', ...(cursor ? {cursor} : {})});
    const page = await (await fetch(`${API}${path}?${query}`, {headers: {authorization: `Bearer ${token}`}})).json();
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

Hatalar

Hatalar {"error": {"code": "…", "message": "…"}} döner (invalid_body'de alanları sayan details da vardır).

Durum	Kod	Anlamı
400	invalid_parameter	Bir sorgu parametresi uymuyor (zaman, kimlik, limit, imleç).
401	invalid_token	Token yok, bilinmiyor, süresi dolmuş ya da geri alınmış — yeni token alın.
403	insufficient_scope	Token'da bu uç noktanın istediği kapsam yok.
403	forbidden	Entegrasyonun yetkileri buna (bu kayıtta, şu an) izin vermiyor.
403	access_denied	Entegrasyon şu an kullanılamıyor (kapalı, paket, organizasyon).
403	read_only	Organizasyon salt okunur (ödenmemiş paket): yalnız iş emri cevaplama sürer.
403	plan_limit	Paket buna izin vermiyor (ör. iş emri oluşturma).
404	not_found	Böyle bir kayıt yok ya da entegrasyon okuyamıyor.
409	external_id_taken	Organizasyonun başka bir kaydında bu external_id var.
409	request_in_progress	Bu Idempotency-Key ile ilk istek hâlâ sürüyor.
422	invalid_body	Gövde uymuyor (details alanları sayar).
422	rule_violation	kommuns'un bir kuralı reddetti (ör. zorunlu soru cevapsız) — mesaj hangisi olduğunu söyler.
422	idempotency_key_reused	Idempotency-Key başka bir istek için kullanılmış.
429	rate_limited	Dakikalık sınır aşıldı; Retry-After saniye bekleyin.

Tekrar güvenliği

POST, PATCH ve DELETE bir Idempotency-Key başlığı alır (1–200 karakter; ör. bir UUID ya da kendi kaydınızın numarası). 24 saat içinde aynı anahtar ve aynı istek, ilk yanıtı Idempotent-Replayed: true ile yeniden döner ve yeni bir şey oluşturmaz — zaman aşımından sonra yeniden denemek güvenlidir.

Kendi numaralarınız: external_id

Envanter düğümleri, iş emirleri ve geri bildirimler sisteminizin kendi numarasını taşıyabilir (en çok 128 karakter, organizasyon içinde tekil). Envanterin numarası kommuns'ta düğümün Genel sekmesinde ("Dış sistem numarası") girilir; iş emirleri ve geri bildirimler numaralarını siz oluştururken alır. Bir kaydı ?external_id= ile bulun.