Paraşüt API ile Alış Faturası, Maaş, Vergi ve Banka Gideri Kaydı

Gider tarafında hangi kaynak ne işe yarar?

Paraşüt arayüzünde "Giderler" menüsünde gördüğünüz kayıtlar API'de ayrı kaynaklara karşılık gelir. Resmi sözlükteki eşleşme şöyledir:

Tüm isteklerde taban adres https://api.parasut.com/v4/{company_id}/, başlıklar ise Authorization: Bearer <ACCESS_TOKEN> ve Content-Type: application/vnd.api+json (veya application/json) şeklindedir. İlişkilerdeki id değerleri string, yol parametreleri integer olarak gönderilir. Bu kuralların ayrıntısı filtreleme, sayfalama ve include yazısında var.

Alış faturası: basic ve detaylı fiş farkı

Alış faturası için tek bir uç nokta vardır: POST /{company_id}/purchase_bills. Dokümantasyon bu işlemi iki ayrı gövde biçimiyle gösterir ve bunları #basic ile #detailed ekleriyle ayırır. Bu ekler yalnızca belgedeki başlıklardır; gerçek istekte URL'ye yazılmaz. Paraşüt'ün kurallarına göre gövdede relationships.details varsa detaylı (kalemli), yoksa basic (kalemsiz) fiş oluşur ve tür sonradan değiştirilemez.

item_type oluştururken purchase_bill ya da refund (iade) değerlerinden birini alır. invoice_no alanına tedarikçinin fatura numarasını yazabilirsiniz. Ortak ilişkiler supplier (contacts), paid_by_employee (employees), category (item_categories) ve tags'tir. Tedarikçi carisini önceden oluşturmanız gerekir; bunun için cari hesap oluşturma yazısına bakın.

Basic fiş örneği

curl -X POST "https://api.parasut.com/v4/$COMPANY_ID/purchase_bills" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "purchase_bills",
      "attributes": {
        "item_type": "purchase_bill",
        "description": "Ekim ayı ofis kirası",
        "issue_date": "2026-10-23",
        "due_date": "2026-11-22",
        "invoice_no": "ABC2026000000123",
        "currency": "TRL",
        "net_total": 1200,
        "total_vat": 200
      },
      "relationships": {
        "supplier": { "data": { "type": "contacts", "id": "SUPPLIER_ID" } },
        "category": { "data": { "type": "item_categories", "id": "CATEGORY_ID" } }
      }
    }
  }'

Detaylı (kalemli) fiş örneği

Detaylı fişte toplamları siz göndermezsiniz; kalemlerden hesaplanır. Kalemlerin data.type değeri purchase_bill_details'tir ve yeni kalemlerin id'si boş bırakılır. Kalemde ayrıca vat_withholding_rate, discount_type / discount_value, excise_duty_type / excise_duty_value, communications_tax_rate ve description gönderilebilir. Kalemdeki net_total ve vat_withholding salt okunurdur.

{
  "data": {
    "type": "purchase_bills",
    "attributes": {
      "item_type": "purchase_bill",
      "issue_date": "2026-10-23",
      "due_date": "2026-11-22",
      "invoice_no": "ABC2026000000124",
      "currency": "TRL"
    },
    "relationships": {
      "supplier": { "data": { "type": "contacts", "id": "SUPPLIER_ID" } },
      "details": {
        "data": [
          {
            "type": "purchase_bill_details",
            "attributes": { "quantity": 2, "unit_price": 500, "vat_rate": 20 },
            "relationships": {
              "product": { "data": { "type": "products", "id": "PRODUCT_ID" } },
              "warehouse": { "data": { "type": "warehouses", "id": "WAREHOUSE_ID" } }
            }
          }
        ]
      }
    }
  }
}

Başarılı istek 201 ile oluşan PurchaseBill kaydını döner. Ürün ve depo kayıtlarını hazırlamak için ürün, stok ve depo yönetimi yazısına bakabilirsiniz.

Okuma, listeleme ve include

GET /{company_id}/purchase_bills listesi şu filtreleri kabul eder: filter[issue_date], filter[due_date], filter[supplier_id], filter[item_type] (purchase_bill, refund, cancelled) ve filter[spender_id]. Sıralama için id, issue_date, due_date, remaining, remaining_in_trl kullanılabilir. Sayfa boyutu varsayılan 15, en fazla 25'tir.

Geçerli include değerleri: category, spender, details, details.product, details.warehouse, payments, payments.transaction, tags, recurrence_plan, active_e_document, pay_to. Resmi kurallar özellikle uyarır: purchase_bills için supplier geçerli bir include değeri değildir. Kalemleri ayrıca GET /purchase_bills/{id}/details ile çekebilirsiniz; bu uç sayfalanmaz ve include almaz.

