Ugrás a fő tartalomhoz

SmartBill integráció

A SmartBill a vezető felhőalapú számlázási platform Romániában 🇷🇴, amelyet kifejezetten a román pénzügyi és jogi követelményekhez terveztek. A CADENSA-ban konfigurálva jogilag érvényes számlákat (facturi fiscale) állíthatsz ki közvetlenül a követett időbejegyzéseidből, teljes e-Factura / ANAF megfeleléssel.

Támogatott országok

A SmartBill a Romániában 🇷🇴 bejegyzett vállalkozások számára készült (érvényes CIF / CUI-val). Támogatja mind a TVA-alany, mind a nem TVA-alany cégeket.

e-Factura megfelelőség

Románia kötelezővé tette az e-Factura jelentést az ANAF-nak (RO e-Invoice rendszer) a B2B tranzakciókban. A SmartBill automatikusan kezeli az ANAF-beküldést, ha a SmartBill Cloud fiókodban ennek megfelelően van konfigurálva.

Mielőtt Elkezded​

Szükséged van:

  • Aktív SmartBill Cloud fiókra (cloud.smartbill.ro)
  • A SmartBill API tokenedre (lásd alább)
  • A vállalatod CIF / CUI adószámára (adóazonosító kód, pl. RO12345678)
  • CADENSA egységre, amelyben legalább Admin szerepköröd van

1. Lépés — A SmartBill API Token Beszerzése​

  1. Jelentkezz be a cloud.smartbill.ro oldalon
  2. Nyisd meg a Contul Meu menüt (jobb felső menü)
  3. Navigálj az Integrări (Integrációk) menüponthoz
  4. Görgess le az API szekcióhoz
  5. Másold ki az API tokenedet — vagy generálj egy újat
Tartsd titokban az API tokened

Soha ne oszd meg az API tokened, és ne commitold verziókezelőbe. Bárki, aki hozzáfér a tokenhez, számlákat hozhat létre és kezelhet a nevedben.

A hivatalos SmartBill API dokumentációért lásd: api.smartbill.ro

2. Lépés — Konfigurálás a CADENSA-ban​

  1. Nyisd meg a Beállítások → Számla menüt a CADENSA-ban
  2. Válaszd a SmartBill 🇷🇴 szolgáltatót
  3. Töltsd ki a hitelesítő adat mezőket:
  • API Key → illeszd be a SmartBill API tokenedet
  • Account Email (API Secret) → a SmartBill bejelentkezési email címed
  • Company ID → a vállalatod CIF/CUI adószáma (pl. RO12345678 vagy csak 12345678)
  1. Kattints a Kapcsolat tesztelése gombra — egy zöld jelzés megerősíti, hogy a hitelesítő adatok érvényesek
  2. Kattints a Mentés gombra
Két hitelesítő adat szükséges

A SmartBill HTTP Basic Authentication hitelesítést használ, amely az email címedet és az API tokenedet kombinálja. Mindkét mező kötelező. Az email címed az "API Secret" mezőként kerül tárolásra a CADENSA-ban.

3. Lépés — Alapértelmezett Értékek Beállítása​

Mentés után konfiguráld a számla alapértelmezett értékeit:

BeállításAjánlott érték
PénznemRON
ÁFA kulcs19% (cota normală)
Fizetési feltételek30 nap

A SmartBill több román TVA kulcsot is támogat:

TVA kulcsSmartBill névLeírás
19%NormalaCota standard
9%RedusaAlimente, medicamente, HoReCa
5%Redusa1Cărți, ziare, locuințe sociale
0%ScutitScutit de TVA

A CADENSA automatikusan kiválasztja a megfelelő SmartBill TVA nevet a beállított ÁFA kulcs alapján.

4. Lépés — Számlasorozat Konfigurálása a SmartBill-ben​

A SmartBill megköveteli, hogy a számlasorozatok az API használata előtt legyenek meghatározva a Cloud fiókodban:

  1. Jelentkezz be a cloud.smartbill.ro oldalon
  2. Nyisd meg a Configurare → Serii menüt
  3. Győződj meg róla, hogy van legalább egy aktív sorozatod facturi-hoz (pl. FCT)
  4. A CADENSA a FCT-t használja alapértelmezett sorozatnévként — ezt módosíthatod, hogy egyezzen a konfigurációddal
A sorozatnak léteznie kell a SmartBill-ben

Ha az FCT sorozat nem létezik a SmartBill Cloud fiókodban, a számla létrehozása sikertelen lesz. Mindig ellenőrizd a sorozatnevet a SmartBill fiókodban.

Ügyféladatok (Számlázási cím)​

A SmartBill REST API nem tesz elérhetővé ügyféllista végpontot, ezért nincs partner választó a Számla generálása párbeszédablakban, amikor a SmartBill az aktív szolgáltatód.

Töltsd ki manuálisan az összes ügyfélmezőt:

