# Teklif ve faturaları içe aktarma

Başka bir teklif veya faturalandırma sisteminden Borkol'a geçiyorsanız, mevcut belgelerinizin sıfırdan başlaması gerekmez. İçe aktarma; belge türlerini, kişileri, teklifleri, faturaları, ödemeleri ve numara serilerini tek bir JSON dışa aktarımından getirir, böylece numaralandırmanız eski sistemin bıraktığı yerden devam eder, 1'den yeniden başlamaz.

Bunun için henüz self-servis bir içe aktarma ekranı yok: Borkol destek ekibi, sizin (veya eski sisteminizin) ürettiği bir JSON dosyasından bunu sizin için çalıştırır.

## Nasıl çalışır

Destek, dışa aktarıma karşı `php artisan sales:import {tenant} {file}` komutunu çalıştırır. Dosyayı doğrulamak ve hiçbir şey yazmadan her türden kaç satırın içe aktarılacağını görmek için önce `--dry-run` ekleyin — bu çalıştırma her zaman geri alınır ve bir deneme çalıştırmasında hiçbir zaman medya saklamaz. Gerçek bir çalıştırma, dosyadaki her şeyi içe aktarır ya da hiçbirini: herhangi bir satır düzeyinde hata (toplamı tutmayan bir tutar, bilinmeyen bir numara serisi, reddedilen bir görsel veya PDF kaynağı) tüm içe aktarımı geri alır ve komut her hatayı dosyadaki konumuyla birlikte bildirir (örneğin `quotes[0] (q-1).total_amount: …`).

İçe aktarma `external_id` üzerinde idempotenttir: aynı dosyayı iki kez çalıştırmak, ya da önceki bir dosyaya yeni satırlar eklenmiş bir dosya çalıştırmak, zaten içe aktarılmış olanı atlar ve yalnızca yeni olanı ekler.

## Dosyanın içeriği

Dışa aktarım, beş isteğe bağlı üst düzey diziye sahip tek bir JSON belgesidir:

| Anahtar | Neyi içerir |
| --- | --- |
| `document_types[]` | Eski sisteminizin kullandığı adlandırılmış numara serisi önekleri |
| `contacts[]` | Her biri bir `external_id` ve tipli adreslere sahip müşteriler |
| `quotes[]` | Kalemleri, kapsam maddeleri ve (isteğe bağlı) bir imza içeren teklifler |
| `invoices[]` | Kalemleri ve ödemeleri içeren faturalar ve iade faturaları |
| `series[]` | Yeni numaraların eskilerin kaldığı yerden devam etmesi için tohumlanacak sayaçlar |

### Kişiler

Her kişi gerçek bir ada, isteğe bağlı şirket alanlarına ve kendinizin atadığı bir `external_id`'ye sahiptir — aynı değer, bu kişiyi aynı veya sonraki bir dosyadaki tekliflerle ve faturalarla eşleştirmek için kullanılır. Adresler, bir teklifin veya faturanın başvurabileceği iki adres türüyle eşleşecek şekilde **fatura adresi** veya **şantiye adresi** olarak tiplenir.

### Teklifler

Her teklif, `number`, `status`, tarihler, kalemler ve kapsam maddelerinin yanı sıra kendi `external_id`'sini taşır. Bir teklif ayrıca (imzalanmış kabul edilmiş bir teklif için) bir `signature_url` ve `signed_pdf_url` ile olağan fotoğraf sınırına kadar `photos[]` taşıyabilir — hepsi, içe aktarma sırasında alınıp Borkol'da saklanan URL'ler olarak verilir. Bir **taslak** teklife, canlı sistemde bir taslağın asla numarası olmadığı gibi, içe aktarma tarafından da asla numara verilmez.

### Faturalar

Her fatura, `number`, `invoice` mi yoksa `credit_note` mu olduğu, durumu, tarihleri, kalemleri ve ona karşı zaten kaydedilmiş ödemeleri taşır. Bir iade faturası, düzelttiği faturaya başvurur.

### Seriler

Her giriş bir `scope` (teklif, fatura veya iade faturası), isteğe bağlı olarak belirli bir belge türü, uygulandığı muhasebe `period`'unu ve o dönemde zaten verilmiş en yüksek `value`'yu adlandırır. İçe aktarmadan sonra, canlı numaralandırma o değerden hemen sonraki numaradan devam eder — hiçbir şey yeniden numaralandırılmaz ve boşluk oluşmaz.

## Medya

URL ile başvurulan imzalar, imzalı PDF'ler ve fatura PDF'leri, Borkol içinde oluşturulan bir belgenin saklandığı şekilde indirilip saklanır; teklif fotoğrafları, diğer her yükleme gibi medya kitaplığınıza eklenir. Kaynak olarak yalnızca sıradan, herkese açık web adresleri kabul edilir — özel, yerel veya başka türlü erişilemez adresler reddedilir.