argist/laravel-invoice-webhook

Laravel altyapılı sistemlerde oluşturulan fatura ve satış kayıtlarını Argist platformuna güvenli şekilde aktaran, e-Arşiv ve e-Fatura uyumlu webhook entegrasyonu.

v1.0.4 2026-01-10 13:26 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0

MIT

README

Laravel altyapılı sistemlerde oluşturulan fatura ve satış kayıtlarını Argist platformuna güvenli şekilde aktaran, e-Arşiv ve e-Fatura uyumlu webhook entegrasyonu.

Özellikler

• ✅ JWT Token Management - Otomatik token yönetimi ve caching
• ✅ Ayrı Servisler - JWT token servisi ve fatura gönderimi servisleri ayrı çalışır
• ✅ Production Ready - Hata yönetimi, validasyon ve logging
• ✅ Configuration Management - Merkezi yapılandırma dosyası
• ✅ Timeout Protection - HTTP istek timeout'ları
• ✅ Error Handling - Detaylı hata mesajları ve yanıtları

Kurulum

1. Composer ile Yükleme

composer require argist/laravel-invoice-webhook

2. Konfigürasyon Yayınlama

php artisan vendor:publish --provider="Argist\InvoiceWebhook\Providers\InvoiceWebhookServiceProvider" --tag=argist-config

Bu komut, config/argist.php dosyasını projenize kopyalayacaktır.

3. Environment Değişkenlerini Ayarlama

.env dosyasına aşağıdaki değişkenleri ekleyin:

# Argist API Konfigürasyonu
ARGIST_PUBLIC_KEY=your-public-key-here
ARGIST_SECRET_KEY=your-secret-key-here

Kullanım

Fatura Gönderme

Option 1: Direct Service Call

use Argist\InvoiceWebhook\Services\InvoiceApiService;

$invoiceData = [
    'bill_date' => '03/01/2026',
    'bill_time' => '14:30:00',
    'payment_status' => 1,
    'description' => 'Ürün satışı',
    'amount' => 1000,
    'total_tax' => 200,
    'total_amount' => 1200,
    'currency_id' => 1,
    'customer' => [
        'name' => 'Müşteri Adı',
        'email' => '[e-mail]',
        'adress' => 'Adres Bilgisi',
        'tax_office' => 'Vergi Müdürlüğü',
        'tax_number' => '12345678901',
    ],
    'rows' => [
        [
            'title' => 'Ürün Adı',
            'quantity' => 2,
            'amount' => 500,
            'tax_rate' => 20,
            'currency_id' => 1,
            'row_sale_type' => '1',
            'product_id' => null,
            'service_id' => null,
            'quantity_unit_id' => 1,
            'tax_amount' => 200,
            'price_excluding_tax' => 1000,
            'total_amount' => 1200,
            'discount_amount' => 0,
            'discount_rate' => 0,
            'description' => 'Ürün açıklaması',
        ]
    ],
];

$result = InvoiceApiService::sendInvoice($invoiceData);

if ($result['success']) {
    // Fatura başarıyla gönderildi
    $invoiceId = $result['data']['id'] ?? null;
} else {
    // Hata oluştu
    $errorMessage = $result['message'];
    $errors = $result['errors'] ?? [];
}

Option 2: HTTP Request

POST /api/v1/invoice/send HTTP/1.1
Content-Type: application/json

{
  "bill_date": "03/01/2026",
  "bill_time": "14:30:00",
  "payment_status": 1,
  "description": "Ürün satışı",
  "amount": 1000,
  "total_tax": 200,
  "total_amount": 1200,
  "currency_id": 1,
  "customer": {
    "name": "Müşteri Adı",
    "email": "[e-mail]",
    "adress": "Adres Bilgisi",
    "tax_office": "Vergi Müdürlüğü",
    "tax_number": "12345678901"
  },
  "rows": [
    {
      "title": "Ürün Adı",
      "quantity": 2,
      "amount": 500,
      "tax_rate": 20,
      "currency_id": 1,
      "row_sale_type": "1",
      "product_id": null,
      "service_id": null,
      "quantity_unit_id": 1,
      "tax_amount": 200,
      "price_excluding_tax": 1000,
      "total_amount": 1200,
      "discount_amount": 0,
      "discount_rate": 0,
      "description": "Ürün açıklaması"
    }
  ]
}

