README

Laravel için Bizimhesap API entegrasyonu. Fatura oluşturma, ürün yönetimi, depo takibi ve stok senkronizasyonu için eksiksiz bir çözüm.

Özellikler

✅ Fatura oluşturma (Satış & Alış)
✅ Ürün listesi ve arama
✅ Depo yönetimi
✅ Stok takibi
✅ Otomatik yeniden deneme mekanizması
✅ Kapsamlı hata yönetimi
✅ Laravel Facade desteği
✅ Test coverage

Gereksinimler

PHP 8.0 veya üstü
Laravel 8.x, 9.x, 10.x veya 11.x
Bizimhesap API erişim bilgileri

Kurulum

1. Paket Kurulumu

Seçenek A: Packagist'ten kurulum (Önerilen)

composer require vizyontech/bizimhesap-laravel

Seçenek B: GitHub'dan direkt kurulum

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/vizyontech/bizimhesap-laravel.git"
        }
    ],
    "require": {
        "vizyontech/bizimhesap-laravel": "^1.0"
    }
}

Seçenek C: Local path (sadece bu proje için)

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/bizimhesap-laravel"
        }
    ],
    "require": {
        "vizyontech/bizimhesap-laravel": "*"
    }
}

2. Service Provider Kaydı

Laravel 5.5+ için otomatik keşif aktiftir. Manuel kayıt için config/app.php:

'providers' => [
    // ...
    VizyonTech\Bizimhesap\BizimhesapServiceProvider::class,
],

3. Facade Kaydı (Opsiyonel)

'aliases' => [
    // ...
    'Bizimhesap' => VizyonTech\Bizimhesap\Facades\Bizimhesap::class,
],

4. Konfigürasyon

Config dosyasını publish edin:

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

.env dosyanıza API bilgilerinizi ekleyin:

BIZIMHESAP_TOKEN=your-account-token-here
BIZIMHESAP_FIRM_ID=your-firm-id-here
BIZIMHESAP_DEBUG=false

Konfigürasyon

Temel Ayarlar

// config/bizimhesap.php

return [
    // Sabit API key (Bizimhesap tarafından belirtilen)
    'api_key' => env('BIZIMHESAP_API_KEY', 'BZMHB2B724018943908D0B82491F203F'),

    // Hesabınıza özel token
    'token' => env('BIZIMHESAP_TOKEN', ''),

    // Bizimhesap tarafından verilen firma ID
    'firm_id' => env('BIZIMHESAP_FIRM_ID', ''),

    // API base URL
    'base_url' => env('BIZIMHESAP_BASE_URL', 'https://bizimhesap.com/api/b2b'),

    // İstek timeout süresi (saniye)
    'timeout' => env('BIZIMHESAP_TIMEOUT', 30),

    // Debug modu
    'debug' => env('BIZIMHESAP_DEBUG', false),

    // Yeniden deneme ayarları
    'retry' => [
        'times' => env('BIZIMHESAP_RETRY_TIMES', 3),
        'sleep' => env('BIZIMHESAP_RETRY_SLEEP', 100), // milisaniye
    ],

    // Varsayılan değerler
    'defaults' => [
        'currency' => 'TL',
        'invoice_type' => [
            'sales' => 3,
            'purchase' => 5,
        ],
    ],

    // Desteklenen para birimleri
    'currencies' => ['TL', 'USD', 'EUR', 'CHF', 'GBP'],
];

Kullanım

Facade ile Kullanım

use Bizimhesap;
use Carbon\Carbon;

// Satış faturası oluştur
$invoice = Bizimhesap::invoice()->createSalesInvoice([
    'invoiceNo' => 'INV-001',
    'dates' => [
        'invoiceDate' => Carbon::now(),
        'dueDate' => Carbon::now()->addDays(15),
    ],
    'customer' => [
        'customerId' => '123',
        'title' => 'Müşteri Adı',
        'address' => 'Müşteri Adresi',
        'taxNo' => '1234567890'
    ],
    'details' => [
        [
            'productId' => 'P001',
            'productName' => 'Ürün Adı',
            'quantity' => 2,
            'unitPrice' => 100,
            'taxRate' => 18,
            // Diğer alanlar otomatik hesaplanır
        ]
    ],
    'amounts' => [
        'currency' => 'TL',
        // Toplamlar otomatik hesaplanır
    ]
]);

// Tüm ürünleri getir
$products = Bizimhesap::products()->all();

// Tüm depoları getir
$warehouses = Bizimhesap::warehouses()->all();

// Belirli depo için stok bilgisi
$inventory = Bizimhesap::inventory()->getByWarehouse('warehouse-id');

Dependency Injection ile Kullanım

use VizyonTech\Bizimhesap\Services\InvoiceService;

class InvoiceController extends Controller
{
    public function __construct(
        protected InvoiceService $invoiceService
    ) {}

    public function store(Request $request)
    {
        $invoice = $this->invoiceService->create($request->validated());
        return response()->json($invoice);
    }
}

Fatura Toplamları Hesaplama

