Metadata-Version: 2.4
Name: iyzi-cli
Version: 0.1.1
Summary: Unofficial iyzico CLI for sandbox testing, payment operations, and webhook tooling
Author: Goktug Ecertastan
License: MIT
Project-URL: Homepage, https://github.com/goktugecertastan-cyber/iyzi-cli
Project-URL: Repository, https://github.com/goktugecertastan-cyber/iyzi-cli
Project-URL: Issues, https://github.com/goktugecertastan-cyber/iyzi-cli/issues
Keywords: iyzico,payment,cli,ödeme,iyzipay,sandbox,webhook
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: iyzipay>=1.0.42
Requires-Dist: click>=8.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# iyzi — iyzico CLI

[![PyPI](https://img.shields.io/pypi/v/iyzi-cli)](https://pypi.org/project/iyzi-cli/)
[![test](https://github.com/goktugecertastan-cyber/iyzi-cli/actions/workflows/test.yml/badge.svg)](https://github.com/goktugecertastan-cyber/iyzi-cli/actions/workflows/test.yml)
[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![coverage](https://img.shields.io/badge/coverage-86%25-brightgreen)](#testler)

**Terminalden iyzico ödemeleri.** Ödeme oluştur/sorgula, iade/iptal, 3DS başlat,
webhook doğrula, BIN/taksit sorgula — hepsi tek komutla, makine-okur `--json`
çıktısıyla, çift-tahsilata karşı yerel guardrail'lerle.

Neden bu araç?

- 🔒 **Kart verisi sızmaz** — PAN/CVC/secret hiçbir log, defter veya hata
  mesajında görünmez (PCI bilinçli, testle kanıtlı).
- 🔁 **Çift tahsilat koruması** — iyzico idempotent değildir; yerel defter +
  mutabakat ile kör retry engellenir.
- 🤖 **Agent-dostu** — kararlı `--json`, stabil exit kodları, asla beklenmedik prompt.
- 💯 **Doğru para** — `Decimal` ile kuruş hassasiyeti (float sapması yok).

> Not: Bu, iyzico'nun resmi ürünü değildir — iyzico API'si üzerine geliştirilmiş
> bağımsız bir araçtır.
> _iyzi-cli is an unofficial developer tool and is not affiliated with iyzico._

> ⚠️ **Önce sandbox.** Tüm geliştirme ve denemeler `sandbox` ortamında
> yapılır. Canlıya (`production`) ancak akış oturduktan sonra geçilir.

## 60 saniyede başla

```bash
# İzole CLI kurulumu için pipx veya uv önerilir:
pipx install iyzi-cli            # veya:  uv tool install iyzi-cli
# (sade pip de olur:)
pip install iyzi-cli

cp .env.example .env             # sandbox anahtarlarınızı girin
iyzi durum                       # bağlantı/anahtar kontrolü
iyzi odeme test --tutar 25.00    # test kartıyla örnek ödeme
iyzi completion install          # TAB ile komut tamamlama (bash/zsh/fish)
```

Tek seferlik deneme (kurulum yapmadan):

```bash
uvx iyzi-cli --help
```

![iyzi demo](docs/demo.gif)

<!-- Demo'yu yeniden üretmek için: vhs scripts/demo.tape (bkz. scripts/demo.tape) -->

## Kurulum

En hızlı yol (GitHub'dan doğrudan):

```bash
pip install git+https://github.com/goktugecertastan-cyber/iyzi-cli.git
```

Veya depoyu klonlayıp geliştirici modunda kurmak için:

```bash
git clone https://github.com/goktugecertastan-cyber/iyzi-cli.git
cd iyzi-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"   # [dev] testleri de kurar
```

Kurulumdan sonra `iyzi` komutu kullanılabilir hale gelir:

```bash
iyzi --version
iyzi --help
```

## Anahtar ayarı

Anahtarlar **asla koda gömülmez**. `.env` dosyasından okunur:

```bash
cp .env.example .env
# .env dosyasını açıp kendi sandbox anahtarlarınızı girin
```

`.env` dosyası `.gitignore`'dadır, commit edilmez.

Sandbox anahtarları: <https://sandbox-merchant.iyzipay.com>

## Tanı logu (sorun bildirimi)

Varsayılan olarak **hiçbir log dosyası tutulmaz**. Bir hatayı destek ekibine
iletmeniz gerekirse, tanı logunu açıkça etkinleştirin:

```bash
IYZI_LOG=1 iyzi odeme getir --id 12345678
```

Bir hata oluşursa kayıt `~/.iyzi/logs/error.log` dosyasına (izin `600`) yazılır
ve CLI size bu yolu gösterir. **Log dosyası kart numarası, CVV veya API/secret
anahtar İÇERMEZ** — yazılan tüm metin diske ulaşmadan maskelenir (PAN → son 4,
CVV/secret → gizli). Bu dosyayı güvenle destek ekibimize iletebilirsiniz.

## Kullanım

```bash
# Adım adım kurulum (ortam + anahtarları sorar, doğrular, .env'e yazar)
iyzi setup

# Ortam/kurulum teşhisi (sürümler, ortam, config kaynağı — sır göstermez)
iyzi doctor

# Anahtar/bağlantı kontrolü
iyzi durum

# Test kartıyla örnek ödeme (sandbox — canlıda çalışmaz)
iyzi odeme test --tutar 25.00

# Gerçek kart bilgisiyle Non-3DS ödeme
# GÜVENLİK: kart no ve CVC'yi bayrakta vermeyin — verilmezse güvenli (gizli)
# olarak sorulur. Böylece shell geçmişine/process listesine sızmazlar.
iyzi odeme olustur --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030
#   → "Kart numarası:" ve "CVC:" gizli sorulur

# (Sandbox otomasyonu için bayraklar yine kullanılabilir — riski göze alarak)
iyzi odeme olustur --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030 --kart-no 5528790000000008 --cvc 123

# 3DS ödeme başlat (doğrulama formu + paymentId döner)
iyzi odeme 3ds-baslat --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030 \
  --callback-url https://siteniz.com/3ds-callback --html-kaydet form.html

# Ödeme detayı getir
iyzi odeme getir --id <PAYMENT_ID>

# İade (onay ister)
iyzi iade yap --tx <TRANSACTION_ID> --tutar 10.00

# Ödeme iptali (onay ister)
iyzi iade iptal --id <PAYMENT_ID>

# Çoklu hesap: isimli profiller (sandbox-dev, production vb.)
iyzi config set sandbox-dev --env sandbox   # anahtarlar gizli sorulur
iyzi config use sandbox-dev
iyzi config list

# BIN sorgulama (kartın bankası/tipi) ve taksit seçenekleri
iyzi bin sorgula --kart-no 552879
iyzi bin taksit --kart-no 552879 --tutar 100.00

# Hata kodu açıklaması (yerel sözlük, API çağrısı yok)
iyzi hata 10051

# Sahte (imzalı) webhook üret — kendi sunucunu test etmek için
iyzi webhook uret --odeme-id 12345 --durum SUCCESS

# Ham API erişimi — özel komutu olmayan her endpoint
echo '{"binNumber":"552879"}' | iyzi api post /payment/bin/check
```

### Webhook imza doğrulama

iyzico, webhook bildirimlerine `X-IYZ-SIGNATURE-V3` başlığı ekler.
Sunucunda bu imzayı doğrulamadan bildirime güvenmek güvenlik açığıdır.
Bu komut imzayı senin yerine doğru üretip karşılaştırır (tamamen yerel,
API çağrısı yok):

```bash
# Gelen bildirimi (JSON) ve imzayı doğrula:
iyzi webhook dogrula --govde bildirim.json --imza <X-IYZ-SIGNATURE-V3>

# Sunucu logundan pipe ile:
cat bildirim.json | iyzi webhook dogrula --imza <SIGNATURE>

# Hosted Payment Page formatı için:
iyzi webhook dogrula --govde bildirim.json --imza <SIG> --hpp

# Sadece beklenen imzayı üret (test/hata ayıklama):
iyzi webhook dogrula --govde bildirim.json --uret
```

Geçerli imza → çıkış kodu `0`, geçersiz → `1`.

### 3DS hakkında not

3DS ödemeler tarayıcı gerektirir: `3ds-baslat` size bir HTML doğrulama
formu (`threeDSHtmlContent`) ve `paymentId` döndürür. Bu formu kullanıcıya
gösterirsiniz, kullanıcı OTP girer, iyzico `--callback-url`'inize `paymentId`
ile döner. Ödemeyi tamamlamak (Auth-3DS) backend'inizde o `paymentId` ile
yapılır — tarayıcı adımı CLI kapsamı dışındadır.

## Testler

```bash
pip install -e ".[dev]"

# Birim testler (ağsız, hızlı — entegrasyon otomatik atlanır):
pytest

# Entegrasyon + uçtan uca (gerçek sandbox, anahtar gerekir):
IYZI_ENV=sandbox IYZI_API_KEY=... IYZI_SECRET_KEY=... pytest -m "integration or e2e"
```

Test katmanları: **birim** (mock, CI'da her zaman) · **integration** (sandbox
kimlik/bağlantı) · **e2e** (ödeme→sorgu→iade yaşam döngüsü). Anahtar yoksa
entegrasyon/e2e testleri güvenle atlanır.

> Girdi doğrulama: tutar, taksit, kart numarası (Luhn), son kullanma tarihi ve
> CVC, API'ye gönderilmeden önce yerel olarak doğrulanır — hatalı girdi
> anlaşılır bir mesajla reddedilir, iyzico'ya gereksiz istek gitmez.

### Faydalı bayraklar

| Bayrak | Açıklama |
|---|---|
| `--json` | Çıktıyı saf JSON olarak verir (otomasyon/pipe için). |
| `--quiet` / `-q` | Yardımcı mesajları (banner/bilgi) bastırır, sadece sonucu verir. |
| `--yes` / `-y` | Onay sorularını otomatik geçer (script'lerde). |
| `--env sandbox\|production` | Ortamı bayrakla geçersiz kılar. |
| `--api-key` / `--secret-key` | Anahtarı bayrakla geçersiz kılar. |

Her komutta `--help` çalışır:

```bash
iyzi --help
iyzi odeme --help
iyzi iade yap --help
```

## Sekme tamamlama (tab completion)

Komutları ve seçenekleri TAB ile tamamlayın (bash / zsh / fish):

```bash
iyzi completion install        # aktif shell'i bulur, başlangıç dosyasına ekler
# veya elle incelemek için:
iyzi completion show zsh       # script'i basar (kurmaz)
```

Sonra yeni bir terminal açın (veya `source ~/.zshrc`). Artık `iyzi od<TAB>` →
`odeme`, `--tut<TAB>` → `--tutar` çalışır. Kurulum idempotenttir (iki kez
çalıştırmak güvenlidir).

## Çıktı kuralları

- **Başarı sessiz, hata gürültülü.** İnsan mesajları `stderr`'e, asıl
  veri `stdout`'a gider — böylece `--json` çıktısı pipe ile temiz akar.
- **Çıkış kodu (exit code):** başarı `0`, API/iş hatası `1`, kimlik/config
  hatası `2`, kullanıcı iptali (Ctrl+C) `130`. Script'lerde güvenle kontrol edilebilir.

## AI agent / otomasyon

CLI, AI agent'ları ve otomasyon sistemleri tarafından **güvenli** kullanılacak
şekilde tasarlandı (kararlı JSON, çift-tahsilat guardrail'i, mutabakat):

- **Operasyon defteri** (`IYZI_LEDGER=1`): para hareketlerini yerel olarak
  izler; retry-öncesi "bunu zaten denedim mi?" kontrolü yapar (iyzico idempotent
  değildir). `iyzi ledger list|show|reconcile`. Defter kart/CVC/secret saklamaz.
- **Mutabakat**: `iyzi ledger reconcile` / `iyzi odeme getir` ağ hatası sonrası
  "ödeme oldu mu?" sorusunu deterministik yanıtlar.
- **Raporlama**: `iyzi rapor islem|gunluk` (hesapta raporlama servisi etkinse).

Ayrıntılı rehberler:

- [docs/agent-reference.md](docs/agent-reference.md) — komut matrisi, exit
  kodları, güvenli retry, "ağ koptu ne yapmalı" senaryosu.
- [docs/json-contracts.md](docs/json-contracts.md) — JSON istek/yanıt şekilleri.
- [docs/3ds-lifecycle.md](docs/3ds-lifecycle.md) — uçtan uca 3DS akışı.
- [docs/webhooks.md](docs/webhooks.md) — webhook üretim/doğrulama.
- [docs/production-runbook.md](docs/production-runbook.md) — üretim geçişi.
- [docs/smoke-test.md](docs/smoke-test.md) — uçtan uca smoke test (sandbox + production).

## Canlıya geçiş

1. `.env` içinde `IYZI_ENV=production` yapın.
2. Gerçek anahtarları girin (<https://merchant.iyzipay.com>).
3. Canlı ortamda CLI her komutta **kırmızı uyarı** gösterir.
4. Adım adım güvenli geçiş: [docs/production-runbook.md](docs/production-runbook.md).

## Mimari

```
iyzi/
  config.py      Anahtar/ortam yönetimi (bayrak > env > .env > profil önceliği)
  client.py      API istemcisi + hata yorumlama
  signing.py     IYZWSv2 istek imzalama (kendi uygulamamız)
  validators.py  Girdi doğrulama (tutar, kart/Luhn, tarih, CVC, callback URL)
  errors.py      iyzico hata kodu sözlüğü (yerel)
  webhook.py     Webhook imza üretme/doğrulama (X-IYZ-SIGNATURE-V3)
  profiles.py    İsimli profil yönetimi (XDG, izin 600)
  cli.py         Click komut arayüzü
  output.py      Tablo/JSON/renk çıktı yardımcıları
  samples.py     Sandbox test kartı ve örnek veriler
```

**Kimlik bilgisi önceliği:** bayrak > ortam değişkeni > `.env` > aktif profil.

**İmzalama:** Standart ödeme/iade akışları resmi `iyzipay` SDK ile yapılır.
Ek olarak [signing.py](iyzi/signing.py) iyzico'nun **IYZWSv2** imza protokolünü
(HMAC-SHA256 + base64) sıfırdan uygular; `api post` ham erişim komutu bunu
kullanır ve SDK'ya bağımlı değildir. Bu uygulamanın SDK ile **birebir aynı**
imzayı ürettiği testlerle kanıtlanır (`tests/test_signing.py`).
