Mali işlem takibi ve tekrar

Belge oluşturma/gönderme/iptal, muhasebeye aktarım ve tahsilat gibi korunan işlemler, yeniden çağrıda aynı mali etkinin kontrolsüz tekrarlanmasını önleyen kalıcı bir işlem makbuzu üretir. Dönen işlem kimliğiyle sonucu takip edin ve aynı işi yeniden göndermeden mevcut işlem durumunu kontrol edin.

İşlem kimliği ve Idempotency-Key

Yeni hedef kimliği henüz olmayan işlemlerde Idempotency-Key zorunludur. Anahtar 1–128 görünür ASCII karakteri içermelidir; boşluk, kontrol karakteri veya kişisel veri kullanmayın. İş referansınızdan türettiğiniz bir değeri istekten önce kalıcı olarak saklayın.

İşlem	Anahtar gereksinimi
Fatura `POST /apps/invoice/api`, `type=view`	Zorunlu
Fatura `GET /apps/invoice/sync`	Zorunlu
POS `POST /apps/pos/link`	Zorunlu
Banka `GET /apps/bank/ws/automations/{id}/run`	Zorunlu
POS `PUT /apps/pos`, başvuru/etkinleştirme	Zorunlu; `status=false` ile pasifleştirmede kullanılmaz
e-Arşiv `PATCH /apps/earsiv`, `func=send`	Zorunlu
e-Arşiv `PATCH /apps/earsiv`, `func=verifyPhoneNumber`	Zorunlu
Belirli UUID ile fatura aktarım/iptal/taslak onay-silme	Hedef kimliği kullanılır
Belirli tahsilat iptali veya banka hareketi onayı	Hedef kayıt kimliği kullanılır
e-Arşiv belge iptali ve imza	Belge ETTN’si; imzada ETTN + SMS işlem kimliği kullanılır
Pazaryeri sipariş durumu güncelleme ve faturaya aktarım	Sipariş kimliği kullanılır

Hedefi belirli bir mali işlemde farklı Idempotency-Key vermek aynı hedefi yeniden başlatmaz. Pazaryeri durum güncellemesinde sipariş kimliği ve istenen durum birlikte işlem türünü belirler; farklı durum geçişleri ayrı işlemdir, aynı sipariş için eş zamanlı güncelleme 409 döndürebilir. Bir belgenin onay/iptal gibi çatışan işlemleri de aynı hedef üzerinde sıralanır. Fatura onayı/silmesinde 1–100 benzersiz UUID toplu gönderilebilir; bir hedefteki çatışma bütün isteği durdurabilir. Eşitleme, her belge aktarımını tekil aktarımın kullandığı korumadan geçirir.

curl --request POST 'https://api.muhasip.pro/apps/pos/link' \
  --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ORNEK-TAHSILAT-20261018-0001' \
  --data '{"description":"Örnek tahsilat","amount":1200}'

Aynı işlemi aynı içerikle yeniden çağırmak, işlem tamamlanmışsa güvenli makbuzu replayed:true ile döndürebilir. İlk çağrının bütün HTML/PDF, alıcı verisi veya yanıt içeriği yeniden üretilmez. Aynı işlem kimliğini farklı içerikle kullanmak 409 IDEMPOTENCY_PAYLOAD_CONFLICT üretir. İşlem failed_before_dispatch durumunda ve retryable:true ise, hata giderildikten sonra aynı iş referansıyla kontrollü tekrar değerlendirilebilir. Aynı firmadaki banka onayı, fatura aktarım/iptali ve pazaryeri aktarımı gibi mali işlemler çakışırsa 409 dönebilir. Okuma istekleri kullanılabilir. Sonuç belirsizse başka bir mali işlem de 409 alabilir; ilgili işlemleri ve kayıtları inceleyin. Beklemek veya yeni anahtar üretmek, belirsiz işlemi yeniden başlatma izni vermez.

Cevaptaki işlem makbuzu

Korunan işlemlerin sonuçlarında operation, birden çok hedefte ayrıca operations bulunur. Fatura eşitlemesi alt belge işlemlerini operationIds içinde de bildirir. İşlem kimliklerini ve iş referansınızı saklayın. Temsilî başarı makbuzu:

