> ## Documentation Index
> Fetch the complete documentation index at: https://docs.muhasip.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# E-Pos entegrasyonu

> Banka ve ödeme kuruluşu POS hesaplarını, kart ailesi tarifelerini, ödeme bağlantılarını ve tam iptal/iadeyi yönetin.

E-Pos, firmanızın kendi banka veya ödeme kuruluşu sanal POS hesaplarını kullanır. İşlemler `/apps/bankpos` altında, **`muhasip:epos:read`** ve **`muhasip:epos:write`** izinleriyle yapılır. Muhasip POS tahsilatının `/apps/pos` kaynakları ayrı hesap ve işlemlerdir.

## 1. Erişimi ve sağlayıcı desteğini okuyun

HTTP Basic kimlik bilgilerinizi sunucu tarafında kullanın. Firma, API anahtarından belirlenir. Genel erişim veya yönetici yetkisi E-Pos izninin yerine geçmez; `write` tek başına `read` sağlamaz. Firma paketi ücretli ve süresi aktif olmalıdır; Enterprise paketinde süre koşulu uygulanmaz.

* [Erişim durumunu okuyun](https://docs.muhasip.pro/api-reference/e-pos/epos-capabilities.md): Firma ortamı, hesap yönetim yetkisi ve ödeme/iade hazırlığı.
* [Sağlayıcıları listeleyin](https://docs.muhasip.pro/api-reference/e-pos/epos-providers.md): Kimlik alanları, gizli bağlantı alanları ve desteklenen işlemler.

Hoppa kodu `esnekpos` değeridir. `integrationStatus=planned` sağlayıcılar için yalnız taslak hesap yönetimi yapılır. Ödeme, bağlantı ve oran sorgusu yeteneklerini katalogdan kontrol edin. Hesabın ortamı firmanın test bilgisine bağlıdır; istekle test/canlı ortam seçilmez.

## 2. Hesabı hazırlayın

1. [Hesap oluşturun](https://docs.muhasip.pro/api-reference/e-pos/epos-create-account.md). İş niyetine ait kalıcı `Idempotency-Key`, hesap adı, sağlayıcı ve taksit/satış tarifelerini gönderin. Başlangıç durumu `draft` olur.
2. [Bağlantı bilgilerini kaydedin](https://docs.muhasip.pro/api-reference/e-pos/epos-credentials.md). Hoppa için `identity.merchant` işyeri kodu, `credentials.merchantKey` gizli anahtardır. Anahtar yanıttan geri okunamaz. Gerçek değeri sunucu ortamınızdan alın; örnek veya loglara koymayın.
3. [Bağlantıyı kontrol edin](https://docs.muhasip.pro/api-reference/e-pos/epos-check-connection.md). `connectionCheck.status=passed` sonucu hesabı kendiliğinden etkinleştirmez.
4. [Hesabı etkinleştirin](https://docs.muhasip.pro/api-reference/e-pos/epos-update-account.md): Güncel `revision` ile `status=active` gönderin. Para birimi/taksit desteği ve bağlantı koşulları ayrıca doğrulanır.

Her hesap yazımında cevapta dönen `revision` değerini saklayın. Yanıt kaybında önce [hesap ayrıntısını](https://docs.muhasip.pro/api-reference/e-pos/epos-account-detail.md) okuyun. Eski sürüm `409 BANKPOS_REVISION_CONFLICT` üretir. `If-Match` yerine bu kaynaklarda gövdedeki `revision` kullanılır.

Hesap oluşturma kendi tekrar anahtarıyla aynı hesabı döndürür; genel işlem makbuzu üretmez. Hesap güncelleme, bağlantı kaydı/kontrolü ve varsayılan seçiminde de genel `operation` makbuzu yoktur; güncel sürümle ilerleyin.

## 3. Genel ve kart ailesi satış tarifelerini tanımlayın

Hesaptaki `installmentRates` dizisi her tek çekim/taksitin aktifliğini ve genel satış oranını içerir. `familySaleRates` kart ailesi ve taksit bazındaki özel satışları içerir. Oranlar yüzde sayısıdır; örneğin `1.49`, **%1,49** demektir. En fazla dört ondalık kullanın.

```json theme={null}
{
  "revision": 4,
  "installmentRates": [
    { "installment": 1, "enabled": true, "saleRate": 0 },
    { "installment": 3, "enabled": true, "saleRate": 1 }
  ],
  "familySaleRates": [{ "family": "paraf", "installment": 3, "saleRate": 0 }]
}
```

Bu tarifede tek çekim komisyonsuzdur; 3 taksitte genel satış oranı %1, Paraf için %0'dır.

* Özel aile satırı yoksa genel satış oranı kullanılır. Açık `0` eksik değer değildir.
* Hesap güncellemesinde gönderilen oran dizisi bütün olarak değiştirilir. Genel taksit satırlarını ve korumak istediğiniz aile satırlarını birlikte değerlendirin; atlanan dizi mevcut hâliyle kalır, `familySaleRates: []` aile tarifelerini kaldırır.
* En az bir taksit aktif olmalıdır. Aile/taksit çifti tekrarlanamaz; aile tarifesinin taksiti hesapta tanımlı olmalıdır.
* [Alış oranlarını okuyun](https://docs.muhasip.pro/api-reference/e-pos/epos-installment-rates.md). Hoppa alışları aile/taksit bazında gelir; katalog güncel ödeme maliyetinin kesin hesabı değildir. Ödeme, müşterinin kartı ve çekim toplamıyla yeniden fiyatlanır.

Alışı satışa birebir yansıtmak için katalogdaki ilgili `purchaseRate` değerini satış tarifesine yazın. Puan eklemek istiyorsanız örneğin **%4,8 + 0,1 puan = %4,9** olarak hesaplayın; %4,8'in yüzde 0,1'i değildir. Geçerli değerleri tek hesap güncellemesinde gönderin. Alışı bulunmayan aile/taksiti sıfır maliyet saymayın; genel tarifeyi ayrıca belirleyin.

`family=null`, sağlayıcının aile belirtmediği alış satırıdır. Aile kodu olarak `null` ile satış tanımlanmaz; bu kartlarda genel satış tarifesi kullanılır.

## 4. Ödeme talebi oluşturun

[Ödeme talebi oluşturma](https://docs.muhasip.pro/api-reference/e-pos/epos-create-payment.md) için aktif/doğrulanmış hesap, güncel `accountRevision`, aynı firmaya ait arşivlenmemiş cari ve en az bir aktif taksit gerekir. Yeni Hoppa talebinde seçenekler 1–12 aralığındadır. Talep para birimi TRY'dir; tutar **kuruş cinsinden tamsayıdır**.

```json theme={null}
{
  "accountId": "600000000000000000000001",
  "accountRevision": 4,
  "contactsId": "600000000000000000000003",
  "amountMinor": null,
  "installmentOptions": [
    { "installment": 1, "saleRate": 0 },
    {
      "installment": 3,
      "saleRate": 0,
      "familySaleRates": [{ "family": "paraf", "saleRate": 0 }]
    }
  ]
}
```

* `amountMinor` verilmez veya `null` olursa müşteri ödeme sayfasında tutarı girer. `10000`, 100 TL'dir; sabit tutar müşteri tarafından değiştirilemez. Verilen tutar 1–1.000.000.000 kuruş olmalıdır.
* Birden fazla taksit sunabilirsiniz; müşteri kartının desteklediği izinli seçeneklerden birini seçer. `installment=1` tek çekimdir.
* Seçenekte `saleRate` verilmezse hesabın o taksite ait genel satışı alınır. `familySaleRates` verilmezse hesabın ilgili taksit aile tarifeleri alınır; açık `[]`, bu talepte genel tarifeyi kullanır.
* Talepte verilen oranlar yalnız o talebe aittir. Hesap tarifesi değişmez; talep, oluşturulduğu tarifeleri korur.
* Cari adı/tam ünvanı en az iki kelime olmalıdır. E-posta, telefon, il, ilçe ve adresin geçerli olanları cari kartından kullanılır; yalnız eksik/geçersiz olanlar ödeme sayfasında müşteriden alınır. Bu alanları talep gövdesine eklemeyin.

Talep oluşturmak karttan çekim başlatmaz. Cevaptaki `_id`, `reference`, `expiresAt`, `url` ve varsa `operation.operationId` değerlerini saklayın. Ödeme bağlantısı 30 dakika geçerlidir; `url` alanındaki adresi doğrudan kullanın ve günlüklemeyin. Kart/PAN/CVV alanlarını bu API'ye göndermeyin.

Hesap ayarı veya bağlantı bilgisi değiştirilirse eski hesap sürümüne bağlı henüz başlatılmamış talepler kullanılamayabilir. Aynı hesapta yeni talep oluşturmak veya başka bir ödeme tamamlamak, hesap ayarı değişikliği değildir.

## 5. Ödemeyi ve komisyonları doğrulayın

Müşteri ödeme bağlantısında eksik bilgilerini, gerekiyorsa tutarı ve kartını girer; sunulan seçenekten bir taksit seçer ve 3D adımını tamamlar. Satış komisyonu çekim toplamına eklenir. Satış oranı 0 olsa da sağlayıcının alış komisyonu bulunabilir.

Örnek: 100 TL ana tutar, %0 satış ve %4,8 alış maliyetinde müşteri toplamı 100 TL, satış komisyonu 0, tahmini alış komisyonu 4,80 TL ve tahmini net 95,20 TL'dir. Üç taksit dağılımı kuruş yuvarlamasıyla 33,34 + 33,33 + 33,33 TL olabilir. Bunlar örnek oranlardır; gerçek alış teklifi kart ve tutarla belirlenir.

[Ödeme ayrıntısını okuyun](https://docs.muhasip.pro/api-reference/e-pos/epos-payment-detail.md). Kart seçilmeden `totalMinor`, alış komisyonu ve net alanları bulunmayabilir veya `null` olabilir; sıfır varsaymayın. Gerçek seçim sonrası komisyon/toplam/taksit alanları sabitlenir. `netMinor`, tekliften hesaplanan tahmini nettir; banka valörü, kesin mutabakat veya muhasebe kaydı değildir.

| Durum | Anlamı / izlenecek adım |
| - | - |
| `open` | Müşteri ödemeyi henüz başlatmadı; `expiresAt` değerini kontrol edin. |
| `processing` | Ödeme başlatıldı; sonucu izleyin. |
| `paid` ve `verification=verified` | Ödeme sağlayıcı sorgusuyla doğrulandı. |
| `not_found` | Sağlayıcıda referans henüz bulunamadı; yeniden çekim başlatma izni değildir. |
| `failed` | Başarısız sonuç kaydedildi; doğrulama bilgisini ve ayrıntıyı inceleyin. |
| `voided` / `refunded` | İptal / iade sağlayıcıdan doğrulandı. |
| `partially_refunded` | Kaydın kalan tutarını ve geçmişini okuyun; yeni kısmi iade gönderilemez. |
| `expired` / `cancelled` | Kullanılamayan taleptir; aynı bağlantıyla ödeme başlatmayın. |

Başlatılmış bir denemenin sonucu belirsizse [sağlayıcı durumunu sorgulayın](https://docs.muhasip.pro/api-reference/e-pos/epos-query-payment.md). Bu çağrı mevcut denemeyi kontrol eder; çekim/iade göndermez. Cevabı `paymentId`, `status`, `verification` ve `reconciliation` içerir; komisyonlar ve bağlantı için ayrıntıyı yeniden okuyun. Başlatılmamış talepler bu sorguya uygun değildir.

HTTP 200, 3D dönüş sayfası veya API makbuzundaki `succeeded` tek başına **Ödendi** anlamına gelmez. `verification=query_unavailable`, `review_required` veya sağlayıcıda bulunamayan sonuçta yeni çekim başlatmayın. Sürekli sık sorgu yerine istek sınırlarına uygun aralıklarla kayıt durumunu izleyin.

## 6. Tam iptal veya iade gönderin

Ödeme ayrıntısında `canReturn=true` ve pozitif `remainingMinor` varsa [tam iptal/iade](https://docs.muhasip.pro/api-reference/e-pos/epos-return-payment.md) talep edilebilir. `amountMinor` güncel kalan **çekim tutarının tamamı** olmalıdır. Ana tutar 100 TL, müşteriden çekilen toplam 103 TL ise iade tutarı `10300` kuruştur.

Bu çağrı için ayrı iş niyetine ait kalıcı `Idempotency-Key` kullanın. Kısmi tutar `422 BANKPOS_FULL_RETURN_REQUIRED` üretir. Ödenmiş kayıt, aynı firma/ortam ve sağlayıcının mali uygunluk koşulları ayrıca denetlenir. Gün sonu ve iade uygunluğu sağlayıcıya bağlıdır.

`returnOperations[].state=verified`, `kind=void|refund`, `returnedMinor` ve `remainingMinor` alanlarını inceleyin. Bekleyen veya belirsiz sonuçta aynı mali isteği yeni anahtarla göndermeyin; mevcut ödemeyi sorgulayın. Tamamlanmış iptal/iade tekrarında yeni mali gönderim oluşturulmaz.

## İşlem makbuzu ve ödeme durumu farklıdır

`POST /payments` ve `POST /payments/{paymentId}/returns` çağrıları [genel işlem takibi](https://docs.muhasip.pro/rehberler/islem-takibi.md) makbuzu üretir. Göreli yollar burada `/apps/bankpos` köküne göredir.

Makbuzdaki `succeeded`, talebin API tarafından işlendiğini gösterir. Ödemenin/iptal/iadenin mali doğruluk kaynağı ödeme kaydının doğrulanmış durumudur. Aynı anahtar ve farklı içerik `409 IDEMPOTENCY_PAYLOAD_CONFLICT` üretir. Tamamlanmış tekrar cevabı ayrıntı yerine makbuz ve güvenli kimlikler içerir; `paymentId` ile ayrıntıyı okuyun.

Genel makbuz `dispatching`, `review_required` veya `provider_accepted` durumunda kalmışsa yeni anahtar üretmek işlemi yeniden başlatma izni vermez. `GET /apps/operations/{operationId}` ile makbuzu ve ödeme kaydını okuyun. Sağlayıcı doğrulaması için yalnız mevcut ödeme sorgusunu kullanın. E-Pos makbuzunu okumak için de açık `epos:read` veya `epos:write` izni gerekir.

## Hesap yaşam döngüsü ve destek sınırları

* [Hesapları listeleyin](https://docs.muhasip.pro/api-reference/e-pos/epos-accounts.md); arşivlenmiş hesaplar için `status=archived` gönderin. Hesap adı/sağlayıcı/durum ve sayfalama desteklenir.
* Pasifleştirme ve arşivleme [hesap güncelleme](https://docs.muhasip.pro/api-reference/e-pos/epos-update-account.md) üzerinden yapılır. İşlem geçmişi korunur.
* [Silme](https://docs.muhasip.pro/api-reference/e-pos/epos-delete-account.md) yalnız işlem/faaliyet kaydı olmayan hesap için geçerlidir.
* [Varsayılan hesabı seçin](https://docs.muhasip.pro/api-reference/e-pos/epos-save-preferences.md). Ortam/para birimi başına tek uygun aktif hesap atanabilir; liste bütün olarak değiştirilir.
* Ödeme taleplerini [hareket listesinden](https://docs.muhasip.pro/api-reference/e-pos/epos-payments.md) izleyin. Liste tutarı, kart seçilmeden ana tutar; sonrasında çekim toplamıdır. Komisyon analizi için ayrıntıyı kullanın.
* Kayıtlı kart, tekrarlı tahsilat, kısmi iade, genel müşteri webhook'u, başlatılmamış talebi API ile kapatma ve otomatik cari/muhasebe mahsubu sunulmaz.

[E-Pos API referansı](https://docs.muhasip.pro/api-reference/e-pos/epos-capabilities.md) · [OpenAPI](https://docs.muhasip.pro/openapi.json) · [Manuel kabul](https://docs.muhasip.pro/rehberler/manuel-kabul.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.