Ekspertiz.app — B2B Partner API

Türkiye'nin oto ekspertiz ERP platformu ekspertiz.app'in B2B entegrasyon API'si.

Bu API, yetkili iş ortaklarımıza (Trameks vb.) sistemimizde oluşturulan ekspertiz raporlarına programatik erişim sağlar. Multi-tenant izolasyon, HMAC-SHA256 imzalı request'ler, replay koruması ve KVKK uyumlu PII anonimizasyonu sunar.

İçindekiler

Hızlı başlangıç — aşağıda
01 · Kimlik doğrulama (HMAC imzalama)
02 · İmza örnekleri (curl / Node.js / Python / PHP)
03 · Rate limit
04 · Sayfalama (cursor pagination)
05 · PII maskeleme kuralları
06 · Hata kodları
07 · Sandbox vs Production
08 · API key rotation
09 · Test hattı cihaz entegrasyonu (test hattı üreticileri)
Endpoint referansı (her endpoint için tam istek/yanıt örneği)
openapi.yaml — OpenAPI 3.1 spec (Scalar/Redoc ile render edilebilir)

Ortamlar

Ortam	Base URL	Anahtar prefix'i
Production	`https://api.ekspertiz.app`	`tmk_live_…`
Sandbox	`https://sandbox-api.ekspertiz.app`	`tmk_test_…`

Rapor endpoint'leri GET ve idempotent'tir. Tek yazma endpoint'i test hattı cihaz ölçümleridir: POST /test-line/measurements (external_id ile idempotent). Webhooks V1 kapsamı dışındadır.

Hızlı başlangıç (5 dakikada ilk istek)

1. Anahtarları al

Sana özel bir Key ID ve Secret üretiriz. Secret yalnız oluşturulduğu anda görüntülenir; güvenli bir yere kaydet.

Aşağıdaki örnek format gösterimi içindir, gerçek değer değildir:

KEY_ID=tmk_test_XXXXXXXXXXXXXXXXXXXXXX   # 22 char base32, "tmk_live_" veya "tmk_test_" prefix
SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # 32 char base32, asla loglamayın

2. İmzalı bir GET isteği gönder

Her isteğe 4 header eklenir:

Header	Açıklama
`X-Trameks-Key-Id`	Public Key ID
`X-Trameks-Timestamp`	UNIX saniye (UTC) — ±5 dk tolerans
`X-Trameks-Nonce`	İstek başına benzersiz (≥16 karakter)
`X-Trameks-Signature`	`sha256=<hex>` — kanonik string'in HMAC-SHA256'sı

Kanonik string

METHOD\n
PATH\n
CANONICAL_QUERY\n
TIMESTAMP\n
NONCE\n
BODY_SHA256

METHOD büyük harf (GET, POST)
PATH /api/v1/partner/... (host yok)
CANONICAL_QUERY — query param'lar alfabetik sıralı, RFC 3986 ile encode (boşsa boş string)
TIMESTAMP ve NONCE header'larla aynı
BODY_SHA256 — body byte'larının lowercase hex SHA-256'sı (boş body için e3b0c4…)

signature = "sha256=" + hex(HMAC_SHA256(secret, canonical))

3. Health check ile dene

Hazır imzalama scriptlerini indir: sign.node.mjs · sign.py · sign.php

export TMK_KEY_ID="tmk_test_..."
export TMK_SECRET="..."

node scripts/sign.node.mjs GET /api/v1/partner/health

Beklenen çıktı:

{
  "status": "ok",
  "partner": "trameks",
  "environment": "test",
  "server_time": "2026-05-17T14:30:00Z"
}

Daha fazla örnek için: guides/02-signing-examples.md.

4. İlk gerçek veriyi çek

node scripts/sign.node.mjs GET /api/v1/partner/organizations
node scripts/sign.node.mjs GET "/api/v1/partner/inspections?limit=10"

Yanıt zarfı

Başarılı yanıt:

{ "data": [...], "page": { "next_cursor": "…", "has_more": true } }

Hata yanıtı:

{
  "error": {
    "code": "invalid_signature",
    "message": "Request signature could not be verified.",
    "request_id": "req_01HM…"
  }
}

Tüm yanıtlarda X-Request-Id header'ı vardır; sorun bildirirken bu ID'yi paylaşın.

Sürüm geçmişi

v1.0.0 (2026-05) — İlk yayın: organizations, branches, inspections (list/detail/forms/photos/pdf).