Postman ile deneyin

Koleksiyon, API’nin tüm uçlarını taşır ve her isteğe imza başlıklarını kendisi koyar. Önce iki dosyayı indirin: yousoft-api.postman_collection.json ve ortam dosyası yousoft-api.postman_environment.json.

Başlamadan önce 3 adım#

1. İki dosyayı da Postman’e aktarın (Import) ve sağ üstteki ortam seçicisinden YouSoft API ortamını seçin. Ortam seçili değilse tüm değişkenler boş gelir.
2. Ortamı açın ve api_key ile api_secret değerlerini Current value sütununa yazın. Initial value paylaşılan dışa aktarmalara girer; güvenlik anahtarı oraya yazılmaz. Değerlerin başında ve sonunda boşluk olmamalı.
3. 1. Bağlantıyı doğrulayın klasöründeki Kimlik (anahtarı doğrulayın) isteğini gönderin.

Firma ile cari kart farkı#

Firma, API anahtarının bağlı olduğu şirkettir; bayi panelinde “müşteri” olarak görünür. Cari kart ise o firmanın kendi müşteri ve tedarikçi kayıtlarıdır (/v1/contacts).

Bir anahtar tek firmaya bağlıdır ve başka firmanın verisini görmez. Yeni bir firmada hiç cari kart yoktur ve dış API kartları listelemez: önce Cari kart oluştur isteğiyle bir kart açın; yanıttaki id cari_id ortam değişkenine yazılır.

İlk istek: Kimlik#

Anahtar, secret, imza ve saat doğruysa 200 ve şuna benzer bir yanıt alırsınız. Bu istek hiçbir kaydı değiştirmez.

{
  "data": {
    "role": "API_CLIENT",
    "scope": "API",
    "firma_id": "0191e515-2e76-767e-ab5d-0500f96619e5",
    "api_client_id": "0191e520-15ed-74ac-a95c-a15b584d852b"
  }
}

401 alıyorsanız aşağıdaki kontrol listesine geçin; diğer isteklere bu istek 200 dönmeden başlamayın.

Koleksiyonda neler var#

• 1. Bağlantıyı doğrulayın: kimlik ve sözleşme indirme.
• 2. Cari kartlar: kart açma ve güncelleme, iletişim kişileri.
• 3. Ürünler ve stok: ürünler, stok hareketi, kategoriler, etiketler, ölçü birimleri.
• 4. Giden faturalar: taslak, gönderim, iptal, liste ve arama (tarih aralığı, fatura numarası, ETTN, zarf), XML ve PDF indirme.
• 5. Gelen faturalar: liste, tek belge, XML ve PDF indirme.
• 6. Makbuz, irsaliye ve e-Fatura posta kutuları: tek makbuz ve tek irsaliye okuması, GİB posta kutusu sorgusu.
• 7. Kurlar ve KDV oranları: TCMB kurları ve faaliyet koduna göre KDV oranları.
• 8. Kendi isteğiniz (şablon): koleksiyonda olmayan bir isteği buradan kurun; şablonu çoğaltıp yolu ve gövdeyi değiştirin.

Her isteğin açıklaması gerekli kapsamı, parametreleri ve yan etkisini söyler. İsteğe bağlı parametreler Params sekmesinde işaretsiz gelir; kutucuğu işaretleyerek açın. Uç listesi ve alan ayrıntıları için OpenAPI referansına bakın.

Kayıtlı örnek yanıtlar#

Her isteğin altında, istek ağacında Examples bölümü vardır: en az bir başarılı ve bir tipik hata yanıtı sözleşmeyle birebir kayıtlıdır. Örneği açınca gövdeyi, başlıkları ve hangi isteğin ürettiğini görürsünüz; isteği göndermeden yanıt biçimini öğrenmenin en kolay yolu budur. Hata örnekleri ortak {"error","message","details"} zarfını taşır.

Değişkenler kendiliğinden dolar#

cari_id, urun_id, fatura_id gibi ortam değişkenlerini elle yazmanız gerekmez. Oluşturma istekleri yeni kaydın id’sini yazar; Ölçü birimi listesi ve Gelen fatura listesi değişken boşsa ilk satırın id’sini yazar. Fatura listesi arama örnekleri için yalnız fatura_no, ettn ve zarf_id değerlerini doldurur; fatura_id’ye bilerek dokunmaz, çünkü gönderim ve iptal istekleri o değişkeni kullanır. Dış API makbuzları ve irsaliyeleri listelemez: makbuz_id ve irsaliye_id değerlerini ortama elle yazın. Boş değişkenle bir istek gönderirseniz, koleksiyon isteği göndermeden değişkeni nasıl dolduracağınızı söyleyen bir hata verir.

