API Entegrasyon & Geliştirici Rehberi

NYW Muhasebe API entegrasyon kılavuzuna hoş geldiniz. Bu RESTful API servisi, kendi ERP yazılımlarınız, e-ticaret altyapılarınız (WooCommerce, Shopify, Trendyol) veya özel veritabanlarınız üzerinden Nywhash Bulut Ön Muhasebe platformuna e-fatura XML ve ZIP arşivlerinizi otomatik olarak aktarmanızı ve mevcut fatura ile cari hesap verilerinizi yönetmenizi sağlar.

Temel API Endpoint Adresi: Bütün API isteklerinizi aşağıdaki adres üzerinden gerçekleştirmelisiniz:
https://muhasebe.nywhash.com/api/v1

Yetkilendirme (Authentication)

API isteklerinizin güvenliği için Nywhash Ön Muhasebe panelindeki Abonelik & Cüzdan sayfasından oluşturduğunuz API anahtarını kullanmanız gerekir.

API anahtarınızı her isteğe başlık (Header) olarak eklemelisiniz:

X-API-KEY: nyw_your_api_key_here

Güvenlik Uyarısı: API anahtarınız (API Key) gizli bir veridir. Hiçbir zaman tarayıcı tarafında (React, Vue, Vanilya JS) doğrudan görüntülemeyin. Her zaman güvenli bir arka uç (Backend) sunucusu üzerinden istek yapın.

Faturaları Listele

Sisteminizde kayıtlı olan tüm gelen (Alış) ve giden (Satış) faturalarını listeler.

GET /invoices

Query Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
limit	integer	İsteğe Bağlı	Sayfa başına dönecek fatura sayısı (Varsayılan: 15, Maksimum: 100)
page	integer	İsteğe Bağlı	Sayfalama için sayfa numarası

Örnek Yanıt (Response)

HTTP 200 OK

{
  "success": true,
  "data": [
    {
      "id": 42,
      "invoice_number": "GIB2026000000123",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "issue_date": "2026-06-15",
      "issue_time": "14:30:00",
      "type_code": "SATIS",
      "currency": "TRY",
      "tax_exclusive_amount": 1000.00,
      "tax_inclusive_amount": 1200.00,
      "payable_amount": 1200.00,
      "customer": {
        "id": 12,
        "name": "Örnek Ltd. Şti.",
        "tax_number": "1234567890"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1
  }
}

Carileri Listele

Sisteminizde kayıtlı olan tüm cari kartları (tedarikçiler ve müşteriler) listeler.

GET /customers

Query Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
limit	integer	İsteğe Bağlı	Sayfa başına dönecek cari sayısı (Varsayılan: 15, Maksimum: 100)
page	integer	İsteğe Bağlı	Sayfalama için sayfa numarası

Örnek Yanıt (Response)

HTTP 200 OK

{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "Örnek Ltd. Şti.",
      "tax_number": "1234567890",
      "created_at": "2026-06-12T14:32:00.000000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1
  }
}

Fatura Aktar (XML/ZIP)

Tekil bir e-Fatura XML dosyasını veya çok sayıda XML içeren bir ZIP arşiv dosyasını API üzerinden doğrudan içeri aktarır. Dosya yükleme isteklerinde `multipart/form-data` şeması kullanılmalıdır.

POST /invoices/import

Post Body Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
file	file	Zorunlu	Fatura XML dosyası veya ZIP arşivi (Maksimum: 50MB)
direction	string	İsteğe Bağlı	Fatura yönü. Değerler: `auto`, `in`, `out` (Varsayılan: `auto`)

İstek Örnekleri (Request Examples)

İstek Örneği (curl)

curl -X POST https://muhasebe.nywhash.com/api/v1/invoices/import \
  -H "X-API-KEY: nyw_your_api_key_here" \
  -F "file=@/path/to/invoice.xml" \
  -F "direction=auto"

İstek Örneği (Node.js Fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('direction', 'auto');

fetch('https://muhasebe.nywhash.com/api/v1/invoices/import', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'nyw_your_api_key_here'
  },
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));