Faturaları Elle Doldurmaktan Bıktım, Bu Yüzden JSON'dan Proforma Faturaları, Borç Notları ve Kredi Notları Oluşturan Bir API Oluşturdum

Sonunda rutini kıran an, üç ayrı fatura şablonunun üç ayrı uygulamada açık olduğu bir Salı öğleydendi. Bir şirketin Almanya'daki bir müşteri için standart bir KDV Faturası gerekiyordu. Bir diğeri, bir perakendeci ile ön ödeme düzenlemesi için bir Proforma Faturasına ihtiyaç duyuyordu. Üçüncüsü, önceki çeyrekten fazla faturalama düzeltmek için bir Kredi Notuna ihtiyaç duyuyordu. Üç şirket, üç belge türü, üç tamamen farklı iş akışı ve bunlardan herhangi birinin gönderilmeye hazır olması için yaklaşık iki saatlik manuel veri girdisi. Sayılar zaten hesaplanmıştı. Müşteri detayları zaten biliniyordu. Satır öğeleri bir elektronik tabloda oturuyordu. Ve yine de bu sayıları düzgün biçimlendirilmiş, profesyonelce tasarlanmış bir PDF'ye koymak için gerçek sürecin, masanın hemen yanında bir yazıcı varken bir romanı elle transkribe etmek gibi hissettirmesi gerekiyordu.

Bu bir seferlik rahatsızlık değildi. Bu aylık ritüeldi. Her faturalandırma döngüsü aynı yorucu diziyi getiriyordu: şablonu aç, fatura numarasını elle güncelle (ve sırayı yanlışlıkla yeniden kullanmadığını kontrol et), müşteri adresini doldur, satır öğelerini teker teker kopyala, vergi hesaplamalarını doğrula, PDF'ye aktar ve gönder. Bunu üç şirketin farklı markalaması, farklı KDV oranları, farklı numaralandırma dizileri ve farklı yasal gerekliliklerle çarpmak ve aylık faturalalandırma süreci bir çalışma gününün çoğunu tüketti. Her ay bir göreve ayrılan tam gün, bu saf veri biçimlendirmesiydi, sıfır yaratıcı veya stratejik değeri vardı.

Mevcut araçlar doğru sorunu çözmüyordu. QuickBooks, FreshBooks, Zoho Invoice ve diğerleri hepsi işletmenin tüm muhasebe omurgası olmak istiyordu. Banka bağlantıları, gider takibi, bordro entegrasyonu ve ayrıcalık için aylık abonelik istediler. Gereken şey çok daha basitti: yapılandırılmış veri gönder, güzel biçimlendirilmiş PDF al. Başka hiçbir şey değil. Kontrol paneli yok, defteri kebir yok, on iki adımlı biniş sihirbazı yok. Sadece JSON kabul eden ve bir belge döndüren bir işlev.

Üç Şirket ve Aylık Faturalaendırmanın Yarattığı Dağınıklık

Birden fazla şirketi işletmek, LinkedIn gönderileri kadar görkemli değildir. Operasyonel ek yük, hemen açık olmayan şekillerde çoğalır ve faturalaendırma en hilelilik şüphelilerinden biridir. Her şirketin kendi yasal tüzel kişiliği, kendi vergi kimlik numarası, kendi banka detayları, kendi logosu ve kendi müşteri tabanı vardır. Bir şirkette mükemmel şekilde çalışan bir faturalandırma aracı, başka bir şirkette tamamen yanlış olabilir çünkü KDV yapısı farklıdır veya çünkü bir şirket euro cinsinden faturalandırırken diğeri yerel para biriminde faturalandırıyor veya çünkü yasal altbilgi gereksinimleri ek hükümün yargı yetkisine göre değişiyor.

Manuel yaklaşım her şirket için Word belge şablonları tutmayı içeriyordu. Bu şablonlar, logolar, yazı tipi seçimleri, renk aksentleri ve dikkatli bir şekilde konumlandırılan alanlarla büyük bir şekilde biçimlendirilmişti. Bunları güncellemek bir kabustu. Şirket telefon numarası değişirse, bu değişim her şablon türü genelinde yayılması gerekiyordu: fatura, proforma, kredi notu, borç notu ve makbuz. Beş belge türü kez üç şirket eşittir on beş şablonu korumak ve her biri hata kaynağı potansiyeli vardır. Banka detaylarında yazım hataları, yanlış KDV kayıt numaraları, günü gelmiş adresler. Bunlar belgelerin yıllar sonra denetlenebilecek yasal kayıtlar olduğunda önemsiz hatalar değildir.

