Fatura hesabı oluşturma

Panele girmeden, API üzerinden yeni bir fatura hesabı (entegratör / portal bağlantısı) eklemek için bu endpoint kullanılır. Oluşan kaydın id değeri, fatura ve irsaliye isteklerinde invoice_integration_id olarak kullanılır.

Bu uç yalnızca Geliştirici paketlerinde açıktır (bkz. sağlayıcı listesi sayfasındaki uyarı). Ayrıca paketinizdeki fatura entegrasyonu limiti dolmuşsa 422 döner:

{
  "message": "Kullanım planınız dahilinde sadece 1 adet fatura entegrasyonu ekleyebilirsiniz.",
  "errors": { "api_error": ["Kullanım planınız dahilinde sadece 1 adet fatura entegrasyonu ekleyebilirsiniz."] }
}

Akış

1. GET /api/integrations/invoice/providers ile sağlayıcı kimliğini (id) seçin.
2. GET /api/integrations/invoice/providers/{id} ile sağlayıcının beklediği fields şemasını alın.
3. Şemadaki her alanı settings.<key> olarak doldurup bu endpoint'e gönderin.

İstek

POST /api/integrations/invoice
Accept: application/json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

İstek gövdesi

Alan	Tip	Zorunlu	Açıklama
integration_id	string	Evet	Sağlayıcı kimliği; sağlayıcı listesindeki id değerlerinden biri olmalıdır.
name	string	Evet	Hesabın panelde görünecek adı (en fazla 255 karakter).
settings	object	Koşullu	Sağlayıcının fields şeması boş değilse zorunlu. Anahtarlar şemadaki key değerleridir.
is_test	boolean	Hayır	Test hesabı işareti. Varsayılan false.

settings alanları

Doğrulama kuralları seçilen sağlayıcının alan şemasından üretilir:

• required: true olan her alan için settings.<key> zorunludur; hata mesajlarında alanın label değeri kullanılır.
• type: number alanlar sayısal, type: select alanlar options[].value içinden bir değer olmalıdır; diğerleri metindir.
• Şemada olmayan anahtarlar yok sayılır.

Bağlantı testi

Sağlayıcının can_check_connection değeri true ise, alan doğrulaması geçtikten sonra girilen bilgilerle sağlayıcıya bağlanmayı dener. Bağlantı kurulamazsa hesap kaydedilmez ve 422 ile connection anahtarında hata döner:

{
  "message": "Bağlantı başarısız: ...",
  "errors": { "connection": ["Bağlantı başarısız: Kullanıcı adı veya parola hatalı."] }
}

Örnek istekler

💻 cURL

curl -X POST "https://app.faturaentegrator.com/api/integrations/invoice" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "mysoft",
    "name": "Klinik A - Mysoft",
    "settings": {
      "username": "klinik@ornek.com",
      "password": "parola"
    }
  }'

🐘 PHP

<?php
$body = [
    'integration_id' => 'mysoft',
    'name' => 'Klinik A - Mysoft',
    'settings' => [
        'username' => 'klinik@ornek.com',
        'password' => 'parola',
    ],
];
$ch = curl_init('https://app.faturaentegrator.com/api/integrations/invoice');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

🟢 Node.js

const res = await fetch('https://app.faturaentegrator.com/api/integrations/invoice', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integration_id: 'mysoft',
    name: 'Klinik A - Mysoft',
    settings: { username: 'klinik@ornek.com', password: 'parola' },
  }),
});
const data = await res.json();

🐍 Python

import requests
r = requests.post(
    'https://app.faturaentegrator.com/api/integrations/invoice',
    headers={'Accept': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'integration_id': 'mysoft',
        'name': 'Klinik A - Mysoft',
        'settings': {'username': 'klinik@ornek.com', 'password': 'parola'},
    },
)
data = r.json()

Yanıt

Oluşan hesap kaydı data altında döner. Yeni eklenen hesap varsayılan hesap (is_default: true) olur; hesabın önceki varsayılanı otomatik kaldırılır.

{
  "data": {
    "id": 12,
    "name": "Klinik A - Mysoft",
    "invoice_integration": "mysoft",
    "is_default": true,
    "is_test": false,
    "stop_before_formalize": false,
    "sync_incoming_waybills": false,
    "sync_incoming_invoices": false,
    "last_incoming_waybill_sync_at": null,
    "last_incoming_invoice_sync_at": null,
    "created_at": "2026-10-15T09:12:40.000000Z",
    "updated_at": "2026-10-15T09:12:40.000000Z",
    "settings": { "id": 7, "invoice_integration_id": 12 },
    "base": {
      "id": "mysoft",
      "title": "Mysoft",
      "waybillCapabilities": { "incoming": true, "outgoing": true },
      "incomingInvoiceCapability": true,
      "incomingInvoiceResponseCapability": true,
      "returnInvoiceCapability": true,
      "fields": { "...": "..." }
    }
  }
}

Alan	Açıklama
id	Hesap ID'si. Fatura ve irsaliye isteklerinde invoice_integration_id olarak kullanılır.
invoice_integration	Sağlayıcı kimliği (integration_id).
is_default	Panelde varsayılan seçili gelen hesap. API isteklerinde invoice_integration_id yine de açıkça gönderilir; varsayılan hesap otomatik kullanılmaz.
stop_before_formalize	true ise faturalar taslak olarak sağlayıcıya aktarılır, resmileştirme adımı yapılmaz.
sync_incoming_waybills	Gelen irsaliyelerin periyodik aktarımı açık mı (bkz. gelen irsaliyeler).
sync_incoming_invoices	Gelen faturaların periyodik aktarımı açık mı (bkz. gelen faturalar).
settings	Kimlik bilgileri gizlenir; yalnızca id, invoice_integration_id (ve varsa sale_channel_id) döner.
base	Sağlayıcı tanımı (yetenekler, alan listesi vb.).

Gelen fatura / irsaliye aktarımı oluşturma anında kapalıdır; açmak için hesabı güncelleyin.