Test Endpoint

Sistem kurulumunu test etmek için:

GET /api/v1/invoice/test HTTP/1.1

Response Format

Success Response (200):

{
  "success": true,
  "status": 200,
  "data": {
    "id": "bill_123456",
    "status": "created"
  }
}

Validation Error (422):

{
  "success": false,
  "status": 422,
  "message": "Fatura gönderimi başarısız",
  "errors": {
    "bill_date": ["Bill date is required"],
    "customer": ["Customer information is invalid"]
  }
}

Server Error (500):

{
  "success": false,
  "status": 500,
  "message": "Gerekli alan eksik: bill_date",
  "errors": []
}

Servis Mimarisi

JwtTokenService

JWT token almandan sorumludur.

Özellikler:

• Token caching (50 dakika)
• Otomatik yenileme
• Error handling

Kullanım:

use Argist\InvoiceWebhook\Services\JwtTokenService;

$tokenService = new JwtTokenService();

// Token al (cache'den ya da API'den)
$token = $tokenService->getToken();

// Cache'i temizle
$tokenService->clearCache();

InvoiceApiService

Fatura gönderme işleminden sorumludur.

Özellikler:

• Veri validasyonu
• JWT token integration
• Response handling
• Error formatting

Metotlar:

// Fatura gönder
InvoiceApiService::sendInvoice(array $invoiceData): array

Hata Yönetimi

Paket tüm hataları yapılandırılmış bir array formatında döndürür:

[
    'success' => bool,
    'status' => int (HTTP status code),
    'message' => string,
    'errors' => array (validation errors if any)
]

Olası Hatalar

Durum	Status	Sebep
JWT Token Hatası	401	API anahtarları yanlış ya da yapılandırılmamış
Validasyon Hatası	422	Gerekli alanlar eksik veya yanlış format
Server Hatası	500	Bağlantı sorunu veya API hatası

Gelişmiş Ayarlar

Timeout Ayarı

ARGIST_API_TIMEOUT=30  # Saniye cinsinden

Custom API Domain

ARGIST_API_DOMAIN=https://custom-api.argist.com

Custom Bill Endpoint

ARGIST_BILL_ENDPOINT=/api/v1/custom/bill/create

Logging

Paket tüm istekleri Laravel logging sistemi ile kaydeder. config/logging.php dosyanızda loglama seviyesini ayarlayabilirsiniz.

Testing

Test endpointini kullanarak sistem kurulumunu doğrulayın:

curl http://localhost:8000/api/v1/invoice/test

Security Best Practices

1. ✅ Environment değişkenlerinde API anahtarlarını saklayın
2. ✅ Production ortamında HTTPS kullanın
3. ✅ API istieyim rate limiting ile koruyun
4. ✅ İstekleri düzenli olarak izleyin ve logları kontrol edin

Teknik Detaylar

Token Caching

• Cache Duration: 50 dakika
• Cache Driver: Laravel cache (default)
• Otomatik Yenileme: Token süresi dolunca otomatik yenilenir

Timeout Settings

• JWT Token Request: 10 saniye
• Bill Sending Request: 30 saniye

Validation

Tüm gerekli alanlar kontrol edilir:

• bill_date
• bill_time
• payment_status
• amount
• total_tax
• total_amount
• currency_id
• customer (array)
• rows (array)

Troubleshooting

"Argist API anahtarları yapılandırılmadı"

Çözüm: .env dosyasında ARGIST_PUBLIC_KEY ve ARGIST_SECRET_KEY ayarlandığından emin olun.

"Token alma işlemi başarısız"

Çözüm:

• API anahtarlarının doğru olduğundan emin olun
• Ağ bağlantısını kontrol edin
• API'nin çalışır durumda olduğundan emin olun

"Gerekli alan eksik"

Çözüm: Tüm gerekli alanları request'e ekleyin. Kullanım bölümü referans alın.

Contributions

Katkılarınız hoşgeldiniz! Lütfen pull request gönderin.

License

MIT License. Detaylar için LICENSE.md dosyasına bakın.

Support

Sorular veya sorunlar için lütfen GitHub issues açın.