$lineItems = [
    ['quantity' => 2, 'unitPrice' => 100, 'discount' => 10, 'taxRate' => 18],
    ['quantity' => 1, 'unitPrice' => 50, 'discount' => 0, 'taxRate' => 18]
];

$totals = Bizimhesap::invoice()->calculateTotals($lineItems);
// Döner: ['gross' => 250, 'discount' => 10, 'net' => 240, 'tax' => 43.2, 'total' => 283.2]

Ürün İşlemleri

// Ürün arama
$products = Bizimhesap::products()->search('laptop');

// Barkod ile ürün bulma
$product = Bizimhesap::products()->findByBarcode('8690123456789');

// ID ile ürün bulma
$product = Bizimhesap::products()->find('product-id');

Stok Yönetimi

// Stok kontrolü
$hasStock = Bizimhesap::inventory()->isInStock('warehouse-id', 'product-id', 5);

// Düşük stok ürünleri
$lowStock = Bizimhesap::inventory()->getLowStockItems('warehouse-id', 10);

// Tüm depolar arası toplam stok
$totalStock = Bizimhesap::inventory()->getTotalStock('product-id');

// Belirli ürün stoğu
$stock = Bizimhesap::inventory()->getStock('warehouse-id', 'product-id');
echo $stock->available; // Mevcut stok
echo $stock->reserved;  // Rezerve stok
echo $stock->quantity;  // Toplam stok

Depo İşlemleri

// Varsayılan depo
$defaultWarehouse = Bizimhesap::warehouses()->getDefault();

// ID ile depo bulma
$warehouse = Bizimhesap::warehouses()->find('warehouse-id');

// Depo görüntü adı
echo $warehouse->getDisplayName();

Hata Yönetimi

Paket özel exception türleri sağlar:

use VizyonTech\Bizimhesap\Exceptions\{
    AuthenticationException,
    ValidationException,
    ApiException
};

try {
    $invoice = Bizimhesap::invoice()->create($data);
} catch (AuthenticationException $e) {
    // Kimlik doğrulama hataları
    logger()->error('Bizimhesap auth error: ' . $e->getMessage());
} catch (ValidationException $e) {
    // Doğrulama hataları
    $errors = $e->getErrors();
    return response()->json(['errors' => $errors], 422);
} catch (ApiException $e) {
    // Genel API hataları
    $statusCode = $e->getStatusCode();
    logger()->error('Bizimhesap API error: ' . $e->getMessage());
}

Model Sınıfları

Invoice Model

$invoice = new VizyonTech\Bizimhesap\Models\Invoice($data);

// Fatura türü kontrolleri
$invoice->isSales();     // true/false
$invoice->isPurchase();  // true/false
$invoice->getTypeName(); // 'Sales', 'Purchase', 'Unknown'

// Fatura bilgileri
$invoice->getTotal();        // float
$invoice->getCurrency();     // string
$invoice->getCustomerName(); // string

// Array'e çevir
$array = $invoice->toArray();

Product Model

$product = new VizyonTech\Bizimhesap\Models\Product($data);

// Ürün bilgileri
$product->getDisplayName();     // Görüntü adı
$product->getPriceWithTax();    // KDV dahil fiyat
$product->getTaxAmount();       // KDV tutarı

// Array'e çevir
$array = $product->toArray();

Inventory Model

$inventory = new VizyonTech\Bizimhesap\Models\Inventory($data);

// Stok kontrolleri
$inventory->isInStock(5);    // 5 adet stok var mı?
$inventory->isLowStock();    // Düşük stok mu?
$inventory->isOverStock();   // Fazla stok mu?
$inventory->getStatus();     // 'in-stock', 'low-stock', 'out-of-stock', 'over-stock'

// Array'e çevir
$array = $inventory->toArray();

Web Arayüzü

Paket, web tabanlı yönetim arayüzü ile gelir:

Entegrasyon Yönetimi

https://yourdomain.com/entegrasyon/bizimhesap

Özellikler:

API ayarları yapılandırması
Bağlantı testi
Ürün senkronizasyonu
İşlem logları görüntüleme
Otomatik senkronizasyon ayarları

API Ayarları

Token: Bizimhesap hesabınızdan alacağınız API token
Firma ID: Bizimhesap hesabınızdaki firma ID'si
Test Modu: Geliştirme ortamı için test modu
Debug Modu: Detaylı log kayıtları
Otomatik Senkronizasyon: Ürün, stok ve fatura otomasyonu

Veritabanı Tabloları

Paket aşağıdaki tabloları oluşturur:

bizimhesap_settings

Entegrasyon ayarlarını saklar.

bizimhesap_sync_logs

Senkronizasyon işlemlerini loglar.

bizimhesap_product_mappings

Lokal ürünler ile Bizimhesap ürünlerini eşleştirir.

bizimhesap_warehouse_mappings

Lokal depolar ile Bizimhesap depolarını eşleştirir.

API Sınırlamaları

⚠️ Önemli: Bizimhesap API'sinin bilinen sınırlamaları:

