Müşterileriniz İçin CAPTCHA API Anahtarı Nasıl Oluşturulur

CapSkip'i başkaları için işletiyorsanız, müşteri ödemeyi yaptığı anda, doğrudan faturalandırma webhook'unuzdan CAPTCHA API anahtarı oluşturabilirsiniz. Remote Key Management, çalışan örnek üzerinde anahtar ekleyen, listeleyen ve silen üç POST uç noktası sunar; yeni anahtar da hemen bir sonraki çözüm isteğinde geçerli olur. Yeniden başlatma yok, elle yapılan bir adım yok ve ödemenin geçmesiyle müşterinin çözmeye başlaması arasında artık hiçbir şey durmuyor. Bu yazıda abonelik başlarken anahtar oluşturmayı, iptalde geri almayı, anahtar listenizi faturalandırma sisteminizle uyumlu tutmayı ve bu kurulumun kolayca yaptırdığı o tek ağ hatasını anlatıyoruz.

Neye ihtiyacınız var

• Sizin kontrolünüzdeki bir Windows makinesinde çalışan CapSkip. Bu makine sizin çözüm servisinizdir ve uygulamanın kurulu olması gereken tek makinedir. Müşterileriniz hiçbir şey kurmaz.
• Bir de Server modu, ki müşteriler gerçekten erişebilsin. Local modu geri döngü adresini dinler ve yalnızca o cihaza hizmet eder; Server modu ise ağ IP'nizi veya genel IP'nizi dinler, böylece başka makineler bağlanabilir. İki mod da şurada anlatılıyor: bağlantı ayarları. Adresi birine vermeden önce statik bir genel IP edinmeniz iyi olur.
• Yönetim token'ını üretmek için CapSkip penceresine bir kez uğramak. Arayüzde geçen tek adım budur ve bir daha tekrarlamazsınız.
• Bu çağrıları yapacağınız bir yer: faturalandırma webhook'u işleyiciniz, panelinizin arka ucu ya da denemeler sürerken bir terminal.

Koda geçmeden önce açıkça söylemekte fayda var, çünkü bu modeli ayakta tutan şey tam olarak budur. Dağıttığınız anahtarları siz basıyorsunuz. Bunlar satın alıp yeniden sattığınız krediler değildir ve arkalarında çözüm başına işleyen bir sayaç yoktur. CapSkip sizin donanımınızda çalışır, dolayısıyla yüz müşteri anahtarının maliyeti tek bir anahtarınkiyle aynıdır.

Adım 1: Remote Key Management özelliğini açın

Anahtar, Settings içinde API Key Validation altında, sonra Advanced, sonra da Remote Key Management yolundadır. Açın ve Generate düğmesine basın.

Token yalnızca bir kez gösterilir ve sadece tuzlanmış özet olarak saklanır, yani sonradan okunabileceği bir yer yoktur. Kaybederseniz yenisini üretirsiniz, eskisi anında geçersiz olur. Bunu iptal düğmesi olarak görün, çünkü ayrı bir iptal düğmesi yok. Onu faturalandırma sisteminizin diğer gizli bilgilerini tuttuğu yerde saklayın, uygulama kodunuzda değil.

Uç noktalar, çözüm isteklerinizi zaten yanıtlayan aynı sunucu ve aynı bağlantı noktası üzerindedir. Müşterileriniz 8080 numaralı bağlantı noktasıyla konuşuyorsa yönetim API'si de oradadır. Bu hem kolaylık hem de dikkat etmeniz gereken şeyin ta kendisidir; aşağıda buna ayrı bir bölüm ayırdık.

Özellik kapalıyken her yönetim yolu, gövdesi olmayan düz bir 404 döndürür. Bilinmeyen bir yola verilen yanıtın tamamen aynısıdır ve bu bilinçli bir tercihtir: bağlantı noktasını yoklayan biri, özelliği kapatılmış bir örnek ile bu özelliği hiç duymamış bir örnek arasındaki farkı göremez.

Adım 2: müşteri abone olduğunda anahtarı oluşturun

Üç uç nokta da POST'tur, JSON gövdesi alır ve token'ı Bearer kimlik bilgisi olarak taşıyan bir Authorization başlığı ister. Ekleme çağrısı bir ad ister. Yalnızca adı gönderin, anahtar değerini CapSkip üretsin; burada istediğiniz de budur, çünkü müşteri kendi kimlik bilgisini kendisi seçmemeli.

# No install needed. Name the key after the customer, not after the plan.
curl -X POST http://YOUR_SERVER:8080/admin/keys/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"cust_10482"}'

# Response carries the value to show the customer once:
# {"errorId":0,"key":{"name":"cust_10482","key":"..."}}

Adı kendi sisteminizde kalıcı olan bir şeyden türetin, örneğin müşteri kimliği ya da abonelik kimliği. Adlar benzersizdir ve bu kural eklemede zorunlu tutulur, dolayısıyla ad sonraki her işlem için güvenilir bir tutamak hâline gelir. Bunun yerine anahtarları pakete veya tarihe göre adlandırmak, iptal gününü acı verici yapan hatadır.

