İç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.

4 dk. okumaSon kontrol: 09.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

  • Planet, Stern veya Galaxie paketi. Komet paketinde API yoktur.
  • Firmanın sahibi ya da yöneticisisiniz.
  • Kesme, gönderme ve ödemeler için: firma sahibisiniz ve iki aşamalı girişi kurdunuz.

Anahtar oluşturma

  1. Ayarlar › API'yi açın.
  2. Anahtara bir ad verin, örneğin „Zapier web mağazası“, ve yalnız uygulamanızın ihtiyaç duyduğu hakları seçin.
  3. „Anahtar oluştur“u seçin ve anahtarı hemen kopyalayın. soplive 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, ürün ve teklif, sipariş, irsaliye, fatura ve alacak dekontu taslakları oluşturma ve değiştirme. Bir taslağın henüz fatura numarası yoktur.
  • Kesme: bir taslağı (fatura, teklif, sipariş, irsaliye) kesme. SoPasst zorunlu bilgileri kontrol eder, sıradaki boşluksuz numarayı verir ve belgeyi kilitler.
  • Gönderme: kesilmiş bir belgeyi müşterinin kayıtlı e-posta adresine şablonunuzla ya da kendi metninizle gönderme.
  • Ödeme kaydetme: faturalara gelen ödemeleri uygulamadaki kurallarla kaydetme.
  • Kesme, gönderme ve ödemelere firma sahibi anahtarı oluştururken doğrulama uygulamasındaki kodla bir kez izin verir. Sonrasında SoPasst her çağrıda tekrar sormaz. Storno ve Gutschrift yalnız uygulamada kesilir.

İlk istek

  1. API'nin adresi https://app.sopasst.at/api/v1'dir. Tüm uç noktaların eksiksiz açıklaması https://app.sopasst.at/api/v1/openapi.json adresindedir; Zapier, Make, n8n ve Postman onu doğrudan içe aktarabilir.
  2. Anahtarı GET /api/v1/me ile kontrol edin. Yanıt anahtarın haklarını, paketinizi ve bu ayki kullanımı gösterir.
  3. Tutarlar her zaman tam euro sentidir, tarihler YYYY-AA-GG biçimindedir.

Değişiklikleri güvenle tekrarlama

  • Her POST isteği benzersiz bir değerle, örneğin bir UUID ile Idempotency-Key başlığına ihtiyaç duyar.
  • Uygulamanız aynı isteği aynı anahtarla tekrar gönderirse, örneğin bağlantı koptuktan sonra, SoPasst kayıtlı sonucu döndürür. Böylece bir fatura asla iki kez kesilmez, bir ödeme asla iki kez kaydedilmez ve hiçbir fatura numarası harcanmaz.
  • Bir istek başarısız olursa hiçbir şey kaydedilmez: düzelttikten sonra aynı değeri tekrar kullanabilirsiniz.

Webhook kurma

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

Önemli

Beklenen sonuç

Uygulamanız yanıtları JSON biçiminde alır: oluşturulan bir taslak SoPasst'ta hemen Belgeler altında 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 › API bu ayki kullanımı ve webhook teslim kaydını gösterir.

Sık görülen sorunlar

  • Planet: ayda 5.000 istek ve API ile oluşturulan 300 belge. Stern: 50.000 ve 3.000. Galaxie: 500.000 istek ve 10.000 belge.
  • Kesme, gönderme ve ödemeler için ayrıca günlük bir sınır vardır; olağan ihtiyacın çok üzerindedir.
  • Bir kota dolduğunda API HTTP 429 ile yanıt verir ve Retry-After başlığında ne zaman devam edeceğini bildirir. Hiçbir zaman otomatik ek ücret çıkmaz.
  • Her hatanın sabit bir kodu vardır, örneğin unauthorized, insufficientscope, validationfailed veya quotaexceeded. Destekle iletişimde x-request-id başlığının değerini belirtin.

Güvenle devam edin

  1. Ayarlar › API'yi açın.
  2. Anahtarda „İptal et“i ya da webhook'ta „Kaldır“ı seçin ve hemen altında onaylayın.
  3. Erişim hemen sona erer. Gerekirse yeni bir anahtar oluşturun.