Temeller

İstek ve yanıt

Zarf, hata şekli, trace_id ve iki farklı yanıt sözleşmesi — hangi uç hangisini kullanır.

İki sözleşme, iki bağlam

Blesyum'da iki yanıt şekli vardır ve karıştırılmaları en sık yapılan hatadır.

Çekirdek ve modül panel uçları

Zarf: {data, trace_id}

json
{ "data": { "id": "0193…", "name": "Acme Ltd." }, "trace_id": "01JC7…" }

Hata:

json
{ "error": {
    "code": "CORE-REQ-0002",
    "message": "Doğrulama başarısız.",
    "hint": "validation",
    "trace_id": "01JC7…",
    "details": [{ "field": "email", "message": "Geçerli bir e-posta değil." }]
} }

Public API uçları (/public/v1/...)

Bu uçlar Intercom uyumlu bir şekil kullanır — mevcut istemci kütüphaneleriyle uyumlu olsun diye:

json
{ "type": "list",
  "data": [ { "type": "contact", "id": "0193…" } ],
  "pages": { "type": "pages", "per_page": 50, "next": { "starting_after": "eyJ…" } } }

Hata:

json
{ "type": "error.list",
  "errors": [{ "code": "parameter_invalid", "message": "per_page en fazla 150 olabilir." }] }

Aynı modülün hem panel uçları hem public API uçları vardır ve şekilleri farklıdır. Yolun içinde public geçiyorsa ikinci şekli beklersin.

trace_id — destek istediğinde bunu ver

Her yanıt bir trace_id taşır. Bir hatayı bize bildirirken bu değeri gönderirsen isteğin tam yolunu loglarda bulabiliriz. Kendi loglarında da sakla: "bazen 500 alıyorum" ile "şu trace_id'de 500 aldım" arasındaki fark, saatlerce süren bir araştırmayla beş dakikalık bir bakış arasındaki farktır.

Hata kodu bir SÖZLEŞMEDİR

code alanı kararlıdır ve DOMAIN-ALAN-NNNN biçimindedir:

text
CORE-AUTH-0001    çekirdek · kimlik · 401
CORE-REQ-0002     çekirdek · istek · 422 (doğrulama)
CRM-LIC-0001      CRM · lisans · 403
ERP-FATURA-0007   ERP · fatura · modüle özel

Dallanmayı codea yap, messagea değil. message kullanıcının diline göre çevrilir ve iyileştirildikçe değişir; code değişmez.

Tam liste: Hata kodları.

İçerik türü ve karakter kodlaması

  • İstek gövdesi: application/json, UTF-8
  • Yanıt: application/json; charset=utf-8
  • Tarihler: RFC 3339, UTC (2026-08-21T09:14:00Z)
  • Para: tam sayı kuruş ve ayrı bir currency alanı — kayan noktalı sayı kullanmıyoruz (0,1 + 0,2 sorunundan kaçınmak için)

Gövde boyutu

JSON uçlarının varsayılan tavanı 1 MiB'tır. Dosya yükleyen uçların kendi (daha geniş) tavanları vardır; aşarsan 413 ve CORE-REQ-0006 alırsın.

Zaman

Sunucu saati kanoniktir. İstemcinden gelen bir tarihe bakarak süre/erişim kararı veren hiçbir uç yoktur; deneme, lisans ve oturum kararlarının tamamı sunucuda verilir. Kendi arayüzünde "kalan gün" gösteriyorsan referansı GET /api/v1/time ucundan al — cihaz saati bir görüştür, kanıt değil.

Bu sayfa işine yaradı mı?
Hâlâ takıldın mı? Destek al