Fatura numaralandırma sorunu kendi paragrafını hak ediyor çünkü gerçek iş sonuçları yarattı. Sıralı fatura numaralandırması birçok yargı yetkisinde yasal bir gerekliliktir. Sırada boşluklar denetimlerde kırmızı bayraklar yükseltir. Tekrarlar daha kötüdür. Üç şirket genelinde beş belge türü için ayrı sıraları korumak, on beş farklı sayacı elle takip etmek anlamına geliyordu. Paylaşılan bir elektronik tablo bu dizileri "kayıt sistemi" olarak hizmet etti ve birden fazla kez fatura zaten gönderildikten sonra elektronik tablo güncellendi, 2024-0047 fatura numarasının gerçekten verilip verilmediği veya hala beklemede olup olmadığı konusunda karışıklık yarattı. Sonunda bu kaosun yerini alan fatura oluşturucu şirket başına ve belge türü başına otomatik numaralandırmayı işler, muhasebe hatalarının tüm bir kategorisini ortadan kaldırır.

Belge ilişkilerinin meselesi de vardı. Bir proforma fatura iş başlamadan önce verilir. Son fatura bu proformaya atıfta bulunur. Bir düzeltme gerekirse, kredi notu orijinal faturaya atıfta bulunur. Borç notu aynı işlemi underbilling için yapar. Bu belgeler bir zincir oluşturur ve bu zinciri Word belgeleri ve elektronik tablolar arasında elle korumak kontrollü kaosun bir alıştırmasıdır. Bir yanlış yazılmış referans numarası ve denetim izi kırılır.

API Gerçekte Ne Yaptığı ve Neden JSON Her Şeyi Değiştirir

Faturalandırma API bir fatura ihtiyaç duyduğu tüm yapılandırılmış verileri içeren bir JSON yükü kabul eder: satıcı detayları, alıcı detayları, miktar ve birim fiyat ile satır öğeleri, vergi oranları, para birimi, ödeme koşulları, notlar ve fatura numarası ve yayın tarihi gibi belge metaveri. Söz konusu yükü işler ve tamamen oluşturulmuş bir PDF belgesini döndürür. Tüm gidiş dönüş saniyeler içinde gerçekleşir. Açmak için şablonlar yok, doldurmak için alanlar yok, doğrulayacak manuel hesaplamalar yok.

Aynı endpoint ailesi tarafından desteklenen beş belge türü desteklenir. Standart bir fatura en yaygın olanıdır, ancak proforma fatura oluşturucu belgenin bir fatura gibi görünmesi ve hissettirmesi gereken ödeme öncesi senaryoları işler. hiçbir yasal ağırlığını taşımayan. Kredi notları orijinal fatura numarasına atıfta bulunarak ve ayarlanmış tutarları göstererek geri ödemeler ve düzeltmeleri işler. Borç notları karşı durumu işler; burada orijinal fatura yayınlandıktan sonra ilave ücretler belgelenmelidir. Makbuzlar ödeyin alındığını onaylar, işlem döngüyü kapatır. Tüm beş tür, küçük varyasyonlar ile aynı JSON yapısını paylaşır, bu, entegrasyon çalışmasının bir kez yapıldığı ve her belge türü bir bonus olarak gelir anlamına gelir.

JSON yaklaşımı, sistemin gerçekten kullanışlı olmasını, yalnızca bir API'nin üzerine bolted başka bir faturalaendırma aracı olmaktan daha kullanışlı hale getiren şeydir. Giriş form alanları yerine yapılandırılmış veri olduğundan, her yerden gelebilir. Bir e-ticaret platformu, bir sipariş sevk edildiğinde otomatik olarak faturalar oluşturabilir. Bir CRM, bir anlaşma belirli bir aşamaya taşındığında bir proforma fatura tetikleyebilir. Elektronik tablo dışı, basit bir komut dosyasıyla bir fatura yığını haline dönüştürülebilir. Veri kaynağı önemli değildir. Geçerli JSON ürettiği sürece API geçerli belgeler üretecektir. Bu birleştirilebilirlik, bir işletmenin zaten kullandığı başka sistemlerle birlikte kullanma temel avantajı, belirli form alanlarını tıklayan bir insanın daima orada olacağını varsayan geleneksel faturalaendırma yazılımlarından.

Daha tatmin edici entegrasyonlardan biri belge tarayıcı ile faturalandırma API'sini bağlar. Tedarikçilerden gelen gelen faturalar taranır ve satır öğeleri, tutarlar ve satıcı detayları çıkarmak için ayrıştırılır. Bu çıkarılan veri, karşılık gelen giden belgeleri oluşturmak için doğrudan faturalandırma API'sına besler, bir eşleşen ödeme makbuzu veya bir ücret uyuşmazlığında kredi notu olup olmadığını. Kağıttan yapılandırılmış veriye kadar oluşturulan belgeye kadar olan döngü, zincirdeki hiçbir noktada manuel veri girdisi olmadan kapanır.

