> ## 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.

# Mali işlem takibi ve tekrar

> Idempotency-Key, işlem durumları, tamamlanmış tekrar ve belirsiz sonuçta mutabakat.

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.

```bash theme={null}
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:

```json theme={null}
{
  "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](/api-reference/islem-takibi/muhasip-get-apps-operations-operationid).


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