Cari oluştur

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

{
  "status": true,
  "result": {
    "id": "507f1f77bcf86cd799439011",
    "version": 0,
    "name": "Örnek Müşteri",
    "code": "C-001",
    "type": "company",
    "isCustomer": true,
    "phone": "",
    "email": "",
    "taxId": "",
    "taxOffice": "",
    "countryCode": "TR",
    "country": "Türkiye",
    "stateCode": "",
    "state": "",
    "city": "",
    "address": "",
    "isAbroad": false,
    "archived": false,
    "isDefault": false,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "contacts.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439011"
    },
    "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

contacts

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

{
  "status": true,
  "result": {
    "id": "507f1f77bcf86cd799439011",
    "version": 0,
    "name": "Örnek Müşteri",
    "code": "C-001",
    "type": "company",
    "isCustomer": true,
    "phone": "",
    "email": "",
    "taxId": "",
    "taxOffice": "",
    "countryCode": "TR",
    "country": "Türkiye",
    "stateCode": "",
    "state": "",
    "city": "",
    "address": "",
    "isAbroad": false,
    "archived": false,
    "isDefault": false,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "contacts.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439011"
    },
    "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?

Tek bir cari oluşturur. Para, açılış, ürün veya ödeme kaydı oluşturmaz. Vergi kimliği zorunlu değildir; verilirse 10/11 rakam olmalıdır.

Ön koşullar ve izin

Gereken izin: muhasip:contacts: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/contacts' \
  --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ORNEK-ACCOUNTINGCONTACTSCREATE-001' \
  --data '{"name":"Örnek Müşteri","code":"C-001"}'

<?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("{\"name\": \"Örnek Müşteri\", \"code\": \"C-001\"}", true, 512, JSON_THROW_ON_ERROR);
$curl = curl_init("https://api.muhasip.pro/accounting/contacts");
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-ACCOUNTINGCONTACTSCREATE-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/contacts", {
    method: "POST",
    headers: {
      Authorization: `Basic ${authorization}`,
      Accept: "application/json",
      "Content-Type": "application/json",
      "Idempotency-Key": "ORNEK-ACCOUNTINGCONTACTSCREATE-001"
    },
    body: JSON.stringify({
      name: "Örnek Müşteri",
      code: "C-001"
    }),
    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": "507f1f77bcf86cd799439011",
    "version": 0,
    "name": "Örnek Müşteri",
    "code": "C-001",
    "type": "company",
    "isCustomer": true,
    "phone": "",
    "email": "",
    "taxId": "",
    "taxOffice": "",
    "countryCode": "TR",
    "country": "Türkiye",
    "stateCode": "",
    "state": "",
    "city": "",
    "address": "",
    "isAbroad": false,
    "archived": false,
    "isDefault": false,
    "createdAt": "2026-10-19T09:00:00.000Z"
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "contacts.create",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "507f1f77bcf86cd799439011"
    },
    "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 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

Sonraki adım

Cari entegrasyonunu tamamlayın. Mali sonucu bakiye ve ekstre okumalarıyla kontrol edin.

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

name

string

gerekli

Cari unvanı veya adı.

Required string length: 1 - 250

code

string

Cari kodu.

Maximum string length: 150

type

enum<string>

Varsayılan company.

Mevcut seçenekler:

company,

person

isCustomer

boolean

Varsayılan true; müşteri/tedarikçi sınıflaması, işlem yönünü zorlamaz.

phone

string

Maximum string length: 150

string

Boş veya geçerli e-posta.

Maximum string length: 150

taxId

string

Boş veya 10/11 rakam; yabancı caride boş bırakılabilir.

Pattern: ^(?:|[0-9]{10,11})$

taxOffice

string

Maximum string length: 150

countryCode

string

Varsayılan TR.

Pattern: ^[A-Z]{2}$

country

string

Maximum string length: 150

stateCode

string

Maximum string length: 150

state

string

Maximum string length: 150

city

string

Maximum string length: 150

address

string

Maximum string length: 2000

isAbroad

boolean

Varsayılan false.

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

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