Faturalar

Barındırılan ödeme bağlantıları oluşturun. Oluşturun, gönderin veya etkinleştirin, iptal edin ve PDF üretin; alıcılar herkese açık bağlantıyla öder.

10 endpoints

POST/v1/invoicesOptional

Taslak bir fatura oluşturur. lineItems toplamı amountMinor değerine eşit olmalıdır. İsteğe bağlı bir Idempotency-Key başlığını destekler.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`storeId`	string	Zorunlu	Store the invoice belongs to
`customerId`	string	İsteğe Bağlı	Bind the invoice to a customer
`amountMinor`	integer	Zorunlu	Total in kuruş (must equal sum of lineItems)
`currency`	string	Zorunlu	Always "TRY"
`lineItems`	array	Zorunlu	[{name, qty, unitPriceMinor, lineTotalMinor}]
`buyerEmail`	string	İsteğe Bağlı	Required before /send (email delivery)
`buyerName`	string	İsteğe Bağlı	Buyer display name
`dueDate`	string	İsteğe Bağlı	ISO 8601 due date
`expiresAt`	string	İsteğe Bağlı	ISO 8601 link expiry
`notes`	string	İsteğe Bağlı	Free-text note on the invoice

JSONİstek Örneği

{
  "storeId": "sto_5a6b7c8d",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "dueDate": "2026-04-20T12:00:00Z"
}

JSONYanıt Örneği

{
  "id": "inv_7a8b9c0d1e2f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "status": "draft",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ],
  "buyerEmail": "buyer@example.com",
  "url": "https://pay.kvell.group/invoice/aB3xK9mN2pQ7rS1tV5wY8z",
  "createdAt": "2026-04-13T10:00:00Z"
}

GET/v1/invoicesOptional

Keyset sayfalama ile faturaları listeler. Filtreler: storeId, status.

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`storeId`	string	İsteğe Bağlı	Filter by store
`status`	string	İsteğe Bağlı	draft\|sent\|activated\|viewed\|paid\|expired\|cancelled
`limit`	integer	İsteğe Bağlı	Page size
`cursor`	string	İsteğe Bağlı	Opaque keyset cursor

JSONYanıt Örneği

{
  "items": [
    {
      "id": "inv_7a8b9c0d1e2f",
      "storeId": "sto_5a6b7c8d",
      "status": "sent",
      "amountMinor": 50000,
      "currency": "TRY",
      "createdAt": "2026-04-13T10:00:00Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTEzVDEwOjAwOjAwWiJ9"
}

GET/v1/invoices/{id}Optional

Bir faturayı kimliğine göre getirir.

JSONYanıt Örneği

{
  "id": "inv_7a8b9c0d1e2f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "storeId": "sto_5a6b7c8d",
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "status": "sent",
  "amountMinor": 50000,
  "currency": "TRY",
  "buyerEmail": "buyer@example.com",
  "url": "https://pay.kvell.group/invoice/aB3xK9mN2pQ7rS1tV5wY8z",
  "createdAt": "2026-04-13T10:00:00Z",
  "sentAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/sendOptional

Taslak faturayı gönderildi durumuna taşır ve alıcıya herkese açık bağlantıyı e-posta ile iletir. buyerEmail alanını gerektirir.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "sent",
  "sentAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/activateOptional

Taslak faturayı, e-posta göndermeden etkinleştirildi durumuna taşır — herkese açık bağlantıyı kendiniz paylaşırsınız.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "activated",
  "activatedAt": "2026-04-13T10:05:00Z"
}

POST/v1/invoices/{id}/cancelOptional

Nihai durumda olmayan bir faturayı iptal eder.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "id": "inv_7a8b9c0d1e2f",
  "status": "cancelled",
  "cancelledAt": "2026-04-13T11:00:00Z"
}

GET/v1/invoices/{id}/pdfOptional

Faturayı application/pdf formatında akış olarak sunar.

JSONYanıt Örneği

{
  "note": "Streams application/pdf; no JSON body."
}

GET/v1/public/invoices/{hash}Optional

Herkese açık bağlantı üzerinden alıcıya yönelik görüntüleme (publicHash bearer görevi görür; üye işyeri imzası gerekmez). İlk erişimde durum sent/activated → viewed olarak değişir.

JSONYanıt Örneği

{
  "publicHash": "aB3xK9mN2pQ7rS1tV5wY8z",
  "merchantName": "Acme Store",
  "status": "viewed",
  "amountMinor": 50000,
  "currency": "TRY",
  "lineItems": [
    {
      "name": "Monthly subscription",
      "qty": 1,
      "unitPriceMinor": 50000,
      "lineTotalMinor": 50000
    }
  ]
}

POST/v1/public/invoices/{hash}/payOptional

Alıcı "Şimdi öde"ye tıkladığında bu uç nokta tetiklenir: gerektiğinde bir ödeme oturumu oluşturur ve barındırılan ödeme sayfası URL'sini döndürür.

JSONİstek Örneği

{}

JSONYanıt Örneği

{
  "sessionId": "9c1f2a7b-8c9d-0e1f-3f1c-9a2e6b4d4e8a",
  "checkoutUrl": "https://pay.kvell.group/s/9c1f2a7b-8c9d-0e1f-3f1c-9a2e6b4d4e8a",
  "expiresAt": "2026-04-13T11:00:00Z"
}

GET/v1/public/invoices/{hash}/pdfOptional

Alıcıya yönelik PDF (görüntüleme durumunu değiştirmez).

JSONYanıt Örneği

{
  "note": "Streams application/pdf; no JSON body."
}

Kategori Özeti

Toplam Endpoint

Ana Domain

api.pay.kvell.group