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

# Cari entegrasyonu

> Cariyi bulun veya oluşturun; belge, ödeme, bakiye ve ekstre ilişkisini kurun.

Cari, alış-satış belgesi ile tahsilat/ödemeyi aynı hesapta ilişkilendirir. Kart oluşturmak tek başına borç, alacak veya açılış bakiyesi oluşturmaz.

## 1. İzinleri ve mevcut cariyi kontrol edin

`muhasip:contacts:read` ve gerektiğinde `muhasip:contacts:write` izinlerini hazırlayın. Ad, kod veya vergi kimliğini `q` ile arayabilirsiniz:

```bash theme={null}
curl 'https://api.muhasip.pro/accounting/contacts?q=C-001&page=1&limit=25' \
  --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET"
```

`q` kısmi aramadır; tekil kayıt garantisi vermez. Sonuçtan doğru cariyi seçin ve `id` değerini kendi sisteminizde eşleyin. Tekrarlanan oluşturmalardan korunmak için kart adını veya vergi kimliğini tekillik anahtarı kabul etmeyin.

## 2. Gerekirse cari oluşturun

```json theme={null}
{
  "name": "Örnek Müşteri",
  "code": "C-001",
  "type": "company",
  "isCustomer": true,
  "countryCode": "TR"
}
```

Bu gövdeyi `POST /accounting/contacts` çağrısında kalıcı `Idempotency-Key` ile gönderin. `name` zorunlu; vergi kimliği isteğe bağlıdır. `type=company|person` ve `isCustomer` kart sınıflamasıdır; aynı cariyle satış ve alış yapılabilir.

Oluşturma cevabındaki `result.id`, `version` ve `operation.operationId` değerlerini saklayın. Aynı iş anahtarıyla tamamlanmış tekrarda ayrıntı yerine sonuç kimliği gelir; [cari ayrıntısını](https://docs.muhasip.pro/api-reference/cari/accounting-contacts-detail.md) yeniden okuyun.

## 3. Belge ve ödemeyi bağlayın

* Satış/alış belgesinde `contactId` bu cari kimliğidir. [Alış-satış rehberi](https://docs.muhasip.pro/rehberler/alis-satis-entegrasyonu.md)
* Tahsilat/verilen ödemede aynı `contactId` kullanılır. Mahsuplaşmadaki belgelerin carisi, yönü, para birimi ve kuru uyuşmalıdır. [Ödeme rehberi](https://docs.muhasip.pro/rehberler/odeme-ve-mahsuplasma.md)
* Kart güncellemesi mali hareketleri veya ödeme dağılımını değiştirmez.

## 4. Bakiye ve ekstreyi okuyun

`GET /accounting/contacts/{id}/balance` para birimi bakiyeleri ile TRY karşılığını döndürür. `GET /accounting/contacts/{id}/statement?from=2026-10-01&to=2026-10-31` belge ve ödeme hareketlerini getirir.

240 TRY satış ve 100 TRY tahsilat sonucunda cari alacağı 140 TRY olur. Ödeme henüz belirli bir belgeye mahsup edilmemiş olsa da cari bakiyesine etki eder. Belgenin açık tutarı ise yalnız belgeye yapılan mahsuplaşmayla azalır. Cari bakiyesiyle tek bir belgenin açık tutarını eşitlemeyin.

## 5. Kartı düzeltin, arşivleyin veya silin

Önce ayrıntıdan güncel `version` değerini okuyun. `PATCH /accounting/contacts/{id}` yalnız gönderdiğiniz alanları değiştirir; `Idempotency-Key` ve `If-Match` zorunludur.

Arşiv için hem yerel para hem TRY bakiyeleri sıfır olmalıdır. `POST .../{id}/archive` kartı aktif listeden kaldırır; `POST .../{id}/restore` yeniden açar. Arşivleme geçmişi silmez. Arşivli kartla yeni belge veya ödeme oluşturulamaz.

Kalıcı `DELETE` yalnız hiçbir belge/ödeme hareketi olmayan, varsayılan olmayan kartta kullanılabilir. Geçmiş hareketi olan sıfır bakiyeli cari silinemez. Varsayılan cariler bu uçlardan değiştirilemez.

[Cari oluştur](https://docs.muhasip.pro/api-reference/cari/accounting-contacts-create.md) · [Cari bakiyesi](https://docs.muhasip.pro/api-reference/cari/accounting-contacts-balance.md) · [Cari ekstresi](https://docs.muhasip.pro/api-reference/cari/accounting-contacts-statement.md)


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