Fáradt vagyok, hogy kézzel töltögessem a számlákat, ezért létrehoztam egy API-t, amely proforma számlákat, terhelési és jóváírási bizonylatok generál JSON-ből

Az a pillanat, amely végül megtörte a rutint, egy szerdai délután volt, amikor három külön számla-sablon volt nyitva három külön alkalmazásban. Az egyik vállalat egy olyan normál ÁFA-számla volt, amely egy német ügyfélnek szólt. A másiknak egy proforma számlára volt szüksége előleges megállapodáshoz egy forgalmazóval. A harmadiknak egy jóváírási bizonylatra volt szüksége, hogy korrigálja az előző negyedév túlszámlázását. Három vállalat, három dokumentumtípus, három teljesen más munkafolyamat, és körülbelül két óra kézi adatbevitel előtt ahhoz, hogy bármelyik is kész legyen a küldésre. A számok már ki voltak számítva. Az ügyfél adatai már ismertek voltak. A tételek egy táblázatban voltak. Mégis a tényleges folyamat, amely során ezeket a számokat egy megfelelően formázott, szakmailag megtervezett PDF-be kellett juttatni, úgy érezte magát, mintha egy regényt kézzel kellett volna abszolválni, amikor egy nyomtató már ott volt az asztalon.

Ez nem volt egyszeri bosszúság. Ez volt a havi rituálé. Minden számlázási ciklus ugyanaz a fárasztó szekvenciát hozta magával: nyiss meg sablont, frissítsd kézzel a számlaszámot (és ellenőrizd, hogy a szekvenciát nem adták-e véletlenül újra), töltsd ki az ügyfél címét, másold át a tételeket egyenként, ellenőrizd az adó-számításokat, exportálj PDF-be, és küld el. Szorozd meg ezt három vállalat által, mindegyiknek más márkázással, más ÁFA-kulcsokkal, más szekvenciákkal, és más jogi követelményekkel, és a havi számlázási folyamat egy munkanap nagy részét felemésztette. Teljes nap havonta olyan feladathoz, amely purement az adatformázás volt, nulla kreatív vagy stratégiai értékkel.

Az eszközök, amelyek léteztek, nem oldották meg a megfelelő problémát. A QuickBooks, FreshBooks, Zoho Invoice és a többi mind azt akarta, hogy az egész könyvelési gerincévé váljon az üzletnek. Bankkapcsolatokat, kiadáskövetetést, bérlista-integrációt és havi előfizetést akartak. Ami szükséges volt, sokkal egyszerűbb volt: küldj strukturált adatot, kapj szépformázott PDF-et. Semmi más. Nincs irányítópult, nincs főkönyv, nincs tizenkét lépéses bevezetési varázsló. Csak egy függvény, amely JSON-t fogad és dokumentumot ad vissza.

Három vállalat és a zűrzavar, amelyet a havi számlázás okoz

Több vállalat működtetése nem olyan dicsőséges, mint amilyennek a LinkedIn-posztok mutatják. Az operatív terhelés többszöröződik olyan módokon, amelyek nem nyilvánvalóak azonnal, és a számlázás az egyik legfurcsább gyanúsított. Minden vállalatnak saját jogi entitása, saját adó-azonosítószáma, saját bankadatai, saját logója és saját ügyfélköre van. Egy olyan számlázási eszköz, amely tökéletesen működik az egyik vállalatnál, lehet teljesen rossznak az másikánál, mivel az ÁFA-szerkezet eltérő, vagy azért, mert az egyik vállalat euróban számláz, míg a másik helyi pénznemben, vagy azért, mert a jogi lábléc követelményei az áttelepülés joghatósága alapján változnak.