Beş Belge Türü ve Her Biri Önemli Olduğunda

Bu beş belge türü arasındaki ayrım, birçok küçük işletme sahibinin zor yoldan öğrendiği bir şeydir, genellikle bir muhasebeci veya vergi makamı yanlış türün kullanıldığını işaret ettiğinde. Proforma fatura vergi belgesi değildir. Standart bir faturanın gerekli olduğu yerde bir tane yayınlamak uyum baş ağrıları yaratabilir. Tersine, mallar teslim edilmeden veya hizmetler sunulmadan önce tam bir fatura yayınlamak, gelir tanıma sorunları yaratabilir. Hangi türü kullanacağını ve ne zaman kullanacağını anlamak gereklidir ve tüm beş türü destekleyen bir sistem, beş ayrı araç veya beş ayrı iş akışı gerektirmeden, anlamlı bir geçiş kaynağını ortadan kaldırır.

Standart fatura, insanların "fatura" kelimesini duyduklarında düşündükleri belgedir. Tamamlanmış bir işlemi kaydeden yasal ödeme talebidir. Benzersiz bir sıralı numara, her iki tarafın tam yasal detayları, satır öğeleri dökümü, geçerli vergiler ve ödeme talimatları taşır. Vergi beyannameleriyle dosyalanmış ve denetimler sırasında üretilen belgedir. Faturalandırma API'si, JSON girdisinden tüm gerekli alanlar doldurarak bunları oluşturur, hesaplanan toplamları, vergi dökümü ve biçimlendirilmiş para birimi değerlerini içerir. Kullanıcının elle hesaplaması için hiçbir şey bırakılmaz.

Proforma fatura neredeyse aynı görünüyor ama farklı bir amaca hizmet ediyor. İşlem başlamadan önce bir fiyat anlaşmasını resmi hale getirmek için kullanılan, bir teklif fatura olarak giydirilmiş. Uluslararası ticaret, gümrük beyannameleri ve ithalatçı izinleri için proforma faturaları çok güvenmektedir. Serbest çalışanlar, çalışmaya başlamadan önce depoziyi talep etmek için bunları kullanırlar. Temel fark, proforma, karşılık gelen nihai fatura verilene kadar muhasebe defteri kebir'e gelir olarak girmez. API, belge türünü başlıkta açıkça işaretleyerek ve ödeme koşulları dilini uygun şekilde ayarlayarak, bir belgenin bağlayıcı bir fatura mı yoksa ön ödeme tahmini mi olduğu konusunda hiçbir belirsizlik olmaz şekilde bu farklılığı işler.

Kredi notları ve borç notları düzeltici belgelerdir ve burada manuel faturalaendırma işlemleri en dramatik şekilde çöküyor. Kredi notu, alıcının borçlu olduğu tutarı azaltır; tipik olarak döndürülen bir ürün, fiyatlandırma hatası veya orijinal faturanın verilmesinden sonra uygulanan müzakere edilmiş bir indirim nedeniyle. Borç notu karşı durumu artırır; belki de orijinal fatura verilmesinden sonra ek hizmetler sunulduğu veya orijinal faturanın bir hesaplama hatası nedeniyle underbilled olduğu için. Her iki tür de orijinal fatura numarasına atıfta bulunmalıdır ve her ikisi de ödenmemiş bakiyeyi ayarlamak için muhasebe sistemi aracılığıyla akmak gerekir. Elle oluşturmak orijinal faturayı açmak, numarasını bulmak, doğru biçimle yeni bir belge oluşturmak, ayarlama tutarlarını girmek ve referans zincirinin bozulmadığından emin olmak anlamına gelir. API, bunu orijinal belge başvurusunu içeren tek bir JSON yükünden işler.

Makbuzlar en basit tür ama çoğu faturalaendırma aracında şaşırtıcı şekilde yoktur. Makbuz, ödemenin alındığını doğrular. Ödenen faturaya atıfta bulunur, ödemenin miktarını ve tarihini belirtir ve alıcı için işlem kanıtı olarak hizmet eder. Birçok işletme, makbuzları tamamen atlar ve bunun yerine banka transfer onaylamasına güvenir, ancak nakit ağırlıklı endüstrilerde veya resmi makbuzların vergi indirimleri için gerekli olduğu yargı alanlarında, uygun makbuz oluşturma yeteneğine sahip olmak isteğe bağlı değildir. API, ilgili faturalarla eşleşen makbuzlar oluşturur, tüm belgeler tarafından aynı şirket tarafından verilen tüm belgeler boyunca tutarlı bir görünüm korur.

Otomatik Numaralandırma ve Koruduğu Sağlık

