Ana içeriğe geç

Hızlı Başlangıç

Bir siparişi satışa çevirip faturasını keseceğiz. Tamamı sandbox'ta, gerçek bir belge oluşmadan.

1. Anahtar alın​

sandbox-app.finansfatura.com üzerinde bir mükellef hesabıyla giriş yapın, Ayarlar → API Anahtarları'ndan yeni anahtar üretin.

Anahtarın açık hâli yalnızca bir kez gösterilir — kopyalayın.

export FF_KEY="ff_test_xxxxxxxxxxxxxxxxxxxx"
export FF_URL="https://sandbox-api.finansfatura.com"

2. Satışı oluşturun​

curl -X POST "$FF_URL/v1/integrations/orders" \
  -H "X-Api-Key: $FF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ECOMSOFT",
    "external_id": "TEST-001",
    "order_number": "001",
    "payment_status": "PAID",
    "currency": "TRY",
    "total_price": 1200,
    "buyer": {
      "title": "Test Müşteri",
      "tckn": "11111111111",
      "email": "[email protected]",
      "address": "Kadıköy / İstanbul"
    },
    "lines": [{
      "sku": "SRV-001",
      "title": "Danışmanlık hizmeti",
      "quantity": 1,
      "unit_price": 1200,
      "total_price": 1200,
      "vat_rate": 20
    }]
  }'
{
  "imported": true,
  "already_imported": false,
  "integration_id": 42,
  "external_id": "TEST-001",
  "transaction_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
}

Satış artık mükellefin panelinde Satışlar listesinde görünüyor. Gönderdiğiniz "Test Müşteri" satışın fatura alıcısı olarak üzerine yazıldı; fatura kesilirken alıcı buradan kurulur, mükellefin elle girmesi gerekmez. Cari kartı açılmaz (neden).

buyer göndermezseniz ya da içinde title (veya contact_name) yoksa istek 400 döner; satış oluşmaz.

Fiyatlar KDV dahil

Bu uçta 1200 yazdık — 1000 TL mal bedeli + 200 TL KDV. Bir sonraki adımda fatura ucu KDV'yi ayrı ister; dikkat edin.

3. Faturayı kesin​

transaction_id'yi transaction_header_id olarak geçiriyoruz — bu alan zorunludur, satışa bağlanmamış belge kabul edilmez (tek istisna IADE).

curl -X POST "$FF_URL/v1/invoicing/invoices/" \
  -H "X-Api-Key: $FF_KEY" \
  -H "Idempotency-Key: TEST-001" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "EARSIV",
    "transaction_header_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "canonical": {
      "Currency": "TRY",
      "RecipientAlias": "",
      "Recipient": { "VKNorTCKN": "11111111111", "Title": "Test Müşteri" },
      "Lines": [{
        "Title": "Danışmanlık hizmeti",
        "ProductCode": "SRV-001",
        "Quantity": 1,
        "UnitPrice": 1000,
        "LineTotal": 1000,
        "UnitCode": "C62",
        "VatRate": 0.2
      }],
      "Totals": {
        "SubtotalExclVAT": 1000,
        "VatTotal": 200,
        "DiscountTotal": 0,
        "GrandTotal": 1200
      }
    }
  }'
{
  "invoice_id": "3b7e1a90-...",
  "status": "QUEUED",
  "ettn": "8f2c...",
  "pdf_url": "https://..."
}

Dikkat edin: fatura gövdesinde tutarlar KDV hariç (1000) ve VatRate oran (0.2). Satış gövdesinde ise KDV dahil (1200) ve yüzde (20) idi.

4. Durumu izleyin​

curl "$FF_URL/v1/integrations/ecomsoft/orders/status?external_ids=TEST-001" \
  -H "X-Api-Key: $FF_KEY"
{
  "statuses": [{
    "external_id": "TEST-001",
    "transaction_id": "9f1c2d3e-...",
    "invoice_status": "ACCEPTED",
    "invoice_number": "FF12026000000001",
    "pdf_url": "https://..."
  }]
}

Fatura numarası burada dolar — kesim yanıtında henüz yoktu.

Sonraki adımlar​

  • Her sipariş için external_id ve Idempotency-Key kullanın; retry'larınız güvenli olur
  • Faturayı siz kesmek zorunda değilsiniz; 3. adımı atlarsanız mükellef panelden toplu faturalandırır
  • Ayrıntılar için Satış Oluştur ve Fatura Kes
  • Dövizli satış, KDV istisnası, tevkifat, özel matrah ya da iade kesiyorsanız Örnek Senaryolar her birini uçtan uca gösteriyor
  • Hata durumları için Hata Kodları
  • Python / Node / PHP yazıyorsanız aynı akışı istemci kütüphaneleriyle birkaç satırda kurabilirsiniz