README

Laravel 13+ projeleri için Paraşüt API V4 entegrasyon paketidir. İlk odak satış faturası, e-Arşiv ve e-Fatura akışlarıdır.

Kurulum

composer require hakanispirli/parasut-laravel

Config dosyasını yayınlayın:

php artisan vendor:publish --tag=parasut-config

Konfigürasyon

.env dosyanıza gerekli değerleri ekleyin:

PARASUT_BASE_URL=https://api.parasut.com/v4
PARASUT_OAUTH_BASE_URL=https://api.parasut.com
PARASUT_CLIENT_ID=
PARASUT_CLIENT_SECRET=
PARASUT_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob
PARASUT_DEFAULT_COMPANY_ID=
PARASUT_TIMEOUT=20
PARASUT_RETRY_TIMES=2
PARASUT_RETRY_SLEEP_MS=250
PARASUT_LOG_REQUESTS=false

OAuth bilgilerini, access token veya refresh token değerlerini asla repoya commit etmeyin.

Hızlı Başlangıç

İhtiyacınız olan servisi Laravel container üzerinden inject edin:

use HakanIspirli\ParasutLaravel\Contracts\SalesInvoicesServiceContract;

final readonly class InvoiceController
{
    public function __construct(
        private SalesInvoicesServiceContract $salesInvoices,
    ) {
    }

    public function show(string $invoiceId): array
    {
        return $this->salesInvoices
            ->show(companyId: 123, invoiceId: $invoiceId, include: ['contact', 'details'])
            ->toArray();
    }
}

Satış Faturası Örneği

$result = $salesInvoices->create(
    companyId: 123,
    payload: [
        'data' => [
            'type' => 'sales_invoices',
            'attributes' => [
                'item_type' => 'invoice',
                'issue_date' => '2026-07-01',
                'description' => 'Online sipariş faturası',
            ],
            'relationships' => [
                'contact' => [
                    'data' => ['id' => 'CONTACT_ID', 'type' => 'contacts'],
                ],
                'details' => [
                    'data' => [
                        [
                            'type' => 'sales_invoice_details',
                            'attributes' => [
                                'quantity' => 1,
                                'unit_price' => 100,
                                'vat_rate' => 20,
                            ],
                            'relationships' => [
                                'product' => [
                                    'data' => ['id' => 'PRODUCT_ID', 'type' => 'products'],
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
    include: ['contact', 'details', 'details.product'],
);

e-Arşiv / e-Fatura Akışı

1. Müşterinin vergi numarasıyla e-Fatura gelen kutusu sorgulanır.
2. Müşteri e-Fatura kullanıcısıysa e-Fatura oluşturulur.
3. Müşteri e-Fatura kullanıcısı değilse e-Arşiv oluşturulur.
4. Dönen trackable job sonucu takip edilir.
5. Aktif elektronik belge ve PDF URL bilgisi alınır.

Detaylı kullanım için bkz. docs/integration-guide.md.

Yapay Zeka Entegrasyon Promptları

Mevcut Laravel projesine bu paketi entegre etmek için kullanılabilecek İngilizce AI promptları docs/ai-prompts.md dosyasında bulunur.

Güvenlik ve Performans Notları

• Access token, refresh token, client secret veya kullanıcı şifresi loglanmamalıdır.
• Paraşüt API çağrılarını sınırsız Eloquent döngüleri içinde çalıştırmayın.
• Lokal siparişlerden fatura oluştururken ilişkileri önceden eager-load edin.
• Paraşüt dokümanına göre limit 10 saniyede 10 istektir.

Lisans

MIT. Bkz. LICENSE.md.