Tahsilat veya ödeme oluştur

{
  "status": true,
  "replayed": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "payments.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439015"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "updatedAt": "2026-10-19T09:00:01.000Z"
  },
  "operations": [
    {
      "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "type": "payments.create",
      "state": "succeeded",
      "reviewRequired": false,
      "retryable": false,
      "result": {
        "resultId": "507f1f77bcf86cd799439015"
      },
      "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-10-19T09:00:00.000Z",
      "updatedAt": "2026-10-19T09:00:01.000Z"
    }
  ],
  "resultId": "507f1f77bcf86cd799439015"
}

{
  "status": true,
  "result": {
    "id": "507f1f77bcf86cd799439015",
    "version": 0,
    "contactId": "507f1f77bcf86cd799439011",
    "accountId": "507f1f77bcf86cd799439012",
    "direction": "collection",
    "paymentDate": "2026-10-19",
    "currencyCode": "TRY",
    "exchangeRate": 1,
    "amount": 100,
    "baseCurrencyCode": "TRY",
    "baseAmount": 100,
    "description": "",
    "receiptNumber": "",
    "allocations": [
      {
        "invoiceId": "507f1f77bcf86cd799439014",
        "amount": 100,
        "baseAmount": 100
      }
    ],
    "allocatedAmount": 100,
    "unallocatedAmount": 0,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "payments.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439015"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "updatedAt": "2026-10-19T09:00:01.000Z"
  }
}

{
  "status": false,
  "code": "INVALID_REQUEST",
  "message": "Alan, tarih, hassasiyet, gövde veya başlık geçersiz."
}

{
  "status": false,
  "code": "UNAUTHORIZED",
  "message": "API kimlik bilgileri doğrulanamadı."
}

{
  "status": false,
  "message": "Ürün, IP, modül izni veya kaynak kapsamı uygun değil."
}

{
  "status": false
}

{
  "status": false,
  "code": "RECORD_CHANGED",
  "message": "İlişki, bakiye, kur, sürüm veya işlem kilidi çakışması. İlgili kaydı ve işlem durumunu okuyun."
}

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

{
  "status": false,
  "message": "Üzgünüz, bir hata oluştu."
}

{
  "status": false,
  "code": "UPSTREAM_RESULT_UNCERTAIN",
  "message": "Mali sonuç kesinleştirilemedi. İşlemi tekrar göndermeden operation durumunu ve ilgili kayıtları inceleyin."
}

{
  "status": false,
  "code": "OPERATION_RECORD_UNAVAILABLE",
  "message": "İşlem makbuzu oluşturulamadı veya kesinleştirilemedi. Yeniden göndermeden durumunu okuyun."
}

POST

https://api.muhasip.pro

accounting

payments

{
  "status": true,
  "replayed": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "payments.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439015"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "updatedAt": "2026-10-19T09:00:01.000Z"
  },
  "operations": [
    {
      "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "type": "payments.create",
      "state": "succeeded",
      "reviewRequired": false,
      "retryable": false,
      "result": {
        "resultId": "507f1f77bcf86cd799439015"
      },
      "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-10-19T09:00:00.000Z",
      "updatedAt": "2026-10-19T09:00:01.000Z"
    }
  ],
  "resultId": "507f1f77bcf86cd799439015"
}

{
  "status": true,
  "result": {
    "id": "507f1f77bcf86cd799439015",
    "version": 0,
    "contactId": "507f1f77bcf86cd799439011",
    "accountId": "507f1f77bcf86cd799439012",
    "direction": "collection",
    "paymentDate": "2026-10-19",
    "currencyCode": "TRY",
    "exchangeRate": 1,
    "amount": 100,
    "baseCurrencyCode": "TRY",
    "baseAmount": 100,
    "description": "",
    "receiptNumber": "",
    "allocations": [
      {
        "invoiceId": "507f1f77bcf86cd799439014",
        "amount": 100,
        "baseAmount": 100
      }
    ],
    "allocatedAmount": 100,
    "unallocatedAmount": 0,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "payments.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439015"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "updatedAt": "2026-10-19T09:00:01.000Z"
  }
}

{
  "status": false,
  "code": "INVALID_REQUEST",
  "message": "Alan, tarih, hassasiyet, gövde veya başlık geçersiz."
}

{
  "status": false,
  "code": "UNAUTHORIZED",
  "message": "API kimlik bilgileri doğrulanamadı."
}