Yalnızca otomatik numaralandırma özelliği tüm geliştirme çabasını garanti etti. Her şirket kendi sırasını korur. Söz konusu şirkette her belge türü kendi alt sırasını korur. Fatura numaraları bir deseni izler, proforma faturalar bir başka deseni izler ve kredi notları bir üçüncüsünü izler. Diziler, üretilen her belgeyle otomatik olarak artırılır ve biçim yapılandırılabilir: bazı şirketler 001, 002, 003 gibi basit bir sayısal diziyi tercih ederken, diğerleri 2026-001 gibi bir yıl önek istemekte ve hala diğerleri ABC-INV-001 gibi bir şirket kodu öneki istiyorlar. API, şirket yapılandırmasında bir şablon dizesi aracılığıyla tüm bu biçimleri barındırır ve gerçek sayaç sunucu tarafından yönetilir, böylece yinelenen numaralara veya yanlışlıkla boşluklara sıfır risk vardır.

Bu önemsiz bir ayrıntı gibi görünebilir, ancak fatura sırasındaki bir boşluğu bir vergi müfettişine açıklamak zorunda kalan biri için hiç de önemsiz değildir. Birkaç Avrupa ülkesinde, fatura numaralandırmasında boşluklar, bildirilmeyen gelir kanıtı olarak kabul edilir. Kanıt yükü, boşluğun yanlışlıkla bir işlemi gizleme girişiminden ziyade yanlış olduğunu göstermek için işletmeye kaymaktadır. Otomatik, sunucu tarafından yönetilen bir sayaç bu riski tamamen ortadan kaldırır. Her sayı sıralı, her sayı kullanılmış ve denetim izi, tamam belleği olan bir insandan ziyade sistem tarafından korunmuş.

Numaralandırma sistemi belge türleri arasındaki ilişkiyi de işler. Fatura 2026-042 veya karşısında bir kredi notu yayınlandığında, kredi notu kendi sırasında kendi numarasını taşır (örneğin, CN-2026-008), ancak orijinal faturaya başvuruda bulunur da saklamaktadır. Orijinal fatura kimliği JSON yükünde bulunduğunda bu çapraz referans otomatiktir. Oluşturulan kredi notu PDF, belgelerine daha sonra bakanlar tarafından, alıcının ödenecek hesapları departmanı, harici bir muhasebeci veya işletme sahibi altı ay sonra kitapları uzlaştırmaya çalışan biri olsun, her iki sayı da kağıt izi hemen açık hale getirir.

Bunun Kişisel bir Düzeltmeden Daha Fazla Neden Olmuş

Kişisel bir faturalandırma baş ağrısının çözümü olarak başlayan şey, sorunun evrensel olduğu açık hale geldiğinde çok daha geniş bir şeye döndü. Her serbest çalışan, her küçük ajans, birden fazla girişim işleten her solo kurucu, aynı zorluk türünü yüzler. Mevcut araçlar ya çok karmaşık (haftalarca kurulum ve devam eden bakım gerektiren tam muhasebe paketleri) ya da çok basit (otomatikleştirme olmadan esasen görkemli Word belgeleri olan ücretsiz fatura şablonları). Birden fazla şirketi ve belge türünü işleyecek kadar güçlü ancak tek bir API çağrısı ile entegre edilecek kadar basit bir araç olan orta yol basitçe var olmamıştır.

API, tasarım yoluyla bu orta noktada oturur. Bir muhasebe sistemi olmaya çalışmaz. Ödemeleri izlemez, harcamaları yönetmez veya banka ekstresini uzlaştırmaz. Tam olarak bir şey yapar: yapılandırılmış veriyi profesyonelce biçimlendirilmiş finansal belgelere dönüştürür. Bu dar odak, güvenilir olmasını ve bir işletmenin zaten kullandığı başka herhangi bir sistem ile birleştirilebilir olmasını sağlayan şeydir. Notion'dan, Airtable'dan, özel bir CRM'den, Shopify webhooktan, bir veritabanını okuyan bir cron işinden veri kanalı yapın. API verinin nereden geldiği umurunda değil. Verinin geçerli JSON ve gerekli alanlarla olduğu umurunda ve gönderilmeye hazır bir PDF döndürür.

Süregiden plan, şirketleri, müşterileri ve belge tarihçesini yönetmek için bir kontrol paneli ile bu API'nin üstünde tam bir faturalandırma SaaS uygulaması oluşturmayı içerir. Ancak API, temelde kalacaktır; çünkü yılların başka araçlarla hayal kırıklığından ders, arayüzün hiçbir zaman darboğaz olmaması gerektiğidir. Veri hazır olduğunda, belge hazır olacaktır. Form sayfaları arasında tıklaması yok, sistem zaten bildiği dropdown değerleri seçmesi yok, "PDF Oluştur" düğmesini basabilmek için bir sayfanın yüklenilmesini beklemesi yok. JSON, PDF çıktısı, fatura tamamlandı.