curl "https://api.parasut.com/v4/$COMPANY_ID/purchase_bills?filter[supplier_id]=123&sort=-issue_date&page[size]=25&include=category,payments" \
  -H "Authorization: Bearer $PARASUT_TOKEN" -H "Accept: application/json"

Alış faturasını ödemek

Fişin ödemesi POST /{company_id}/purchase_bills/{id}/payments ile girilir. Gövde, satış faturası tahsilatıyla aynı PaymentFormAttributes şemasını kullanır ve data.type değeri payments'tir.

curl -X POST "https://api.parasut.com/v4/$COMPANY_ID/purchase_bills/$BILL_ID/payments?include=transaction" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"payments","attributes":{
        "account_id": 456, "date": "2026-11-20", "amount": 1400, "description": "Havale ile ödendi"
      }}}'

Yanıt 201 ile Payment kaydını döner. Her ödeme, faturayı kapatan bir işleme (transaction) bağlıdır; ödemeleri GET /purchase_bills/{id}/payments?include=transaction ile listeleyebilirsiniz (bu listede page[size] en fazla 10000). Paraşüt'ün kuralları satış tahsilatını geri almak için işlemin DELETE /{company_id}/transactions/{id} ile silinmesini tarif eder. Tahsilat tarafının tamamı tahsilat ve ödeme kaydı yazısında anlatılıyor.

İptal, arşiv ve silme

• DELETE /purchase_bills/{id}/cancel: fişi iptal eder ve 200 ile kaydı döner.
• PATCH /purchase_bills/{id}/mark_as_cancelled: aynı iptali zorunlu note alanıyla yapar; fişe ait ödemeler silinir. Zaten iptal, arşivli, iadesi olan veya tedarikçisi olmayan kayıtlarda 422 döner.
• PATCH /purchase_bills/{id}/recover: iptali geri alır.
• PATCH .../archive ve PATCH .../unarchive: arşive alır veya çıkarır.
• DELETE /purchase_bills/{id}: kaydı siler, 204 döner.
• PUT /purchase_bills/{id}: günceller; gövde oluşturmadaki basic veya detaylı biçimle aynıdır.

Gelen bir e-Faturadan fiş oluşturmak için POST /{company_id}/e_invoices/{id}/create_purchase_bill kullanılır. Bu uçta gövde JSON:API değil, düz JSON'dur (details, supplier, warehouse) ve aynı e-Fatura için ikinci çağrı 422 döner. Yanlışlıkla oluşan fişi silip e-Faturayı bekleyenlere geri göndermek için PATCH /purchase_bills/{id}/move_to_awaiting_e_invoices vardır. e-belge tarafının ayrıntıları e-Fatura ve e-Arşiv yazısında.

Banka gideri, maaş ve vergi kayıtları

Bu üç kaynak birbirine çok benzer: kayıt bir borç doğurur, ardından ayrı bir istekle ödenir. Oluşturma gövdelerindeki zorunlu alanlar şöyledir:

Dikkat edilecek iki ayrıntı var. Birincisi, taxes oluşturma gövdesinde currency alanı tanımlı değildir. İkincisi, belgede bank_fees için bir liste (index) uç noktası yoktur; yalnızca oluşturma, tekil okuma, düzenleme, silme, arşiv ve ödeme uçları tanımlıdır. Banka giderlerinin ID'lerini kendi tarafınızda saklamanız gerekir. salaries ve taxes listeleri ise filter[due_date], filter[issue_date], filter[currency] ve filter[remaining] filtrelerini alır.

curl -X POST "https://api.parasut.com/v4/$COMPANY_ID/salaries" \
  -H "Authorization: Bearer $PARASUT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "salaries",
      "attributes": {
        "description": "Ekim 2026 maaşı",
        "currency": "TRL",
        "issue_date": "2026-10-31",
        "due_date": "2026-11-05",
        "net_total": 30000
      },
      "relationships": {
        "employee": { "data": { "type": "employees", "id": "EMPLOYEE_ID" } }
      }
    }
  }'

Ödeme uçları POST /bank_fees/{id}/payments, POST /salaries/{id}/payments ve POST /taxes/{id}/payments'tir; gövdeleri alış faturası ödemesiyle aynıdır (payments tipi, account_id, date, amount, description, exchange_rate). Salt okunur total_paid, remaining, remaining_in_trl ve archived alanlarını gönderemezsiniz.

Çalışan kaydı ve çalışana ödeme

Maaşı bir kişiye bağlamak için önce çalışan kaydı gerekir. POST /{company_id}/employees gövdesinde tek zorunlu alan name'dir; email, iban, archived ve category ilişkisi isteğe bağlıdır. Bakiye alanları (balance, trl_balance, usd_balance, eur_balance, gbp_balance) salt okunurdur. Liste filter[name] ve filter[email] ile aranabilir.