A kézi megközelítés Word-dokumentum-sablonok fenntartásához vezetett mindegyik vállalatnak. Ezek a sablonok aprólékosan voltak formázva logókkal, betűtípus-választásokkal, szín-akcentusokkal és óvatosan elhelyezett mezőkkel. Frissítésük rémálom volt. Ha a vállalat telefonszáma megváltozott, ezt a változást minden sablon-változaton keresztül kell keringenie: számla, proforma, jóváírási bizonylatlandsági jegyzék, terhelési bizonylatlandsági jegyzék és nyugta. Öt dokumentumtípus szorozva három vállalat egyenlő tizenöt sablon fenntartása, és mindegyik lehetséges hiba forrása. Elírások bankadatokba, rossz ÁFA-regisztrációs számok, elavult címek. Ezek nem triviális hibák, amikor a dokumentumok jogi bizonylatlandsági jegyzékek, amelyeket évek múlva lehet auditálni.

A számla-számozási probléma saját bekezdést érdemel, mert tényleges üzleti következményeket okozott. Az egymást követő számlaszámozás sok joghatóságban jogi követelmény. A szekvenciaban lévő hézagok piros zászlókat emelnek az auditok során. Az ismétlődések még rosszabbak. Három vállalat között öt dokumentumtípusos külön-külön szekvenciák fenntartása tizenöt különböző számláló kézi nyomon követésétől függött. Egy megosztott táblázat a "bizonylatlandsági jegyzék rendszer"-nek szolgált ezekhez a szekvenciákhoz, és több mint egyszer a táblázat frissítése után a számla már el volt küldve, ami zavart okozott abban, hogy az 2024-0047 szám-számlát már kiadták-e vagy még függő. A számlázási generátor, amely végül ezt a chaos-t helyettesítette, kezeli az autó-számozást vállalatonként és dokumentumtípusonként, kiküszöbölve egy teljes kategóriát a könyvelési hibák közül.

Volt még a dokumentum-kapcsolatok kérdése is. A proforma számlát a munka megkezdése előtt adják ki. A végleges számla ezt a proformát utal. Ha korrekcióra van szükség, a jóváírási bizonylatlandsági jegyzék az eredeti számlára utal. A terhelési bizonylatlandsági jegyzék ugyanezt teszi az alulszámlázáshoz. Ezek a dokumentumok egy láncszemet képeznek, és ezt a láncszemet kézzel Word-dokumentumok és táblázatok között fenntartani egy kontrolláció alatti chaos gyakorlata. Egy elírás referencia-számban, és az audit trail megtörik.

Mit csinál valójában az API és miért változtat meg mindent a JSON

A számlázási API egy JSON-terhelési adatot fogad, amely tartalmazza az összes strukturált adatot, amelyre egy számla szükséges: értékesítő adatai, vevő adatai, tételek mennyiséggel és egységárral, adó-kulcsok, pénznem, fizetési feltételek, megjegyzések és dokumentum-metaadatok, mint például a szám-szám és a kiadás dátuma. Ez feldolgozza azt a terhelési adatot és teljes mértékben felrendezett PDF-dokumentumot ad vissza. Az egész utazás másodpercek alatt megtörténik. Nincsenek sablonok megnyitni, nincsenek mezők kitölteni, nincsenek kézi számítások ellenőrizni.

Öt dokumentumtípus támogatott ugyanaztól az endpoint családtól. Egy normál számla a legelterjedtebb, de a proforma számlázási generátor kezeli az olyan előleges forgatókönyveket, ahol a dokumentumnak úgy kell kinéznie és érezni magát, mint egy számlának, anélkül, hogy az egyik jogi súlyát vinné. A jóváírási bizonylatok visszatérítéseket és korrekciókat kezelnek az eredeti szám-szám meghivatkozásával és a módosított összegek megjelenítésével. A terhelési bizonylatok az ellenkező esetet kezelik, ahol az eredeti szám kiadása után további díjak dokumentálásra van szükség. A nyugták megerősítik, hogy a kifizetés megérkezett, lezárva a tranzakciót. Mind az öt típus ugyanaz a JSON-szerkezetet osztja meg kisebb variációkkal, ami azt jelenti, hogy az integrációs munka egyszer megtörtént, és minden dokumentumtípus ingyen jön magával.

