İçeriğe geç
Yardım merkezine dön

Otomasyon

API ve webhook'lar

Yazılımınızı, Zapier, Make veya n8n'i bir API anahtarıyla bağlayın, hakları seçin, değişiklikleri güvenle tekrarlayın ve webhook kurun.

5 dk. okumaSon kontrol: 13.10.2026
SoPasst'ta aç

Genel bakış

SoPasst API'si ile kendi yazılımınızı, web mağazanızı ya da Zapier, Make ve n8n gibi araçları SoPasst'taki firmanıza bağlarsınız. Webhook'lar bir belge kesildiğinde veya gönderildiğinde ya da bir ödeme kaydedildiğinde uygulamanıza hemen haber verir.

Gereksinimler

  • Aktif aboneliği olan Planet, Stern veya Galaxie paketi (deneme süresi de geçerlidir). Komet paketinde API yoktur.
  • Firmanın sahibi ya da yöneticisisiniz. Diğer roller Ayarlar › Yapay zekâ asistanları ve API › API sayfasını görmez.
  • Kesme, gönderme ve ödemeler için: firma sahibisiniz ve Ayarlar › Güvenlik altında iki adımlı girişi kurdunuz.

Anahtar oluşturma

Kullanım, anahtarlar, haklar ve webhook'larla Ayarlar › Yapay zekâ asistanları ve API › API
Firmanızın kullanımı, anahtarları ve webhook'ları tek sayfada.
  1. Ayarlar › Yapay zekâ asistanları ve API › API'yi açın.
  2. „Yeni anahtar“ altında bir ad girin, örneğin „Zapier web mağazası“, ve yalnız uygulamanızın ihtiyaç duyduğu hakları işaretleyin.
  3. „Anahtar oluştur“u, ardından „Kopyala“yı seçin. Anahtar sop_live_ ile başlar ve yalnız bu kez gösterilir.
  4. Anahtarı uygulamanıza bearer token olarak girin: Authorization başlığı, değeri „Bearer “ ve ardından anahtar.

Önemli

Bir anahtarın hakları

  • Okuma: PDF'leriyle birlikte belgeleri, müşterileri, ürünleri ve ödemeleri getirme.
  • Taslak yazma: müşteri ve ürün oluşturma ve değiştirme; teklif, sipariş onayı, irsaliye, fatura ve Gutschrift taslakları oluşturma ve değiştirme. Bir taslağın henüz fatura numarası yoktur.
  • Kesme: bir taslağı (fatura, teklif, sipariş onayı, irsaliye) kesme. SoPasst zorunlu bilgileri kontrol eder, sıradaki boşluksuz numarayı verir, PDF'i saklar ve belgeyi kilitler.
  • Gönderme: kesilmiş bir belgeyi müşterinin kayıtlı bir e-posta adresine şablonunuzla ya da kendi metninizle gönderme.
  • Ödeme kaydetme: faturalara gelen ödemeleri uygulamadaki ödeme formuyla aynı kurallarla kaydetme.
  • Kesme, gönderme ve ödemelere yalnız firma sahibi, anahtarı oluştururken bir kez, doğrulama uygulamasındaki kodla izin verir. Sonrasında SoPasst her çağrıda tekrar sormaz. Gutschrift, Storno ve Mahnung yalnız uygulamada kesilir.

İlk istek

  1. API adresi https://app.sopasst.at/api/v1'dir. Tüm uç noktaların açıklaması https://app.sopasst.at/api/v1/openapi.json adresindedir; Zapier, Make, n8n ve Postman bunu doğrudan okuyabilir.
  2. Anahtarı GET /api/v1/me ile kontrol edin. Cevap anahtarın haklarını, paketinizi ve bu ayki ve bugünkü kullanımı gösterir.
  3. Tutarlar her zaman euro cinsinden tam sent, tarihler YYYY-AA-GG biçimindedir. Tüm değişiklikler JSON içeren POST istekleridir.

Değişiklikleri güvenle tekrarlama

  • Her POST isteğinde benzersiz bir değer (örneğin bir UUID) taşıyan Idempotency-Key başlığı olmalıdır. Bu başlık yoksa API idempotency_key_required ile cevap verir.
  • Uygulamanız aynı isteği aynı değerle 24 saat içinde yeniden gönderirse, örneğin bağlantı koptuktan sonra, SoPasst kaydedilmiş sonuçla ve idempotent-replayed başlığıyla cevap verir. Böylece bir fatura asla iki kez kesilmez, bir ödeme asla iki kez kaydedilmez.
  • Aynı değer farklı bir içerikle gönderilirse idempotency_key_reused ile reddedilir. Her yeni değişiklik için yeni bir değer kullanın.
  • Bir istek başarısız olursa hiçbir şey kaydedilmez ve fatura numarası harcanmaz. Düzelttikten sonra aynı değeri yeniden kullanabilirsiniz.

Webhook kurma

  1. Ayarlar › Yapay zekâ asistanları ve API › API'yi açın ve Webhook'lar altında uygulamanızın adresini girin. Yalnız 443 numaralı portta, herkese açık bir ana makine adına sahip https adreslerine izin verilir.
  2. Olayları seçin: document.issued (Storno ve Mahnung dahil), document.sent ve payment.recorded. „Webhook ekle“yi seçin.
  3. Gösterilen imza sırrını (whsec_…) kopyalayın. Yalnız bir kez gösterilir.
  4. Uygulamanızda her mesajı kontrol edin: webhook-id, webhook-timestamp ve webhook-signature başlıkları „Standard Webhooks“ standardına uyar; birçok kütüphane imzayı tek satırla doğrular.

Önemli

Beklenen sonuç

Uygulamanız JSON biçiminde cevaplar alır: oluşturulan bir taslak hemen SoPasst'ta görünür, kesilmiş bir belgenin kesin numarası ve PDF'i vardır ve her webhook adresinize geçerli bir imzayla ulaşır. Ayarlar › Yapay zekâ asistanları ve API › API bu ayki kullanımı, her anahtarın en son ne zaman kullanıldığını ve son 20 webhook'un teslim kaydını gösterir.

Sık karşılaşılan sorunlar

  • Aylık kota: Planet 5.000 istek ve API ile oluşturulan 300 belge, Stern 50.000 ve 3.000, Galaxie 500.000 ve 10.000. Hatalı olanlar dahil her istek sayılır.
  • Anahtar ve dakika başına: Planet 60, Stern 120, Galaxie 300 istek. Kesme, gönderme ve ödemeler için ayrıca günlük bir sınır vardır; GET /api/v1/me bunu gösterir.
  • Bir kotaya ulaşıldığında API HTTP 429 ile cevap verir ve Retry-After başlığında ne zaman devam edileceğini belirtir. Asla kendiliğinden ek ücret çıkmaz.
  • Her hatanın sabit bir kodu vardır, örneğin unauthorized (anahtar yok ya da iptal edilmiş), insufficient_scope (hak eksik), validation_failed (örneğin zorunlu bilgiler eksik) veya quota_exceeded. Destekle iletişimde x-request-id başlığının değerini verin; anahtarı asla paylaşmayın.

Güvenle devam edin

  1. Ayarlar › Yapay zekâ asistanları ve API › API'yi açın.
  2. Anahtarda „İptal et“i ve ardından „Anahtarı iptal et“i, webhook'ta „Kaldır“ı ve ardından „Webhook'u kaldır“ı seçin.
  3. Erişim hemen sona erer ve geri getirilemez. Gerekirse yeni bir anahtar oluşturun. İptal etme ve kaldırma abonelik kilitliyken de çalışır.