MezőLeírás
CégnévKötelező. Az ügyfél bejegyzett cégneve
Kapcsolattartó NeveOpcionális. Egyéni kapcsolattartó személy
EmailOpcionális. A számla emailben történő elküldéséhez használt
OrszágKötelező. Válassz a kereshető ország legördülő listából (ISO kód, pl. RO, HU, DE)
Utca / CímKötelező
IrányítószámKötelező
VárosKötelező
ÁFA / AdószámOpcionális, de szükséges az EU fordított adózású számlákhoz (B2B)
Ország legördülő lista

Az Ország mező egy kereshető legördülő lista — gépeld be az ISO kódot (RO), a magyar nevet (Románia) vagy az angol nevet (Romania) a lista szűréséhez. A legördülő listában mind az elsődleges név, mind a zárójeles fordítás megjelenik.

A megadott ügyféladatok közvetlenül a SmartBill-nek kerülnek elküldésre a POST /invoice kérés részeként. A SmartBill opcionálisan elmentheti az ügyfelet a kapcsolati adatbázisodba — ezt a saveToDb paraméter szabályozza (alapértelmezetten engedélyezve a CADENSA-ban).

Hogyan Jönnek Létre a Számlák​

Amikor a Számla generálása gombra kattintasz, a CADENSA:

  1. Átveszi a Számla generálása párbeszédablakban manuálisan megadott ügyféladatokat
  2. Leképezi az időbejegyzéseidet SmartBill tételekké (products)
  3. Elküldi a POST /invoice kérést a SmartBill API-nak (beleértve az ügyfél adatait — a SmartBill elmentheti a kapcsolati adatbázisodba a saveToDb paraméteren keresztül)
  4. A SmartBill kiosztja a következő elérhető számot a konfigurált sorozaton
  5. A CADENSA elmenti a visszakapott {series}-{number} értéket külső hivatkozásként (pl. FCT-0023)
  6. A számla PDF elérhető a PDF Letöltése gombbal a számlatörténetben

Tétel-leképezés​

CADENSA mezőSmartBill mező
Leírásname
Mennyiség (óra)quantity
Egységárprice
Egység (óra/nap/darab)measuringUnitName (ora/zi/buc)
ÁFA kulcstaxName + taxPercentage
Projekt / feladatproductDescription

Minden ár nettó összegben kerül elküldésre (TVA nélkül) — a SmartBill automatikusan kiszámítja a TVA összegeket.

Számla Visszavonása​

Egy számla visszavonásához a CADENSA-ban:

  1. Nyisd meg a Jelentések → Számlatörténet menüt
  2. Keresd meg a számlát, és kattints a Visszavonás gombra
  3. A CADENSA elküldi a PUT /invoice/cancel kérést a SmartBill-nek (soft-cancel — a számla visszavontként kerül megjelölésre, de a rendszerben marad)
Különbség a törlés és a visszavonás között

A SmartBill támogatja mind a törlést (csak a sorozat utolsó számlájánál lehetséges), mind a visszavonást (anulare, bármely számlánál). A CADENSA mindig a visszavonást használja az ellenőrzési nyomvonal megőrzése érdekében.

Hibaelhárítás​

„401 Unauthorized"​

  • Ellenőrizd, hogy az API token helyes és nem járt-e le
  • Ellenőrizd, hogy az email cím megegyezik-e a token generálásához használt SmartBill fiókkal
  • Ellenőrizd, hogy a CIF pontosan egyezik-e a SmartBill Cloud fiókodban szereplő vállalattal

„Serie inexistenta" (Sorozat nem található)​

  • Az alapértelmezett FCT sorozat nem létezik a SmartBill fiókodban
  • Nyisd meg a Configurare → Serii documente menüt a SmartBill Cloud-ban, és hozz létre egy FCT sorozatot (típus: Factura)

„Cota TVA nu a fost gasita" (ÁFA kulcs nem található)​

  • A TVA kulcs kombinációnak (név + százalék) meg kell lennie határozva a Configurare → Cote TVA menüben a SmartBill Cloud-ban
  • Példa: ha 19%-ot használsz, győződj meg róla, hogy a Normala 19%-on engedélyezve van a fiókodban

„403 Forbidden" (Sebességkorlát)​

  • A SmartBill 10 másodpercenként 30 hívásra korlátozza a kéréseket. Ha ez a korlát túllépésre kerül, a hozzáférés 10 percre blokkolásra kerül
  • A CADENSA úgy van megtervezve, hogy normál használat mellett jól e korlát alatt maradjon

A kapcsolat tesztelése sikertelen, de a hitelesítő adatok helyesnek tűnnek​

  • Győződj meg róla, hogy a vállalatodnak aktív SmartBill Cloud előfizetése van
  • Ellenőrizd, hogy az API felhasználó rendelkezik-e a szükséges jogosultságokkal (számla létrehozása, olvasási hozzáférés)
  • Vedd fel a kapcsolatot a SmartBill támogatással: api@smartbill.ro, ha a probléma továbbra is fennáll

Kapcsolódó Források​