A JSON-megközelítés az, ami a rendszert meggyőzően hasznossá teszi ahelyett, hogy csak egy másik számlázási eszköz lenne egy API-val, amely utólagosan volt felszerelve. Mivel a bemenet strukturált adat helyett űrlapmezőkből áll, bármilyen helyről jöhet. Egy e-kereskedelem platform automatikusan számlét generálhat egy megrendeléshez való szállításkor. Egy CRM egy proforma számlát indíthat meg, ha az alkalom egy adott fázishoz mozog. Egy táblázat-export néhány számlára alakítható egy egyszerű scripttel. Az adatforrás nem számít. Amíg érvényes JSON-t állít elő, az API érvényes dokumentumokat fog előállítani. Ez az összetehetetőség az alapvető előnye a hagyományos számlázási szoftverrel szemben, amely azt feltételezi, hogy egy ember mindig egy képernyő előtt fog ülni és gombokra fog kattintani.

Az egyik meghökkentő integrációs egy dokumentum-szkennerrel csatlakozó számlázási API-hez. A szállítók bejövő számláit beolvassák és parseálják a tételek, összegek és szállító-adatok kinyeréséhez. Ez a kinyert adat közvetlenül a számlázási API-ba kerül a megfelelő kimenő dokumentumok generálásához, legyen az szállítási nyugta vagy a szállító kifizetésének vitatott jóváírási bizonylata. A hurok a papírtól a strukturált adatig a generált dokumentumig szűnik meg kézi adatbevitel nélkül a láncszemet bárhol sem.

Öt dokumentumtípus és amikor mindegyik számít

Az ezen öt dokumentumtípus közötti megkülönböztetés valami, amit sok kis üzleti tulajdonos az a kemény módszer tanul meg, általában amikor egy könyvelő vagy adó-hatóság rámutat, hogy a rossz típust használták. Egy proforma számla nem egy adó-dokumentum. Az egy helyét kiadása, ahol egy normál számlát kellett volna szükséges lehet megfelelőségi fejfájásokat okozni. Ezzel szemben egy teljes számla kiadása a szállítás vagy a szolgáltatás nyújtása előtt bevétel-elismerési problémákat okozhat. Annak megértése, hogy melyik típust kell használni és mikor, elengedhetetlen, és egy olyan rendszer, amely mind az öt támogatja anélkül, hogy öt külön eszköz vagy öt külön munkafolyamat kellene, egy értelmes súrlódási forrásról való megszabadulás.

Egy normál számla az a dokumentum, amelyről a legtöbb ember gondol, amikor meghallják a "számlát". Ez egy jogi fizetési kérelem, amely egy befejezett tranzakciót rögzít. Ezt egy egyedi szekvenciális szám, mindkét fél teljes jogi adatai, tételek bontása, alkalmazható adók és fizetési utasítások hordozzák. Ez az a dokumentum, amely a adó-bevallásokkal van felfájlva és az auditok során előnyálóznak. A számlázási API ezeket az összes szükséges mező feltöltésével hozza létre a JSON-bemenet alapján, beleértve a kiszámított összegeket, adó-lebontásokat és formázott pénznem-értékeket. Semmi sem marad vissza a felhasználó számára, hogy kiszámítsa kézzel.

A proforma számlát csaknem azonos, de más célt szolgál. Ez egy megidézés ruhatörvénnyel felöltözve, amelyet az áramkör formalizálásához használnak a tranzakció megkezdése előtt. A nemzetközi kereskedelem nagymértékben támaszkodik a proforma-számlákat vámnyilatkozatokra és importengedélyekre. A szabadságiak ezeket használják, hogy előlegeket kérjenek a munka megkezdése előtt. A kulcskülönbség az, hogy a proforma nem lép be a könyvelési főkönyvbe bevételként, amíg a megfelelő végső számla ki nem adják. Az API ezt a megkülönböztetést kezeli az alapján, hogy a dokumentumtípusban egyértelműen megjelöli a fejlécben és beállítja a fizetési feltételek nyelvét megfelelően, így soha nincs kétértelműség arról, hogy egy dokumentum egy kötődő számla vagy egy előzetes becslés.

