Pluginul leagă un magazin WordPress / WooCommerce de firma din eZif, prin API-ul eZif. Se descarcă din Integrări → Magazine online — WooCommerce (buton Descarcă pluginul). Cerințe: WordPress 6.2+, WooCommerce 7.8+, PHP 7.4+; compatibil cu comenzile HPOS și cu finalizarea cu blocuri.
Instalare
- eZif → Integrări → API și chei: o cheie pentru fiecare magazin (ex. „Magazin bioglobal.ro”); domeniul magazinului la Domenii autorizate → Salvează.
- WordPress → Module → Adaugă → Încarcă modul → fișierul
ezif-woocommerce-1.5.1.zip(la actualizare: încarci arhiva nouă și alegi „Înlocuiește versiunea curentă”) → Instalează → Activează. - WooCommerce → Setări → eZif: adresa eZif — doar domeniul, fără
/api/…(https://app.ezif.ro; pentru probehttps://dev.ezif.ro; o adresă copiată cu/api/ext/v1se curăță automat), X-Ezif-Key, Secret → Salvează și testează legătura cu eZif (arată firma și utilizatorul în numele căruia se emit facturile).
Caseta „Comunicarea cu eZif”
Sus în WooCommerce → Setări → eZif: versiunea pluginului, ultima cerere reușită și ultima eroare (ora și motivul). Dacă modulul FGO e încă activ și emiterea e automată, apare un avertisment: fiecare comandă ar primi două facturi. În eZif, aceleași cereri se văd în Integrări → API și chei → Ultimele cereri.
Setările pluginului
| Setare | Explicație |
|---|---|
| Documentul emis | Factură, Proformă sau Proformă la comandă, apoi factură — factura se emite din proformă (aceleași linii, același client) |
| Emite proforma când | doar pentru „Proformă, apoi factură”: comanda e plasată, devine În așteptare (ex. plata prin transfer) sau În procesare, ori Manual |
| Emite documentul când comanda devine | Finalizată (implicit), În procesare, În așteptare sau Manual — factura (sau proforma, la „Proformă”) |
| Seria facturilor / Seria proformelor | alegere din seriile active în eZif (lista se încarcă după „Salvează și testează”); „Seria implicită din eZif” sau un prefix anume (ex. BIO, PAPS). Fiecare magazin poate avea seriile lui. |
| Metode de plată încasate online | pentru comenzile plătite cu aceste metode (card, Netopia, Stripe…), încasarea se înregistrează odată cu factura |
| Cota TVA implicită | doar când taxele WooCommerce sunt dezactivate (prețurile din magazin includ TVA) |
| Retur integral / Comandă anulată | stornarea automată a facturii |
| Linkul facturii | linkul PDF în e-mailurile către client și în „Contul meu” |
| Factură pe firmă | câmpurile „Vreau factură pe firmă”, CUI și Nr. Reg. Com. la finalizarea comenzii |
| Sincronizează stocul | stocul disponibil din eZif, o dată pe oră |
| După factură și storno | stocul produselor din comandă se actualizează imediat după factură și după stornare (anulare, retur) |
| Sincronizează stocul acum | butonul de sub setări: sincronizarea completă, oricând, cu rezultatul afișat |
Articolele pe factură
Secțiunea Articolele pe factură (pluginul 1.4.0) — echivalentul paginii „Setări Articole” din modulul FGO:
| Setare | Explicație |
|---|---|
| Codul produsului | bifat (implicit): SKU-ul din magazin e codul articolului din eZif — factura folosește articolul și descarcă stocul; nebifat: linii libere, doar cu denumirea |
| SKU în denumire | codul apare înaintea denumirii pe factură (ex. „VITC-1000 — Vitamina C 1000 mg”) |
| Gestiunea din eZif | codul gestiunii (ex. GES01) din care se descarcă produsele și al cărei stoc se sincronizează; gol = gestiunea implicită a fiecărui articol |
| Transportul pe factură | Da — linie separată, cu TVA-ul calculat de WooCommerce; Nu — transportul nu apare (totalul facturii va fi mai mic decât al comenzii) |
| Denumirea / codul transportului | pe factură: „Transport — metoda de livrare”; codul = un serviciu din eZif (ex. TRANSPORT) |
| Reducerile | Prețul final (implicit) — reducerea e inclusă în prețul produselor; Prețul întreg + linie separată „Reducere” — produsele la prețul întreg (înainte de cupoane; la produsele cu preț redus, prețul obișnuit), iar reducerea pe o linie cu cantitatea −1, câte una pe fiecare cotă TVA |
| Denumirea / codul reducerii | ex. „Reducere” / REDUCERE (un serviciu din eZif) |
Codurile de transport și de reducere care nu există încă în eZif se creează singure ca servicii, fără stoc (când regula „Produs necunoscut din magazin” e „Adaugă în Produse”). Linia de reducere nu poate fi pe un articol de stoc, iar totalul facturii rămâne pozitiv; returul de marfă se face prin storno. În toate variantele (cu excepția transportului ascuns), totalul facturii e totalul comenzii. La produsele cu preț redus, prețul întreg e prețul obișnuit al produsului la momentul facturii: dacă promoția s-a încheiat între timp, produsul apare la prețul plătit, fără linie de reducere.
TVA-ul transportului e cel din WooCommerce (Setări → Taxe): opțiunile FGO „costul de livrare include TVA / cu TVA” sunt acoperite de setările de taxe ale magazinului.
Ce se întâmplă
| În magazin | În eZif |
|---|---|
| comanda e plasată / ajunge la starea aleasă pentru proformă | proforma se emite din seria de proforme (fără e-Factura și fără descărcarea stocului); linkul PDF apare în e-mailul clientului |
| comanda ajunge la starea aleasă | factura se emite (la „Proformă, apoi factură”: din proformă) (numerotare, TVA, e-Factura, descărcarea stocului pentru produsele cu SKU = cod eZif); nota „eZif: factura … emisă” și caseta eZif — factura din comandă, cu PDF-ul |
| aceeași comandă ajunge din nou la starea aleasă | nimic: o comandă are o singură factură (numărul comenzii e cheia) |
| plată online cu o metodă bifată | încasarea pe factură |
| comanda cu ramburs / transfer e încasată în eZif | cu callback-ul configurat, comanda devine plătită în magazin |
| rambursare integrală | factura storno (dacă e bifat) |
| rambursare parțială | notă în comandă: stornarea parțială se face în eZif, pe linii |
| comandă facturată, anulată | stornarea (dacă e bifat) sau notă |
| eZif nu răspunde | reîncercări automate după 5, 10, 15, 20 de minute; erorile de date (ex. adresă lipsă) apar în comandă, iar butonul Emite factura reîncearcă |
Lista de comenzi are coloana Factura eZif (numărul, cu link la PDF, sau „eroare”) și acțiunea în masă Emite facturile eZif (cel mult 50 de comenzi odată; cele care au deja factură se sar).
O încasare înregistrată în eZif pe factura unei comenzi (Documente de vânzare → factura → Încasări) ajunge în magazin prin callback: comanda devine plătită; o încasare anulată apare ca notă în comandă.
Clientul și liniile
- Persoană fizică: numele din facturare; firmă: bifa „Vreau factură pe firmă”, numele companiei și CUI-ul (cu RO = plătitor de TVA). Administratorul poate completa CUI-ul și în comandă.
- Adresa (județ, localitate, adresă) e obligatorie pentru e-Factura; câmpurile lipsă din adresa de facturare se iau din adresa de livrare, iar dacă tot lipsesc, nota comenzii spune exact ce lipsește și ce s-a primit. În București sectorul se ia din localitate („Sector 3”) sau din codul poștal (03xxxx = sectorul 3).
- Produs necunoscut (SKU-ul nu există în eZif) — după setarea din eZif, Integrări → API și chei → Articole și clienți: linie liberă pe factură (implicit), adaugă în Produse, fără gestiune de stoc (doar facturare) sau adaugă în Produse, cu scădere din stoc (cu stoc 0, vânzarea trece doar dacă gestiunea permite stoc negativ; altfel comanda așteaptă NIR-ul). Produsul adăugat e marcat „de verificat” în Produse → Articole.
- Liniile: produsele (codul = SKU-ul), transportul și taxele suplimentare; prețurile se trimit fără TVA, din totalul fiecărei linii după cupoane, deci valoarea fiecărei linii e exactă. Reducerile: fie incluse în prețuri (taxele negative se repartizează proporțional pe produsele cu aceeași cotă), fie pe linii separate „Reducere” — vezi Articolele pe factură.
- Totalul: cu setarea WooCommerce „Rotunjește taxa la nivel de subtotal”, TVA se calculează la fel ca în eZif (pe cotă), iar totalul facturii e identic cu al comenzii. Fără ea pot apărea diferențe de 1 ban, scrise în nota comenzii; pluginul afișează un avertisment în setări.
Callback la încasare
Se configurează automat, la Salvează și testează legătura cu eZif: pluginul își înregistrează în eZif adresa magazinului (…/wp-json/ezif/v1/callback, sau …/?rest_route=/ezif/v1/callback pe site-urile fără legături permanente), primește secretul cu care eZif semnează apelurile și îl salvează; apoi eZif trimite un apel de test, iar mesajul din plugin spune „Callback-ul la încasare funcționează” sau motivul. Nu se copiază nimic și nu se completează nimic în eZif.
Fiecare magazin are callback-ul lui, legat de cheia lui. În eZif, Integrări → API și chei → Callback la încasare e o listă, ca lista cheilor: adresa (cu Copiază), aplicația și cheia, ultima verificare, starea și butoanele Trimite un test, Arată secretul (cod 2FA), Secret nou (cod 2FA; apoi în plugin „Salvează și testează” preia secretul nou) și Șterge. Tot acolo se adaugă un callback general pentru alte aplicații (adresa → Adaugă callback → apare secretul, o dată; apoi din nou cu Arată secretul). O încasare pe o factură emisă de magazin merge la callback-ul acelui magazin.
Stocul
Cu Sincronizează stocul bifat, o dată pe oră: stocul disponibil din eZif (fizic minus rezervat, din gestiunea aleasă sau din toate) devine stocul produselor WooCommerce cu același SKU și cu „Gestionează stocul” activ. Cu După factură și storno, stocul produselor din comandă se actualizează imediat (API: GET /api/ext/v1/stock?sku=COD1,COD2). Sincronizează stocul acum face sincronizarea completă la cerere, fără limită de frecvență.
Probleme frecvente
| Mesaj în comandă | Ce faci |
|---|---|
| Domeniul aplicației nu e în lista domeniilor autorizate | adaugă domeniul magazinului în eZif → API și chei |
| Cheia API nu există sau a fost revocată / Semnătura nu corespunde | copiază din nou cheia și secretul în setările pluginului |
| Cererea e prea veche sau ceasul serverului tău nu e sincronizat | ceasul serverului magazinului e decalat cu peste 5 minute: cere firmei de hosting sincronizarea (NTP) |
| Județul, localitatea și strada sunt obligatorii | completează adresa de facturare în comandă → Emite factura |
| Seria „…” nu există în eZif | corectează seria în plugin sau creeaz-o în eZif |
Livrarea și AWB-ul (pluginul 1.5.0)
Pentru decontările curierilor și ale procesatorilor de plăți (Integrări → Curieri / Procesatori de plăți), pluginul trimite în eZif, la emiterea facturii: metoda de plată (plata la livrare → ramburs; transfer bancar → transfer; plățile cu cardul și metodele bifate la „Metode de plată încasate online” → card), numărul comenzii și, dacă există deja, curierul și AWB-ul.
| Setare | Explicație |
|---|---|
| (automat) Sameday | AWB-ul generat de pluginul Sameday (tabelul sameday_awb) se citește singur |
| AWB-ul altui curier | câmpul comenzii (meta) în care pluginul altui curier salvează AWB-ul, ex. _awb_number; mai multe, separate prin virgulă |
| Curierul acestor AWB-uri | FAN Courier, Cargus, GLS, DPD, DHL, Poșta Română |
AWB-ul generat după factură se trimite la finalizarea comenzii sau, cel târziu, în 30 de minute (WP-Cron), o singură dată pe AWB; comanda primește nota „AWB-ul … a fost legat de factura …”, iar caseta eZif din comandă îl arată.