{
  "status": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "pos.link",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": { "resultId": "507f1f77bcf86cd799439011" },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-18T09:00:00.000Z",
    "updatedAt": "2026-10-18T09:00:01.000Z"
  }
}

Alan	Tip	Anlamı
`operationId`	string	64 onaltılık karakterli işlem kimliği; belge/kayıt kimliği değildir
`type`	string	İşlem türü; örneğin invoice.import, pos.cancel, earsiv.sign
`state`	string	Aşağıdaki durum tablosundaki değer
`reviewRequired`	boolean	Sonucu kesinleştirmek için inceleme gerekiyor
`retryable`	boolean	Yalnız dış işlem başlamadan başarısızlıkta true olabilir
`result`	object	Mevcutsa resultId, transactionId, uuid, id, providerId, documentId, paymentId, orderId veya uuids gibi güvenli sonuç kimlikleri
`statusUrl`	string	Firma kapsamında okunacak göreli durum adresi
`createdAt`, `updatedAt`	date-time	İşlem kaydının zamanları

result bir mali belge gövdesi değildir. Alanlar işleme göre değişir; bütün sonuç kimliklerinin her makbuzda bulunması beklenmez. Kimliklerin aynı tür veya aynı anlama geldiğini varsaymayın.

Durumlar ve istemci davranışı

Durum	Anlamı	İstemci davranışı
`claimed`	İşlem sahiplenildi; dış etki henüz doğrulanmış değil	Yeni işlem başlatmayın; durumu izleyin
`dispatching`	İşlem başlatıldı; sonuç kesinleşmedi	Yeniden göndermeyin; inceleyin
`provider_accepted`	Sağlayıcı kabulü kaydedildi; yerel tamamlama beklenebilir	Yeniden göndermeyin; durumu izleyin
`succeeded`	İşlem tamamlandı ve makbuz kaydedildi	Sonuç kimliklerini ilgili kaynakla doğrulayın
`rejected`	Sağlayıcının kesin reddi kaydedildi	Hata nedenini giderin; kör tekrar yapmayın
`failed_before_dispatch`	Dış etki başlamadan başarısızlık	`retryable:true` ise aynı iş referansıyla kontrollü tekrar değerlendirilebilir
`review_required`	Dış/yerel sonucun kesinliği yok	Otomatik tekrar yapmayın; belge ve ödeme durumuyla mutabakat yapın

Devam eden veya inceleme gerektiren bir işlemi süre geçtiği için yeniden göndermeyin. 502 UPSTREAM_RESULT_UNCERTAIN mali etkinin oluşmadığı anlamına gelmez. 503 OPERATION_RECORD_UNAVAILABLE durumunda dış çağrının başlayıp başlamadığını yalnız HTTP kodundan çıkarmayın; mevcut operationId ile durumu araştırın. Başlıca hata kodları: IDEMPOTENCY_KEY_REQUIRED, INVALID_OPERATION_TARGET, INVALID_OPERATION_TARGETS, IDEMPOTENCY_PAYLOAD_CONFLICT, OPERATION_IN_PROGRESS, OPERATION_BATCH_CONFLICT, OPERATION_TARGET_LOCKED, OPERATION_REJECTED, UPSTREAM_RESULT_UNCERTAIN, OPERATION_RECORD_UNAVAILABLE.

Durumu okuyun

İşlem durumu referansına gidin.

Mali işlemleri geliştirin

Kaynaklara genel bakış

Entegrasyonu tamamlayın

Mali işlem takibi ve tekrar

İşlem kimliği ve Idempotency-Key

Cevaptaki işlem makbuzu

Durumlar ve istemci davranışı

Durumu okuyun

​İşlem kimliği ve Idempotency-Key

​Cevaptaki işlem makbuzu

​Durumlar ve istemci davranışı

​Durumu okuyun

İşlem kimliği ve Idempotency-Key

Cevaptaki işlem makbuzu

Durumlar ve istemci davranışı

Durumu okuyun