A jóváírási bizonylatok és a terhelési bizonylatok korrekciós dokumentumok, és itt van, ahol a kézi számlázási folyamatok a legspektakulárisabban szűnnek meg. A jóváírási bizonylatlandsági jegyzék csökkenti az összeget, amelyet a vásárló tartozik, jellemzően egy visszatérített termék, egy árazási hiba vagy a eredetia után alkalmazott engedély miatt. A terhelési bizonylatlandsági jegyzék a fordított esetet növeli, talán azért, mert további szolgáltatásokat nyújtottak, vagy azért, mert az eredeti számlát alulszámlázták egy számítási hiba miatt. Mindkét típusnak az eredeti szám-szám meghivatkozása szükséges, és mindkettőnek a könyvelési rendszeren keresztül kell áramolni az outstanding számla módosításához. A generálás kézzel azt jelenti, hogy az eredeti számlát megnyitod, találd meg a számát, hozz létre egy új dokumentumot a megfelelő formátummal, írj be a módosítás összegeket, és biztosítsd, hogy a referencia láncszemet érintetlenül van. Az API ezt az összes egyszerű JSON-terhelési adatból kezeli, amely tartalmazza az eredeti dokumentum hivatkozásást.

A nyugták a legegyszerűbb típus, de meglepően hiányzik a legtöbb számlázási eszközből. A nyugta megerősíti, hogy a kifizetés megérkezett. Ez az a számla, amely volt fizetett, állítja az összeget és a kifizetés dátumát, és a tranzakció bizonylatként szolgál a vásárló számára. Sok üzletség teljesen kihagyja a nyugtákat, és inkább a bankátvitel-megerősítésekre támaszkodik, de készpénz-gazdag iparágakban vagy olyan joghatóságokban, ahol az adó-levonások számára szükséges az adóügyi nyugták, és a tényleges nyugta-generációs képesség nem opcionális. Az API nyugtákat generál, amelyek megfelelő márkázási márka a megfelelő számlák között, fenntartva egy konzisztens megjelenést az összes dokumentum között, amelyet ugyanaz a vállalat adott ki.

Autó-számozás és az értelem, amelyet megőriz

A csak autó-számozási funkció önmagában igazolta az egész fejlesztési erőfeszítést. Minden vállalat fenntartja a saját szekvenciáját. Minden dokumentumtípus egy adott vállalaton belül fenntartja saját alszekvenciáját. A szám-számok követik az egyik mintát, a proforma-számlák követik a másik mintát, és a jóváírási bizonylatok követik a harmadik mintát. A szekvenciák minden generált dokumentummal automatikusan növekednek, és a formátum konfigurálható: egyes vállalatok preferálnak egy egyszerű számszerű szekvenciát, mint az 001, 002, 003, míg mások egy évhokkú előtagot akarnak, mint 2026-001, és még mások egy vállalat-kód-előtagot akarnak, mint az ABC-INV-001. Az API ezeket a formátumokat a vállalati konfigurációban egy sablonos karakterláncán keresztül elég, és a tényleges számláló szerveren kezelt, így nincs nulla kockázata a duplikációs számoknak vagy véletlen hézagoknak.