Bu benzersizlik kuralı aynı zamanda tekrar koruma mekanizmanızdır. Ödeme sağlayıcıları webhook'ları yeniden gönderir ve tekrar gelen bir abonelik olayı, aynı müşteriye sessizce ikinci bir anahtar oluşturmak yerine 409 ile ERROR_KEY_EXISTS döndürür. İşleyicinizde bu 409'u başarı sayın, tekrar sorunu ortadan kalksın.

Değer tam olarak bir kez, o yanıtın içinde döner. Onu müşteriye gösterin ya da panelinizin okuduğu yere kaydedin; çünkü anahtarları sonradan listelemek bir yönetim işlemidir ve tek bir müşterinin kimlik bilgisini kurtarmak için çalıştırmak isteyeceğiniz bir şey değildir.

Adım 3: iptal ettiklerinde anahtarı geri alın

Silme işlemi tam olarak tek bir seçici alır, ya anahtar değerini ya da adı. Anahtarları müşterilere göre adlandırdığınız için kullanılacak olan addır:

# By name, which is unambiguous because names are unique.
curl -X POST http://YOUR_SERVER:8080/admin/keys/delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"name":"cust_10482"}'

# By value works too, if that is what your records hold:
#   -d '{"key":"the-old-value"}'

Geri alma bir sonraki çözüm isteğinde geçerli olur, yani çağrı döner dönmez erişim biter. O andan itibaren o müşterinin çağrıları şu hatayla başarısız olur: ERROR_KEY_DOES_NOT_EXIST. Bu yeterince açık bir sinyaldir; entegrasyonları bunu bir kesinti olarak değil, süresi dolmuş abonelik olarak gösterebilir.

Bunu ne zaman tetikleyeceğinize bilinçli karar verin. İptal olayında silmek erişimi hemen keser, oysa müşteri genellikle dönem sonuna kadar ödemiştir. Çoğu kişinin aslında istediği, dönem sonu olayında silmektir. Başarısız ödeme ise üçüncü durumdur: geri almadan önce kısa bir ödemesiz süre tanımak, karttan yeniden çekim denemesinde kaybolan bir anahtardan çok daha az destek talebi doğurur.

Adım 4: listeyi faturalandırma sisteminizle karşılaştırın

Listeleme çağrısı boş bir nesne alır ve örneğin şu anda kabul ettiği her anahtarı döndürür.

# The audit: exactly who can solve right now.
curl -X POST http://YOUR_SERVER:8080/admin/keys/list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

{
  "errorId": 0,
  "keys": [
    { "name": "cust_10482", "key": "..." },
    { "name": "cust_10515", "key": "..." }
  ]
}

errorId değerinin 0 olması başarı demektir; çözüm uç noktaları da aynı kuralı kullanır. Bunu belirli aralıklarla çalıştırın ve adları etkin aboneliklerinizle karşılaştırın. Karşılığında abonelik olmayan bir anahtar, hâlâ bedava çözüm yapan biri demektir; anahtarı olmayan bir abonelik ise, hazırlama webhook'u düşmüş ve muhtemelen birazdan destek talebi açacak bir müşteri demektir. İkisi de siz bakana kadar sessiz kalır ve bu çağrı, gerçeğin yaşadığı tek yerdir.

Bunu bir abonelik webhook'una bağlamak

Bir araya getirildiğinde bütün entegrasyon iki işleyici ve bir tekrar kuralından ibarettir:

# pip install requests
import requests

BASE = "http://YOUR_SERVER:8080"
AUTH = {"Authorization": "Bearer YOUR_TOKEN"}

def admin(path, body):
    r = requests.post(f"{BASE}/admin/keys/{path}", json=body,
                      headers=AUTH, timeout=10)
    # 409 on add means the key already exists, which is what a
    # retried webhook looks like. Treat it as success, not failure.
    if r.status_code == 409:
        return None
    r.raise_for_status()
    return r.json()

def on_subscription_active(customer_id):
    created = admin("add", {"name": f"cust_{customer_id}"})
    return created["key"]["key"] if created else None

def on_subscription_ended(customer_id):
    admin("delete", {"name": f"cust_{customer_id}"})

Tekrarlanan bir abonelikten dönen None değerini bilinçli olarak ele alın. Anahtarın var olduğu ama değerini artık göremeyeceğiniz anlamına gelir; ilk seferde kaydetmediyseniz kurtarma yolu listelemek değil, silip yeniden oluşturmaktır. Değeri ilk aldığınızda kaydederseniz bu durum hiç oluşmaz.

Yönetim API'sini müşteriye açık bağlantı noktasında bırakmayın