{
  "status": false,
  "message": "Ürün, IP, modül izni veya kaynak kapsamı uygun değil."
}

{
  "status": false
}

{
  "status": false,
  "code": "RECORD_CHANGED",
  "message": "İlişki, bakiye, kur, sürüm veya işlem kilidi çakışması. İlgili kaydı ve işlem durumunu okuyun."
}

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

{
  "status": false,
  "message": "Üzgünüz, bir hata oluştu."
}

{
  "status": false,
  "code": "UPSTREAM_RESULT_UNCERTAIN",
  "message": "Mali sonuç kesinleştirilemedi. İşlemi tekrar göndermeden operation durumunu ve ilgili kayıtları inceleyin."
}

{
  "status": false,
  "code": "OPERATION_RECORD_UNAVAILABLE",
  "message": "İşlem makbuzu oluşturulamadı veya kesinleştirilemedi. Yeniden göndermeden durumunu okuyun."
}

Bu çağrı kayıt değiştirir. Idempotency-Key zorunludur. Zaman aşımından sonra yeni anahtarla tekrar başlatmadan işlem durumunu okuyun.

Ne yapar?

collection tahsilat, disbursement verilen ödeme kaydeder. Gerçek banka/POS para transferi başlatmaz. allocations boşsa avans kalır; doluysa belirtilen belgelere tam/kısmi dağıtılır. Aynı cari, yön, para birimi ve kur zorunludur.

Ön koşullar ve izin

Gereken izin: muhasip:payments:write. Bu kaynak için açık izin tanımlanmalıdır; genel erişim veya yönetici yetkisi bu iznin yerine geçmez. İlişkili bütün kimlikler aynı firma kapsamında olmalıdır. Yeni mali kayıt için kullanılan cari, kasa veya hesap aktif olmalıdır. Ürün/depo kimlikleri verilirse geçerli, aynı firmaya ait ve yeni işlem için aktif olmalıdır. Kimlik ve izinler · Muhasebe veri kuralları

İstek örnekleri

Kimlikleri kendi kayıtlarınızla değiştirin. Yazmada iş niyetine özel anahtarı istekten önce saklayın; örnek anahtarını farklı işler için yeniden kullanmayın. Alan ve cevap tanımları bu sayfanın API referansında yer alır.

curl --request POST 'https://api.muhasip.pro/accounting/payments' \
  --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ORNEK-ACCOUNTINGPAYMENTSCREATE-001' \
  --data '{"contactId":"507f1f77bcf86cd799439011","accountId":"507f1f77bcf86cd799439012","direction":"collection","paymentDate":"2026-10-19","amount":"100.00","allocations":[{"invoiceId":"507f1f77bcf86cd799439014","amount":"100.00"}]}'

