Başlangıç ve kimlik doğrulama

Anahtarı nereden alırsınız, ilk istek nasıl atılır, hangi başlıklar zorunludur.

1. Anahtarı alın

API anahtarı firma başına üretilir: müşteri panelinde Firma Bilgileri → Web Servis Tanımları ekranından firma sahibi bir anahtar açar. Anahtar üretildiğinde iki değer verilir:

X-Api-Key — gizli değildir, isteğin kimliğini söyler.
Secret — yalnız üretim anında BİR KEZ gösterilir, imzayı üretir ve hiçbir isteğe konmaz. Kaybolursa yenilenir (aşağıda).

Anahtarın kapsamları anahtarı ÜRETENİN yetkileriyle sınırlıdır. Panel ekranı bugün kapsam seçtirmez ve kapsam listesi boş bırakılan bir anahtar izin verilen tam kümeyi alır — fatura düzenleme ve gönderim dahil. Dar kapsam istiyorsanız anahtarı uçtan üretin ve kapsamlar listesini AÇIKÇA verin:

http

POST /api/firma-api-anahtarlari
{"yazilim_evi": "Örnek Yazılım", "kapsamlar": ["Kart.MusteriTedarikciIzleyebilir"]}

Kapsam taşımayan bir uç 403 forbidden döner ve eksik kapsam kodunu yanıta yazmaz — anahtarı gören birine yetki haritası çıkarmayalım diye.

2. Zorunlu başlıklar

X-Api-Key	Anahtarın kendisi.
X-Api-Timestamp	UNIX saniye. Sunucu saatinden ±5 dakikadan fazla saparsa istek 401 alır.
X-Api-Signature	Küçük harf hex HMAC-SHA256 — üretimi İmzalama sayfasında, test vektörüyle birlikte.

3. İlk istek

GET /v1/me anahtarın kimliğini döndürür ve hiçbir kapsam istemez — kurulumu doğrulamanın en ucuz yolu budur.

bash

TS=$(date +%s)
YOL='/v1/me'
OZET=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
IMZA=$(printf '%s\n%s\n%s\n%s' "$TS" GET "$YOL" "$OZET" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -hex | awk '{print $NF}')

curl -s "https://api.example.com$YOL" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Timestamp: $TS" \
  -H "X-Api-Signature: $IMZA"

Yanıt zarfı her uçta aynıdır: tekil kaynak { "data": { … } }, liste { "data": [ … ], "meta": { "next_cursor": … } }.

4. Secret yenileme

Secret yenilendiğinde eski secret 24 saat daha geçerlidir. Pencere, entegrasyonunuzu yeni değeri yerleştirene kadar ayakta tutar; penceredeki secret’ın yetkisi dar değildir, tek fark hangi sırla imzalandığıdır. Yeni değeri yerleştirdikten sonra beklemeye gerek yok.

Neden OAuth yok

v1’de OAuth 2.0 akışı yoktur: ne client_credentials, ne authorization_code. Yüzey sunucudan sunucuya çalışan bir entegrasyon içindir ve anahtar+imza aynı işi bir jeton uç noktası, yenileme döngüsü ve süre yönetimi olmadan görür. password grant’ı ise hiçbir zaman uygulanmayacak: kullanıcının panel parolasını üçüncü tarafa verdirir.

Bunun bugün maliyeti şudur: son kullanıcı adına yetkilendirme (bir kullanıcının “bu uygulamaya izin ver” demesi) yoktur — anahtarı firma sahibi üretir ve kapsamını kendisi seçer. Uygulama pazarı ve OAuth için şema tarafındaki alan (uygulama_id) açıldı; akışın kendisi bir sonraki sürümün konusudur ve geldiğinde bu sayfada duyurulur.

Tarayıcıdan çağrılmaz

API CORS başlığı göndermez ve bu bilinçli bir duruştur: imza sırrı olan bir API’nin tarayıcıda yaşayacak bir istemcisi yoktur, çünkü sır oraya indiği anda sır olmaktan çıkar. İstekleri kendi sunucunuzdan atın.