Sadece GET ve POST metodları desteklenir
UPDATE veya DELETE işlemleri yok
Sınırlı response formatı dokümantasyonu
Resmi rate limiting bilgisi yok
Dokümantasyon eski (5+ yıl)

Pratik Kullanım Örnekleri

Sipariş'ten Fatura Oluşturma

class InvoiceController extends Controller
{
    public function createFromOrder(Order $order)
    {
        // Sipariş kalemlerini hazırla
        $lineItems = $order->items->map(function ($item) {
            return [
                'productId' => $item->product_id,
                'productName' => $item->product_name,
                'quantity' => $item->quantity,
                'unitPrice' => $item->price,
                'taxRate' => $item->tax_rate ?? 18,
                'discount' => (string) $item->discount,
            ];
        })->toArray();

        // Toplamları otomatik hesapla
        $totals = Bizimhesap::invoice()->calculateTotals($lineItems);

        // Fatura oluştur
        $invoiceData = [
            'invoiceNo' => $order->invoice_number,
            'dates' => [
                'invoiceDate' => Carbon::now(),
                'dueDate' => Carbon::now()->addDays(30),
                'deliveryDate' => $order->delivery_date,
            ],
            'customer' => [
                'customerId' => $order->customer->id,
                'title' => $order->customer->name,
                'address' => $order->customer->address,
                'taxNo' => $order->customer->tax_number,
            ],
            'details' => array_map(function ($item, $index) use ($lineItems) {
                $lineItem = $lineItems[$index];
                $grossPrice = $lineItem['quantity'] * $lineItem['unitPrice'];
                $discount = (float) $lineItem['discount'];
                $net = $grossPrice - $discount;
                $tax = $net * ($lineItem['taxRate'] / 100);

                return array_merge($lineItem, [
                    'grossPrice' => $grossPrice,
                    'net' => $net,
                    'tax' => $tax,
                    'total' => $net + $tax,
                ]);
            }, $lineItems, array_keys($lineItems)),
            'amounts' => array_merge($totals, [
                'currency' => $order->currency ?? 'TL',
            ]),
        ];

        try {
            $response = Bizimhesap::invoice()->create($invoiceData);

            // Bizimhesap fatura ID'sini siparişe kaydet
            $order->update([
                'bizimhesap_invoice_id' => $response['id'] ?? null,
                'invoice_created_at' => now(),
            ]);

            return response()->json([
                'success' => true,
                'message' => 'Fatura başarıyla oluşturuldu',
                'data' => $response
            ]);

        } catch (\Exception $e) {
            \Log::error('Bizimhesap fatura oluşturma hatası', [
                'order_id' => $order->id,
                'error' => $e->getMessage()
            ]);

            return response()->json([
                'success' => false,
                'message' => 'Fatura oluşturulamadı',
                'error' => $e->getMessage()
            ], 422);
        }
    }
}

Stok Kontrolü Servisi

class StockService
{
    public function checkAvailability(array $items, string $warehouseId = null)
    {
        if (!$warehouseId) {
            $warehouseId = Bizimhesap::warehouses()->getDefault()?->id;
        }

        $availability = [];

        foreach ($items as $item) {
            $stock = Bizimhesap::inventory()->getStock($warehouseId, $item['product_id']);

            $availability[] = [
                'product_id' => $item['product_id'],
                'requested' => $item['quantity'],
                'available' => $stock?->available ?? 0,
                'in_stock' => $stock?->isInStock($item['quantity']) ?? false,
            ];
        }

        return [
            'warehouse_id' => $warehouseId,
            'items' => $availability,
            'all_available' => collect($availability)->every('in_stock'),
        ];
    }
}

Test Etme

vendor/bin/phpunit

Güvenlik

Güvenlik açıkları bulursanız, lütfen info@vizyontechyazilim.com adresine e-posta gönderin.

Lisans

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

Değişiklik Geçmişi

Tüm önemli değişiklikler CHANGELOG.md dosyasında belgelenmiştir.

Katkıda Bulunma

Katkılarınızı memnuniyetle karşılıyoruz! Lütfen katkıda bulunmadan önce CONTRIBUTING.md dosyasını okuyun.

Destek

Sorularınız için:

GitHub Issues: Teknik sorunlar ve bug raporları
E-posta: info@vizyontechyazilim.com
Bizimhesap Desteği: destek@bizimhesap.com - (0216) 706 06 60

Ek Kaynaklar

Not: Bu paket, Bizimhesap API'sinin mevcut sınırlamaları göz önüne alınarak hazırlanmıştır. API'nin eksik dokümantasyonu nedeniyle, response formatları ve bazı özellikler tahmine dayalı olarak implement edilmiştir. Production kullanımı için Bizimhesap teknik desteği ile iletişime geçerek güncel dokümantasyon talep edilmesi önerilir.

Paket, Laravel'in best practice'lerine uygun şekilde tasarlanmış olup, genişletilebilir ve test edilebilir bir yapıya sahiptir. API güncellemeleri durumunda kolayca adapte edilebilir.

vizyontech / bizimhesap-laravel

Maintainers

Package info

Statistics

Security