Bu kurulum için en önemli bölüm burasıdır, çünkü tek sunucu ve tek bağlantı noktasının getirdiği kolaylık iki yönlü çalışır. Müşterilerinizin çözüm uç noktalarına erişmesi gerekir. Yönetim uç noktaları da aynı bağlantı noktasındadır, Bearer token dışında hiçbir korumaları yoktur ve taşıma katmanı denetimi de yoktur; dolayısıyla özel bir bağlantı noktasında bu token açık metin HTTP ile gider. Bu trafiği izleyebilen herkes onu okur, eline geçiren herkes de kendine bir anahtar oluşturur.

Örneğin önüne bir ters proxy koyun ve iki kitleyi birbirinden ayırın:

• İnternete yalnızca çözüm yollarını, proxy'de sonlandırılan HTTPS üzerinden yayınlayın ve yönetim yolunun altındaki her şey için 404 döndürün.
• Yönetim uç noktalarına kendi arka ucunuzdan özel bir güzergâhla erişin: faturalandırma servisiniz aynı Windows makinesinde çalışıyorsa geri döngü adresi, değilse özel bir ağ, bir VPN ya da bir SSH tüneli.

Kural şu: yönetim token'ı altyapınızdan asla çıkmamalı ve konuştuğu bağlantı noktası asla bir müşterinin erişebildiği yer olmamalı. Özellik açık olsun ya da olmasın, yönetim yolunu asla açık internete çıkarmayın.

Bilinmesi gereken bir sınır daha var, çünkü burada akla ilk gelen şey müşteri paneli yapmaktır. Tarayıcılar bu uç noktaları çağıramaz, çünkü yönetim yanıtları tasarımı gereği hiçbir CORS başlığı taşımaz. Paneliniz kendi arka ucunuz üzerinden geçmek zorundadır; zaten token'ın ait olduğu yer de orasıdır.

Anahtarlar gerçekte nereye yazılıyor

Anahtarlar, anahtarlarınızın zaten durduğu yere gider. Direct Input ve From File birbirinden ayrı iki listedir ve API, o an hangisi seçiliyse onu okuyup ona yazar. Ayarlar penceresinde kaynağı değiştirmek uç noktaların gördüğünü de değiştirir; bu yüzden az önce oluşturduğunuz anahtarın neden listede olmadığını merak etmeye başlamadan önce hangi modda olduğunuzu doğrulayın.

Dosya modunun önceden bilmekte fayda olan bir davranışı var: ilk yazma işlemi, düz metin anahtar dosyasını JSON olarak yeniden yazar. Hiçbir şey kaybolmaz ama biçim kalıcı olarak değişir, dolayısıyla dosyayı okuyan başka bir şey varsa önce yedek alın. Hiç dosya seçilmemişse yazma işlemi hiçbir yere düşemez ve 500 ile birlikte ERROR_ADMIN_STORE_FAILURE alırsınız. Buradaki bir 500 neredeyse her zaman bu demektir.

Bu özellik ortaya çıkmadan önce oluşturulmuş listeler hâlâ yinelenen adlar taşıyabilir, çünkü benzersizlik yalnızca eklemede denetlenir. Böyle bir kayıtta ada göre silmek ERROR_KEY_NAME_AMBIGUOUS döndürür ve hiçbir şeyi değiştirmez. Bunun yerine değere göre silin, belirsizlik ortadan kalkar.

Windows'ta kabuk tırnakları, testleri makinenin kendisinde yapıyorsanız

CapSkip bir Windows uygulamasıdır, dolayısıyla test ettiğiniz makine de çoğu zaman Windows'tur. Komut İstemi tek tırnağı bir tırnak karakteri saymaz. Kopyaladığınız komut, tırnak işaretlerini JSON gövdesinin parçası olarak gönderir, ayrıştırıcı reddeder ve tamamen doğru görünen bir komutta ERROR_ADMIN_BAD_REQUEST alırsınız.

PowerShell'de curl.exe'yi tam adıyla çağırın. Oradaki düz curl, Invoke-WebRequest için bir takma addır; bambaşka argümanlar alır ve bu API ile hiçbir ilgisi olmayan bir şekilde hata verir.

Hata kodları

Bunlar çözüm hata kodlarının yerini almaz, onların yanında durur; tam listeyi burada bulabilirsiniz: CapSkip API belgeleri.

FAQ

En kısa hâli

Remote Key Management'ı bir kez açın ve token'ı diğer faturalandırma sırlarınızla birlikte saklayın. Aboneliği etkinleştiğinde müşterinin adıyla bir anahtar ekleyin, tekrarda gelen 409'u başarı sayın ve abonelik bittiğinde aynı adla silin. Belirli aralıklarla listeleyip etkin abonelerinizle karşılaştırın, çünkü gerçek cevabın yaşadığı tek yer orasıdır. Sonra öne bir proxy koyun ve yönetim yolunu müşterilerinizin görebildiği bağlantı noktasından uzak tutun. Bunu yaparsanız captcha atlatma kendi donanımınız üzerinde yeniden satabileceğiniz bir şeye dönüşür ve oluşturma hızı, ödeme akışınızın webhook tetikleme hızı kadar olur.