Ez azért hangzik, mint egy apró részlet, de bárki számára, aki valaha is kénytelen volt elmagyarázni egy hézagot egy szám-szekvenciájában egy adó-ellenőrnek, a semmi sem apró. Több európai országban az adó-szám-szekvencia hézagai meg nem jelentett bevétel feltételezettességeként kezelik. Az igazolásbetöltés a vállalatra áttevődik, hogy megmutassa, hogy a hézag véletlen volt-e, nem pedig egy tranzakció elfedésének kísérlete. Egy automatizált, szermálható szerveren kezelt számláló teljesen kiküszöbölheti ezt a kockázatot. Minden szám szekvenciális, minden szám használt, és az audit-ösvényet a rendszer fenntartja egy embernek egy táblázat helyett egy táblázatban és egy tökéletes memóriában.

A számozó rendszer az összes dokumentumtípus közötti kapcsolatot is kezeli. Egy jóváírási bizonylatlandsági jegyzék kiadása az 2026-042 szám ellen, a jóváírási bizonylatlandsági jegyzék hordja a saját számát a saját szekvenciájában (például CN-2026-008), de az eredeti számlára való hivatkozásás is tárol. Ez az kereszt-hivatkozás automatikus, ha az eredeti szám-ID a JSON-terhelési adatban szerepel. A generált jóváírási bizonylatlandsági jegyzék PDF mindkét szám prominensen megjeleníti, a papír-nyomvonal azonnal világossá téve bárki számára a dokumentumok későbbi felülvizsgálata során, legyen az a vásárló adott kifizetésű osztálya, egy külső könyvvizsgáló vagy az üzleti tulajdonos, aki hat hónap múlva próbálja megbékélni a könyveket.

Miért vált ez többé egy személyes javításnál

Ami egy személyes számlázási fejfájások megoldásáról kezdődött, valamivel jelentősebbé vált, amikor világossá vált, hogy a probléma univerzális. Minden szabadságias, minden kis ügynökség, minden egyetlen alapító, amely több vállalat futtat, valamely verzióját találja meg ugyanehhez a kihíváshoz. A meglévő eszközök vagy túl összetett (teljes könyvelési szvit, amely hetek beállítása és folyamatos karbantartás szükséges) vagy túl egyszerű (szabad számlázási sablonok, amelyek lényegében az utánhagyott Word-dokumentumok, nincsenek automatizálása). A középút, egy eszköz, amely elég erős ahhoz, hogy több vállalatot és dokumentumtípust kezeljen, de elég egyszerű ahhoz, hogy egy API-hívást integráljon, egyszerűen nem létezett.

Az API az e középút alapján ül. Nem próbál egy könyvelési rendszer lenni. Nem követi nyomon a kifizetéseket, nem kezeli a kiadásokat, és nem egyeznek meg a bankszámlák. Pontosan egy dolgot csinál: átalakítja a strukturált adatokat szakmailag formázott pénzügyi dokumentumokba. Ez az estreszült fókusz az, ami megbízható, és mi teszi összetehetetőnek a bármely más rendszerrel, amelyet egy üzletség már használ. Vezeték-adat a gondolatból, az Airtablótól, egy egyéni CRM-ből, a Shopify webhookkal, egy cron munka, amely egy adatbázist olvasva. Az API nem törődik azzal, hogy az adat honnan származik. Azzal foglalkozik, hogy az adat érvényes JSON az szükséges mezőkkel, és PDF-et ad vissza, amely készen áll a küldésre.

A terv előre jár egy teljes számlázási SaaS alkalmazás építése ennek az API-nak az alapján, teljes irányítópulttal a vállalatok, ügyfelek és dokumentum-előzmények kezeléséhez. De az API az alapvető marad, mivel az évek frusztráció tanácsa más eszközökkel az, hogy az interfész soha ne legyen a szűk hely. Amikor az adat készen áll, a dokumentum készen áll. Nincsenek kattintás az űrlapok között, nincsenek a rendszer már tudott legördülő értékek kiválasztása, nincsenek egy oldal betöltésére való várakozása, így egy "Generálj PDF" gomb megnyomható. JSON-ben, PDF-ben ki, számla kész.