{
  "data": {
    "type": "employees",
    "attributes": { "name": "Ayşe Yılmaz", "email": "ayse@example.com", "iban": "TR000000000000000000000000" }
  }
}

Maaşları tek tek ödemek yerine çalışana toplu ödeme de girebilirsiniz: POST /{company_id}/employees/{id}/employee_debit_transactions. Burada data.type transactions'tır ve ödeme alanlarına ek olarak payable_ids (öncelikli eşleşecek maaş ve masraf fişi ID'leri) gönderilir. Belgeye göre banka entegrasyonu olan hesaplar kullanılamaz (400) ve TL dışı hesaplarda exchange_rate ya da target_amount zorunludur (422 "Döviz kuru doldurulmalı"). Çalışanın hareketleri GET /employees/{employee_id}/transaction_history_items, bakiye özeti GET /employees/{employee_id}/balance_info ile okunur.

Alış faturasındaki paid_by_employee ilişkisi ise bir gideri kaydederken ilgili çalışanı fişe bağlamanızı sağlar.

Node.js ile basit bir gider kaydı fonksiyonu

Aşağıdaki TypeScript örneği Paraşüt'ün resmi örnek uygulamasındaki yaklaşımı (Bearer token, JSON gövde, 429'da bekleyip tekrar) sadeleştirir. Token yenileme mantığını OAuth2 yazısındaki gibi tek noktada tutun; gizli bilgileri .env dosyasında saklayın.

const BASE = 'https://api.parasut.com/v4';
const COMPANY_ID = process.env.PARASUT_COMPANY_ID;

async function parasut(path: string, method: string, body: unknown, token: string) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(`${BASE}/${COMPANY_ID}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json',
        Accept: 'application/json',
      },
      body: JSON.stringify(body),
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get('retry-after')) || 10;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const json = await res.json().catch(() => undefined);
    if (!res.ok) throw new Error(`${res.status} ${JSON.stringify(json?.errors)}`);
    return json;
  }
  throw new Error('429: deneme hakkı bitti');
}

export async function createBankFee(token: string, amount: number, date: string) {
  return parasut('/bank_fees', 'POST', {
    data: {
      type: 'bank_fees',
      attributes: {
        description: 'EFT masrafı',
        currency: 'TRL',
        issue_date: date,
        due_date: date,
        net_total: amount,
      },
    },
  }, token);
}

Webhook ile gider kayıtlarını izlemek

Paraşüt, purchase_bill modeli için create ve update olaylarını gönderir; delete olayı yoktur. Gelen bir e-Faturaya bağlı fişler ve tekrarlayan fiş şablonları (recurring_purchase_bill) için bu olaylar gönderilmez; gelen e-Faturalar inbound_e_invoice olayıyla izlenir. Banka gideri, maaş ve vergi için webhook olayı belgelenmemiştir; bunları zamanlanmış bir eşitleme ile takip edin. Kurulum için Paraşüt webhook kurulumu yazısına, zamanlama için cron job rehberine bakabilirsiniz.

Sık Sorulan Sorular

Basic ve detaylı fiş için farklı URL mi kullanmalıyım?

Hayır. İkisi de POST /{company_id}/purchase_bills adresine gider. #basic ve #detailed yalnızca dokümantasyondaki ayrımdır. Gövdede relationships.details varsa detaylı fiş oluşur ve bu tür sonradan değişmez.

Tedarikçi bilgisini include ile neden alamıyorum?

purchase_bills için geçerli include listesinde supplier yoktur; resmi kurallar bunu ayrıca uyarır. Listede spender ve pay_to gibi değerler vardır. Tedarikçiyi filtrelemek için filter[supplier_id] kullanın.

Vergi kaydında para birimi gönderebilir miyim?

taxes oluşturma gövdesinde currency alanı tanımlı değildir; zorunlu alanlar description, issue_date, due_date ve net_total'dir. Banka gideri ve maaşta ise currency zorunludur.

Hangi gideri hangi belgeyle kaydetmem gerektiğini API söyler mi?

Hayır. API yalnızca kaydı tutar. Bir giderin fiş, fatura veya vergi olarak nasıl muhasebeleşeceğini mali müşavirinizle belirleyin. e-belge yükümlülükleri için e-Arşiv ve e-Fatura zorunluluğu yazısına bakabilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Paraşüt entegrasyonu genel rehberi · Paraşüt API tahsilat ve ödeme · Paraşüt API cari hesap · Paraşüt API dövizli fatura · Paraşüt webhook kurulumu · Luca entegrasyonu rehberi