Ana içeriğe geç
YouSoftGeliştirici Portalı
Dokümanlar

Hızlı başlangıç

Bu sayfa, API anahtarını aldıktan sonra ilk isteği göndermenin en kısa yoludur. Her adım kısa anlatılır; ayrıntı için ilgili sayfaya bağlanır. Kendi sunucusundan API çağıracak geliştiriciye yöneliktir.

1. Anahtarı alın

API anahtarı firma başına üretilir. Müşteri panelinde Ayarlar → Web Servis Tanımları ekranını açın, Yazılım Adı listesinden yazılımınızı seçin (yoksa Diğer) ve Web Servis Tanımı Ekle düğmesine basın. Üretimde iki değer verilir:

  • X-Api-Key: isteğin kimliği. Gizli değildir.
  • Güvenlik anahtarı (secret): imzayı üretir ve hiçbir isteğe konmaz. Ekranda yalnız bir kez gösterilir; hemen gizli deponuza kopyalayın.

Anahtarı firma sahibi, bayi (iş ortağı) paneli ya da YouSoft ekibi açabilir. Kimin nereden açtığı, kapsamlar ve yenileme için API anahtarı yönetimi sayfasına bakın.

2. Üç başlığı hazırlayın

Her istek şu üç başlıkla gider:

X-Api-KeyAnahtarın kendisi.
X-Api-TimestampUnix saniyesi (tam sayı). Sunucu saatinden ±5 dakikadan fazla saparsa istek 401 alır.
X-Api-SignatureKüçük harf hex HMAC-SHA256; üretimi bir sonraki adımda.

3. İsteği imzalayın

X-Api-Signature, aşağıdaki dört alanın güvenlik anahtarıyla alınmış HMAC-SHA256 değeridir. Alanlar tek bir LF (\n) ile ayrılır:

<timestamp>\n<METOD>\n<yol+sorgu>\n<hex(sha256(gövde))>

Gövdesiz istekte (GET) dördüncü alan boş dizenin SHA-256 değeridir. Sorgu dizesi telden gittiği gibi imzalanır. Kodunuzun doğru olduğunu yayımlanmış test vektörüyle doğrulayın: dört dilde örnek kod ve imza hatalarının sık nedenleri İmzalama sayfasındadır.

4. İlk isteği gönderin

GET /v1/me anahtarın kimliğini döndürür ve hiçbir kapsam istemez; kurulumu doğrulamanın en ucuz yolu budur. Taban adres https://api.yousoft.com.tr; bütün yollar (/v1/…) bunun üzerine eklenir. Önce iki değeri ortam değişkeni yapın, sonra isteği gönderin:

bash
export API_KEY='X-Api-Key değeriniz'
export API_SECRET='güvenlik anahtarınız (secret)'
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.yousoft.com.tr$YOL" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Timestamp: $TS" \
  -H "X-Api-Signature: $IMZA"

Postman ile denemek için Postman sayfasına bakın.

Beklenen yanıt

200 ve anahtarı tanımlayan bir gövde dönmelidir:

JSON, 200
{
  "data": {
    "api_client_id": "0192e8a1-7c3f-7d2e-b5a4-3f6c9d8e1a20",
    "firma_id": "0192e8a0-11b2-7c4d-9e3f-5a6b7c8d9e01",
    "scope": "API",
    "role": "API_CLIENT"
  }
}

Yanıt zarfı her uçta aynıdır: tekil kaynak { "data": { … } }, liste { "data": [ … ], "meta": { "next_cursor": … } }. Tek istisna: fatura gönderimi 202 ile yalnız { "data": { "invoice_id": … } } döner.

401 aldıysanız

Başlıklardan biri eksik ya da biçimsizse yanıt details.hint ile neyin bozuk olduğunu söyler. Biçim doğruysa 401 nedenini söylemez: yanlış anahtar, kapatılmış anahtar, yanlış imza ve saat sapması aynı yanıtı alır. En sık neden kanonik dizedeki küçük bir sapmadır; önce test vektörünü çalıştırın, ardından kontrol listesini izleyin.

Sıradaki adımlar