401 alıyorsanız kontrol listesi#

Sunucu 401’in nedenini bilerek söylemez (API anahtarı doğrulanamadı). Sırayla kontrol edin:

1. X-Api-Key herkese açık anahtar kimliğidir ve ysk_ ile başlar. Secret hiçbir başlığa yazılmaz.
2. X-Api-Signature 64 karakterlik onaltılık bir metindir ve elle yazılmaz; koleksiyon her istekte kendisi üretir.
3. Sağ üstte YouSoft API ortamı seçili mi?
4. api_key ve api_secret Current value sütununda dolu mu, başında ya da sonunda boşluk yok mu?
5. İsteği koleksiyonun içinde mi kurdunuz? Dışarıda kurulan istekler imzalanmaz.
6. Yol /v1/ ile mi başlıyor? /api/* yolları panelin uçlarıdır.
7. Bilgisayar saatiniz sunucudan 5 dakikadan fazla sapmıyor mu?

Koleksiyon yardımcı olur: 401’de Test Results sekmesinde bir ipucu çıkar ve saat sapması 5 dakikayı aşıyorsa ayrıca uyarır; ayrıntı Postman Console’dadır (View, Show Postman Console). Secret hiçbir zaman konsola yazılmaz.

Postman tuzakları#

• Secret’ı başlığa yapıştırmayın. En sık görülen hata: secret X-Api-Signature başlığına yazılır. Secret yalnız api_secret değişkeninde durur; imza, onunla hesaplanan ayrı bir değerdir.
• İmza başlığını elle eklemeyin. Koleksiyonun betiği üç X-Api-* başlığını her istekte kendisi koyar.
• Koleksiyonun dışında kurulan istek imzalanmaz. Yeni bir istek için 8. Kendi isteğiniz klasöründeki şablonu çoğaltın; yeni sekmede ya da başka bir koleksiyonda kurulan istek 401 alır.
• /api/* panelin uçlarıdır. Örneğin POST /api/firma-api-anahtarlari panel oturumuyla çalışır, API anahtarıyla çağrılmaz ve imzalanmaz. Dış API yalnız /v1/* uçlarını sunar.
• Sorgu, gönderilen hâliyle imzalanmalıdır. Postman adresi gönderirken yeniden yazarsa (boşluk, ASCII dışı karakter, +, sondaki ?) sunucu başka bir metin imzalar. Süzgeç değerlerindeki saat farkını UTC ya da %2B03:00 yazın; düz + boşluk sayılır. Köşeli parantez kodlanmaz. Console’daki YouSoft imza metni satırındaki yol ve sorgu, isteğin gerçek adresiyle aynı olmalıdır.
• Saat. Postman imzayı yerel saatinizle üretir; VPN ya da sanal makine saat kayması 5 dakikayı aşarsa tüm istekler 401 alır.
• Dinamik değişkenleri gövdeye koymayın. {{$guid}}, {{$timestamp}} her çözümlemede yeniden üretilir; imza ile gönderim farklı değer görür. Koleksiyon bunları imzalamadan reddeder.
• Yalnız raw (JSON) gövde. form-data ve urlencoded gövde imzalanmaz.
• base_url yalnız adres olur. Değer https://api.yousoft.com.tr gibi olmalı, sonunda bölü işareti ve yol bulunmamalıdır.
• Secret’ı paylaşmayın. api_secret ortamda secret türünde kalmalı; koleksiyonu ya da ortamı bir başkasına dışa aktarırken Initial value sütununa secret yazmadığınızdan emin olun. Bu dosyalarda gerçek anahtar yoktur ve yazılmamalıdır.

İmzayı yayımlanmış vektörle doğrulayın#

Beklenmedik bir 401’de önce betiğin imzayı doğru ürettiğini ayırın. api_key ve api_secret yerine İmzalama sayfasındaki yayımlanmış örnek değerleri, zaman_damgasi_sabit yerine 1767225600 yazın. 8. Kendi isteğiniz (şablon) klasöründeki şablonu çoğaltın, adresini {{base_url}}/v1/invoices?filter[created_at][gte]=2026-01-01T00:00:00Z&page_size=25&sort=-created_at yapın ve isteği gönderin. İstek 401 alır (örnek anahtar hiçbir ortamda geçerli değildir), ama Console’daki YouSoft imza: satırı şu değeri taşımalıdır:

baba0dbaaaf328b3139589b11a897791b0835b5941d6cb5ab1bf2888f7f7dc81

Tutmuyorsa sorun betikte değil ortamdadır. Tuttuğunda zaman_damgasi_sabit alanını boşaltın: dolu kalırsa her istek 5 dakikadan eski bir damgayla gider ve 401 alır.