providercheck: Uyumluluk Kiti

providercheck, merchant-provider/v1 API'nizin sözleşmeye uygun davrandığını canlıya geçmeden önce sandbox (test ortamı) üzerinde kanıtlar. Önce Chargeless'ın canlı sözleşme kontrolündeki satırların aynısını çalıştırır; ardından canlı bir sistemde para hareketi olmadan gösterilemeyecek durumları sınar: gerçek bir iade ve tekrarı, bir idempotency çakışması, API'nizin reddetmesi gereken bir fazla iade, gerçek bir iptal, bir kez reddedildikten sonra hep reddedilen bir anahtar ve her get_operation durumu. Canlıya geçmek için son 30 gün içinde başarıyla tamamlanmış ve panele yüklenmiş bir çalıştırma gerekir.

Kit, hiçbir bağımlılığı olmayan tek bir dosyadır. Kendi makinenizde çalıştığı için localhost'taki ya da VPN'inizin içindeki bir sandbox'a da erişebilir; sandbox imzalama anahtarınız makinenizden hiç çıkmaz.

İndirin

providercheck/2 sürümü, sözleşmenin 1.0 ile 1.2 arasındaki revizyonları içindir.

Sistem	Dosya
macOS, Apple silicon	providercheck-darwin-arm64
macOS, Intel	providercheck-darwin-amd64
Linux, x86-64	providercheck-linux-amd64
Linux, ARM64	providercheck-linux-arm64
Windows, x86-64	providercheck-windows-amd64.exe

SHA256SUMS her dosyanın SHA-256 özetini listeler. Dosyayı terminalden indirin ve çalıştırmadan önce doğrulayın:

# macOS on Apple silicon; use your file's name from the table
curl -fsSLO https://chargeless.io/developers/downloads/providercheck/providercheck-darwin-arm64
curl -fsSLO https://chargeless.io/developers/downloads/providercheck/SHA256SUMS
grep providercheck-darwin-arm64 SHA256SUMS | shasum -a 256 -c -    # Linux: sha256sum -c -
mv providercheck-darwin-arm64 providercheck && chmod +x providercheck
./providercheck -version

Windows'ta dosyayı PowerShell'de Get-FileHash providercheck-windows-amd64.exe ile kontrol edin ve sonucu SHA256SUMS içindeki satırla karşılaştırın.

Dosyalar Apple veya Microsoft sertifikasıyla imzalı değildir. curl ile indirilen dosya olduğu gibi çalışır; macOS'ta tarayıcıyla indirilen dosya ise karantinaya alınır. SHA-256 özetini doğruladıktan sonra xattr -d com.apple.quarantine providercheck komutuyla dosyayı karantinadan çıkarabilirsiniz.

Çalıştırmadan Önce

API'niz, faturalama sisteminizin sandbox'ının önünde çalışıyor olmalı; orada iade ve iptal hiçbir maliyet doğurmaz.
Sandbox'ınız, sandbox imzalama anahtarıyla doğrulama yapmalı. Chargeless bu anahtarı, bağlantınızı panelde (Ayarlar → Entegrasyonlar → bağlantınız) ilk kez kaydettiğinizde yalnızca bir kez gösterir; anahtar srmps_ ile başlar. Yeni bir anahtar almak için bağlantıyı düzenleyin ve "Yeni bir test ortamı imzalama anahtarı oluştur" seçeneğini işaretleyin. Bu anahtarı yalnızca sandbox'ta tanımlayın: canlı (production) API'niz onu reddetmelidir.
Sandbox'ta yeni test verileri (fixture) seçin: bir müşteri, bu müşterinin iade edilebilir bir ödemesi ve iptalleri destekliyorsanız aynı müşterinin etkin bir aboneliği. Çalıştırma ödemeyi iade eder (kısmi iadeyi destekliyorsanız en küçük birimden 1 birim, desteklemiyorsanız kalanın tamamı) ve aboneliği iptal eder; bu yüzden her çalıştırmada yeni test verileri kullanın.
Çalışma alanı kimliğiniz: Ayarlar → Genel altında Çalışma alanı kimliği olarak görünür; panelin Uyumluluk kiti bölümünde gösterdiği komutta da sizin için doldurulmuştur. Chargeless'ın idempotency anahtarları bu kimlikle başlar; kit de anahtarları aynı biçimde gönderir.

Çalıştırın

Gizli anahtarlar komut satırından asla alınmaz, yalnızca ortam değişkenlerinden okunur.

export PROVIDERCHECK_SANDBOX_SIGNING_SECRET=srmps_…
# optional, when your sandbox needs them:
#   export PROVIDERCHECK_BEARER_TOKEN=…
#   export PROVIDERCHECK_EDGE_HEADERS='[{"name":"CF-Access-Client-Id","value":"…"}]'   (at most 3)

./providercheck -sandbox \
  -base-url https://sandbox.billing.example.com/supportroute \
  -tenant <your workspace id> \
  -customer cus_… -transaction ch_… -subscription sub_… \
  -out providercheck-report.json

MCP bağlantısı için -transport mcp ekleyin ve -base-url olarak sandbox'ınızın MCP uç noktasını verin.

