netSEO Oblio Facturare pentru CS-Cart - Modul Integrare Generare Facturi in Oblio (oblio.eu)

netSEO: Oblio Facturare pentru CS-Cart

netSEO: Oblio Facturare este un addon profesional pentru CS-Cart care automatizează generarea facturilor prin integrarea directă cu platforma Oblio (oblio.eu) prin REST API. Modulul permite emiterea documentelor din pagina comenzii, cu preluare automată a datelor client și produse, aliniat la documentația oficială Oblio (oblio.eu/api) și la exemplele publicate de OblioSoftware pe GitHub.

Generare automată a facturilor în Oblio

Modulul permite generarea facturilor direct din pagina de detaliu comandă, cu un singur click. Autentificarea se face prin OAuth 2.0 (client_id = e-mail cont Oblio, client_secret = token din Setări > Date cont), apoi cererile folosesc Bearer token. Datele sunt trimise către endpoint-ul de emitere factură; răspunsul (serie, număr, link document) este salvat în baza de date CS-Cart.

Integrare completă cu comenzile CS-Cart

Toate datele comenzii sunt preluate automat din CS-Cart:

• Informații client (persoană fizică sau juridică)
• Adresă de facturare, localitate, județ și țară
• Produse comandate cu prețuri, cantități și coduri
• Costuri de transport (linie dedicată în factură)
• Moneda facturii (select din monedele active ale platformei) și zile până la scadență

Modulul normalizează textele pentru API (eliminare diacritice unde este cazul) și completează câmpurile client conform API Oblio (ex. vatPayer, save client, contact pentru PJ).

Configurare API Oblio

Conectarea la Oblio se face prin setările addon-ului:

• URL API – URL de bază (implicit: https://www.oblio.eu/api)
• Utilizator (e-mail) – cont Oblio (client_id la token OAuth)
• Token API – client_secret din Oblio: Setări > Date cont
• CUI Companie (fără RO) – CUI firmă emitentă; în cereri se trimite CIF normalizat cu prefix RO
• Serie factură – numele seriei din nomenclatorul Oblio (ex: netseo, FCT)
• Zile până la scadență – configurabile
• Descărcare gestiune Oblio – Da: useStock=1, linii Marfă cu cod (produse în nomenclator + stoc în gestiune); Nu: useStock=0, linii Serviciu fără cod (recomandat pentru magazin online fără aliniere stoc Oblio)

Suport pentru persoane fizice și juridice

Modulul recunoaște tipul de client și preia datele din câmpurile de profil configurate:

• Persoană juridică – nume companie, CUI, Nr. Reg. Com. (ID-uri câmpuri profil)
• Persoană fizică – nume din facturare; CNP din câmp profil opțional

Județul este preluat din state-ul comenzii (b_state_descr). Opțiunea „Salvează client în Oblio” controlează trimiterea câmpului save (actualizare nomenclator client Oblio).

Produse, transport, TVA și discount

Liniile de produs respectă structura JSON Oblio: nume, cantitate, preț, monedă, vatIncluded, vatName, vatPercentage, measuringUnit (implicit buc din setare BUC), productType conform modului de gestiune. Transportul este adăugat ca linie separată. Modulul aliniază totalul la suma comenzii (ajustare rotunjire sau linie discount valoric conform API Oblio).

Delegat și întocmitor pe factură

Se pot configura issuerName, issuerId (CNP), deputyName, deputyIdentityCard, deputyAuto. Dacă comanda are administrator alocat (issuer_id), modulul poate prelua automat numele afișat pentru întocmitor/delegat, similar logicii din alte module netSEO de facturare.

Istoric facturi generate

Facturile generate sunt salvate în baza de date cu:

• ID comandă
• Serie și număr factură
• Link către document (din răspunsul Oblio)
• Cale PDF salvată local când este posibilă descărcarea
• Data generării

În pagina comenzii: subheader, listă facturi cu link, buton „Generează Factură” (culoare portocalie #f36f21) cu confirmare prin POST securizat.

Acțiuni pe facturi emise (API Oblio)

După generare, pentru fiecare factură sunt disponibile acțiuni conform documentației Oblio:

• Storno – emitere factură storno prin POST /docs/invoice cu referenceDocument (Factura, refund)
• Anulare – PUT /docs/invoice/cancel
• Ștergere – DELETE /docs/invoice (conform API, doar ultimul document din serie)
• Restaurare – PUT /docs/invoice/restore

Fiecare acțiune este confirmată înainte de trimitere. Mesajele de eroare returnate de API sunt afișate utilizatorului.

Vizualizare PDF și proxy

Linkul către factură poate fi deschis direct; există și modul get_pdf care servește PDF-ul salvat local sau îl obține prin API (GET document + link semnat) pentru vizualizare din admin.

Mod debug

Opțiune de debug afișează JSON-ul trimis către Oblio înainte de emitere, utilă pentru testare și depanare.

Integrare cu netSEO Addons Manager

Modulul depinde de netSEO Addons Manager:

• Verificare licență la activare și la salvare cod licență
• Cod licență în setările addon-ului
• Upgrade Center Connector pentru actualizări (același model ca la celelalte addon-uri netSEO)

Compatibilitate

• CS-Cart 4.10.1+, ediții ULTIMATE și MULTIVENDOR
• Dependență obligatorie: netSEO Addons Manager

Integrare nativă în CS-Cart

netSEO: Oblio Facturare se integrează în admin prin hook în pagina de detaliu comandă: generare factură, istoric, acțiuni Oblio și setări grupate (API, delegat, date client, produse și transport). Fluxul este proiectat pentru magazine care folosesc Oblio ca soluție de facturare și vor emitere rapidă din comenzile CS-Cart, cu posibilitate de legare la gestiune atunci când produsele și stocul Oblio sunt aliniate cu magazinul.

Fără integrare dedicată Oblio, facturarea din comenzi presupune reintroducere manuală sau export separat. Acest addon reduce timpul și erorile, respectând API-ul Oblio și oferind control clar între modul „fără gestiune” (Serviciu) și modul „cu descărcare gestiune” (Marfă + stoc).