<?php
$apiUserId = getenv("MUHASIP_API_USER_ID");
$secret = getenv("MUHASIP_API_SECRET");
if (!$apiUserId || !$secret) {
    throw new RuntimeException("API kimlik bilgileri eksik.");
}
$body = json_decode("{\"contactId\": \"507f1f77bcf86cd799439011\", \"accountId\": \"507f1f77bcf86cd799439012\", \"direction\": \"collection\", \"paymentDate\": \"2026-10-19\", \"amount\": \"100.00\", \"allocations\": [{\"invoiceId\": \"507f1f77bcf86cd799439014\", \"amount\": \"100.00\"}]}", true, 512, JSON_THROW_ON_ERROR);
$curl = curl_init("https://api.muhasip.pro/accounting/payments");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => $apiUserId . ":" . $secret,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Content-Type: application/json",
        "Idempotency-Key: ORNEK-ACCOUNTINGPAYMENTSCREATE-001"
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR)
]);
$response = curl_exec($curl);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($response === false) {
    curl_close($curl);
    throw new RuntimeException("Bağlantı sonucu belirsiz; yazma işlemini yeniden göndermeden durumunu kontrol edin.");
}
curl_close($curl);
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
echo json_encode(["httpStatus" => $httpStatus, "response" => $result], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

async function main() {
  const apiUserId = process.env.MUHASIP_API_USER_ID
  const secret = process.env.MUHASIP_API_SECRET
  if (!apiUserId || !secret) throw new Error("API kimlik bilgileri eksik.")
  const authorization = Buffer.from(`${apiUserId}:${secret}`, "utf8").toString("base64")
  const response = await fetch("https://api.muhasip.pro/accounting/payments", {
    method: "POST",
    headers: {
      Authorization: `Basic ${authorization}`,
      Accept: "application/json",
      "Content-Type": "application/json",
      "Idempotency-Key": "ORNEK-ACCOUNTINGPAYMENTSCREATE-001"
    },
    body: JSON.stringify({
      contactId: "507f1f77bcf86cd799439011",
      accountId: "507f1f77bcf86cd799439012",
      direction: "collection",
      paymentDate: "2026-10-19",
      amount: "100.00",
      allocations: [
        {
          invoiceId: "507f1f77bcf86cd799439014",
          amount: "100.00"
        }
      ]
    }),
    signal: AbortSignal.timeout(30000)
  })
  const result = await response.json()
  console.log({ httpStatus: response.status, response: result })
}
main().catch(() => {
  console.error("İstek tamamlanamadı; yazma sonucunu kontrol etmeden yeniden göndermeyin.")
  process.exitCode = 1
})

Cevabı değerlendirin

Aşağıdaki cevap temsilîdir.

{
  "status": true,
  "result": {
    "id": "507f1f77bcf86cd799439015",
    "version": 0,
    "contactId": "507f1f77bcf86cd799439011",
    "accountId": "507f1f77bcf86cd799439012",
    "direction": "collection",
    "paymentDate": "2026-10-19",
    "currencyCode": "TRY",
    "exchangeRate": 1,
    "amount": 100,
    "baseCurrencyCode": "TRY",
    "baseAmount": 100,
    "description": "",
    "receiptNumber": "",
    "allocations": [
      {
        "invoiceId": "507f1f77bcf86cd799439014",
        "amount": 100,
        "baseAmount": 100
      }
    ],
    "allocatedAmount": 100,
    "unallocatedAmount": 0,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "payments.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439015"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "updatedAt": "2026-10-19T09:00:01.000Z"
  }
}

İlk başarılı çağrı result ile kayıt sonucunu ve operation ile makbuzu döndürür. Aynı iş anahtarıyla tamamlanmış tekrar 200 ve replayed:true döndürür; ilk ayrıntı gövdesi tekrarlanmaz. Sonuç kimliğiyle ilgili okuma ucunu kullanın. reviewRequired:true sonucunu başarılı mali işlem kabul etmeyin.

Hata durumunda

HTTP / kod	İzlenecek adım
`400 INVALID_REQUEST`	Alanları, tarihi, ondalık hassasiyeti ve desteklenmeyen alanları kontrol edin.
`401` / `403`	Kimlik, IP ve açık modül iznini doğrulayın.
`404 RESOURCE_NOT_FOUND`	Kaynağın ve bağlı kimliklerin doğru olduğunu, bu kaynak türünde kullanılabildiğini kontrol edin.
`409 RESOURCE_ARCHIVED`	Yeni işlemden önce kartı arşivden çıkarın.
`409 ACCOUNT_CURRENCY_MISMATCH`	Ödemeyi hesabın para biriminde gönderin.
`400 DUPLICATE_ALLOCATION`	Bir belgeyi listede bir kez gönderin.
`409 ALLOCATION_DIRECTION_MISMATCH`	Tahsilatı satışa, verilen ödemeyi alışa ve aynı cariye bağlayın.
`409 ALLOCATION_CURRENCY_MISMATCH`	Belge ve ödeme para birimini eşleştirin.
`409 ALLOCATION_RATE_MISMATCH`	Kur farkı mahsubu desteklenmez; belge ve ödeme kuru aynı olmalıdır.
`409 ALLOCATION_EXCEEDS_BALANCE`	Belgenin güncel remainingBaseAmount alanını okuyup ayrılacak tutarı azaltın.
`409 ALLOCATION_EXCEEDS_PAYMENT`	Yerel para ve yuvarlanmış TRY dağıtım toplamları ödeme tutarını aşamaz.
`409 IDEMPOTENCY_PAYLOAD_CONFLICT`	Aynı iş anahtarıyla farklı gövde, kimlik veya If-Match göndermeyin. Önce mevcut işlemi inceleyin.
`409 OPERATION_TARGET_LOCKED` / `OPERATION_IN_PROGRESS`	Dönen işlem kimliğini takip edin; beklemek veya anahtarı değiştirmek işlem izni vermez.
`502` / `503`	Otomatik tekrar yapmayın. İşlem durumunu ve kayıtları inceleyin.

Hata yönetimi · İşlem takibi 409 ALLOCATION_ROUNDING_MISMATCH: yerel para ve TRY açık tutarı birlikte kapanmıyor. Mevcut ödeme dağılımlarını inceleyin; yuvarlama farkını fazla tahsilatla kapatmayın.

Sonraki adım

Ödeme ve mahsuplaşma akışını izleyin. Dönen kimlikleri ve version değerini saklayın; mali yazma sonrasında ilgili belge ve cari bakiyesini okuyun.

Yetkilendirmeler

Authorization

string

header

gerekli

Kullanıcı adı apiUserId, parola secretKey. Aktif ve süresi geçmemiş API kullanıcısı ve uygun firma gerekir.

Başlıklar

Idempotency-Key

string

gerekli

Her yeni iş niyeti için kalıcı, farklı anahtar. Aynı anahtar+işlem+firma ve farklı içerik 409 üretir; tamamlanmış tekrar 200 replay makbuzu döner.

Required string length: 1 - 128

Pattern: ^[!-~]+$

Gövde

application/json

allocations gönderilmezse ödeme avans olarak kalır; otomatik mahsuplaşmaz. Aktif nakit/banka hesabı, aynı para birimi ve cari gerekir.

contactId

string

gerekli

24 karakterli kayıt kimliği.

Pattern: ^[a-f0-9A-F]{24}$

accountId

string

gerekli

24 karakterli kayıt kimliği.

Pattern: ^[a-f0-9A-F]{24}$

direction

enum<string>

gerekli

collection tahsilat/kasa girişi, disbursement ödeme/kasa çıkışıdır.

Mevcut seçenekler:

collection,

disbursement

paymentDate

string<date>

gerekli

YYYY-MM-DD; 1900-01-01–2199-12-31. Saat gönderilmez.

amount

gerekli

Pozitif ödeme tutarı; hesabın para biriminde.

Gerekli aralık: 0 < x <= 999999999.99Şunun katı olmalıdır 0.01

currencyCode

enum<string>

İşlem para birimi. Uygulama tutar hassasiyeti bütün bu birimlerde 2 basamaktır.

Mevcut seçenekler:

TRY,

USD,

EUR,

GBP,

CHF,

CAD,

AUD,

JPY,

CNY,

AED,

SAR,

RUB,

DKK,

NOK,

SEK

exchangeRate

1 birim dövizin TRY karşılığı; pozitif, en fazla 6 basamak. TRY için 1; diğer para birimlerinde zorunlu.

Gerekli aralık: 0 < x <= 999999.999999Şunun katı olmalıdır 0.000001

description

string

Maximum string length: 2000

receiptNumber

string

Maximum string length: 100

allocations

object[]

Maximum array length: 100

Show child attributes

Yanıt

Aynı anahtarla daha önce tamamlanan işlem; ilk ayrıntı gövdesi yerine güvenli sonuç kimlikleri.

status

boolean

gerekli

replayed

enum<boolean>

gerekli

Mevcut seçenekler:

true

operation

object

gerekli

Show child attributes

operations

object[]

gerekli

Show child attributes

resultId

string

transactionId

string

uuid

string

providerId

string

documentId

string

paymentId

string

orderId

string

uuids

string[]

sourcePaymentId

string

24 karakterli kayıt kimliği.

Pattern: ^[a-f0-9A-F]{24}$

destinationPaymentId

string

24 karakterli kayıt kimliği.

Pattern: ^[a-f0-9A-F]{24}$

Servis ve uygulamalar

Cari hesaplar

Kasa ve transferler

Alış-satış (e-belgesiz)

Ödemeler ve mahsuplaşma

Muhasebe seçenekleri

Fatura ve e-belge

Banka hesapları ve hareketleri

Banka otomasyonları

İş akışları ve alanlar

POS ve tahsilat

E-Pos

GİB e-Arşiv

Pazaryeri

Online işlemler

Proje ve görevler

Ajanda

Takvim

Mali işlem durumu

Tahsilat veya ödeme oluştur

Ne yapar?

Ön koşullar ve izin

İstek örnekleri

Cevabı değerlendirin

Hata durumunda

Sonraki adım

Yetkilendirmeler

Başlıklar

Gövde

Yanıt

​Ne yapar?

​Ön koşullar ve izin

​İstek örnekleri

​Cevabı değerlendirin

​Hata durumunda

​Sonraki adım

Yetkilendirmeler

Başlıklar

Gövde

Yanıt

Ne yapar?

Ön koşullar ve izin

İstek örnekleri

Cevabı değerlendirin

Hata durumunda

Sonraki adım