Bayrak	Kullanım
`-sandbox`	Zorunlu: çalıştırma gerçekten iade ve iptal yaptığı için hedefin bir sandbox olduğunu bu bayrakla onaylarsınız
`-base-url`	Sandbox'ınızın temel URL'si; `-transport mcp` ile MCP uç noktası
`-transport`	`rest` (varsayılan) veya `mcp`
`-tenant`	Çalışma alanı kimliğiniz
`-customer`, `-transaction`, `-subscription`	Test verileri; iptalleri desteklemiyorsanız `-subscription`'ı vermeyin
`-out`	Mühürlü raporun yazılacağı dosya (varsayılan `providercheck-report.json`)
`-allow-private`	Düz http üzerinden, başka bir portta ya da özel bir adreste (localhost, VPN) çalışan sandbox'lar için
`-client-cert`, `-client-key`	mTLS isteyen bir sandbox için kendi test istemci sertifikanız
`-settle-timeout`	`pending` bir sonucun ne kadar bekleneceği: varsayılan 2 dk, en fazla 30 dk
`-v`	Her çağrıyı günlüğe yazar (kimlikler, durumlar ve gecikmeler; gövdeyi asla yazmaz)
`-version`	Kitin sürümünü yazdırıp çıkar

Kit; canlı ortamın imzalama anahtarıyla (srmp_…), -sandbox olmadan ya da sözleşmenin reddedeceği bir test verisi referansıyla (örneğin ardışık 13 veya daha fazla rakam içeren bir değer) başlatılırsa çalışmaz. Raporun kaydedemeyeceği bir kaynak adresini (origin) de kabul etmez; örneğin rakamları port numarasıyla birleşince 13 veya daha fazla rakam oluşturan bir IPv4 adresi. Böyle bir durumda IP adresi yerine bir alan adı kullanın.

Sonucu Okuyun

Kit her kontrol için bir satır, en sonda da genel sonucu yazdırır. Bunlardan önce görünen WARN satırları, kitin bilerek tetiklediği çağrılardır (yanlış imza, çakışma):

text

providercheck/2 against https://sandbox.billing.example.com over rest (run 01a1cec2-cdc0-7251-af9e-9fc989823775, contract 1.0)
  reachability             passed  TLS and an HTTP answer from the configured endpoint, through Chargeless's egress
  describe                 passed  contract version 1.0; a wrong signature and a stale timestamp were refused
  get_transaction          failed  schema_invalid get_transaction answered 200 with a body that breaks the contract (schema_invalid): `amount.amount_minor` is missing
                                   X-SR-Request-Id 01a1cec2-cdc8-79eb-b918-1b84d0bab31f
  …
FAILED; sealed report written to providercheck-report.json

Çıkış kodu 0 tüm kontrollerin geçtiğini, 1 en az birinin başarısız olduğunu, 2 ise çalıştırmanın başlatılamadığını gösterir.
Başarısız bir satırda kontrolün adı, bir hata kodu, beklenen davranış ve şemaya uymayan bir yanıtta ilgili alan yer alır. X-SR-Request-Id ile çağrıyı kendi günlüklerinizde bulabilirsiniz.
Örneklerle REST bağlantısı her kontrolün beklediği yanıtı gösterir; Uyumluluğu kanıtlamak ise tüm kontrolleri geçme koşullarıyla birlikte listeler.

Sandbox kontrolü	Geçme koşulu
`refund_over_refundable`	Kalanı en küçük birimden 1 birim aşan gerçek bir iade `amount_exceeds_refundable` ile reddedilir
`refused_key_final`	Aynı anahtar yeniden gönderildiğinde yine reddedilir, `get_operation` `failed` döner ve hiç para hareketi olmamıştır
`refund_executes`	İade bir kez gerçekleşir ve `refunds[]` onu Chargeless'ın anahtarıyla listeler
`refund_replay`	Yeniden gönderim ilk sonucu döndürür ve ek bir iade yapmaz
`refund_conflict`	Aynı anahtar farklı bir tutarla gönderildiğinde `409 idempotency_conflict` alır ve hiçbir işlem yapılmaz
`cancel_executes`, `cancel_replay`, `cancel_conflict`	Aynı kontroller, hemen geçerli olan bir iptal için
`cancel_refused_key`	İkinci bir iptal `already_canceled` ile reddedilir; yeniden gönderildiğinde yine reddedilir ve `failed` olarak okunur
`one_effect_per_call`	İade aboneliği etkilemez, iptal de ödemeyi etkilemez
`operation_states`	Yeniden okunan her anahtar son durumunu korur; hiç gönderilmemiş bir anahtar ise `unknown` döner

Raporu Yükleyin

Rapor dosyası, sandbox imzalama anahtarınızdan türetilen bir anahtarla mühürlenir; böylece daha sonra dosyanın kitin değiştirilmemiş çıktısı olduğunu anlayabilirsiniz. Dosyayı panelde Ayarlar → Entegrasyonlar → bağlantınız → Uyumluluk kiti altında yükleyin: dosyayı seçin, "Bu dosya, kitin bu çalışma alanı için değiştirilmemiş çıktısıdır" kutusunu işaretleyin ve raporu beyan edin.

Canlıya geçmek için kullandığınız aktarımla (REST veya MCP) son 30 gün içinde alınmış başarılı bir rapor gerekir; aktarımı sonradan değiştirdiğinizde de aynı koşul geçerlidir.
Chargeless dosyanın SHA-256 özetini (shasum -a 256 providercheck-report.json), kit sürümünü, çalıştırma bilgisini, aktarımı, sandbox'ınızın kaynak adresini ve her satırın sonucunu kaydeder. Dosyanın kendisini saklamaz; kendi kopyanızı saklayın.
Chargeless mührü doğrulayamaz (sandbox imzalama anahtarınızı saklamaz): beyan, ekip üyenizin dosyanın kitin çıktısı olduğuna dair kendi ifadesidir.

Önce Kendi Makinenizde Deneyin

Sandbox'ınız hazır olmadan önce kiti, Faturalama sisteminizi bir öğleden sonrada bağlayın rehberinde gösterildiği gibi Örneklerle REST bağlantısı sayfasındaki eksiksiz sunucuya karşı çalıştırın. Bu sunucu tüm satırlardan geçer; böylece başarılı bir çalıştırmanın neye benzediğini görürsünüz.