Documentație modul Colete Online pentru Magento 2

1. Setările cheii Magento

A. Crearea cheii

Pentru a conecta magazinul, intrați în contul dumneavoastră Colete Online, în meniul Cont → Integrare, și apăsați Cerere generare cheie API. La primul pas alegeți categoria Magento, apoi apăsați Pasul următor.

La pasul al doilea configurați setările cheii și apăsați Salvează. Setările pot fi modificate oricând ulterior din lista de chei, cu butonul de editare. Comutatorul Simplu / Avansat din dreapta sus afișează doar setările esențiale sau pe toate; capturile de mai jos sunt făcute în modul Avansat.

După salvare veți primi un e-mail cu Client ID și Client Secret. Le veți introduce în configurarea modulului din Magento (vezi capitolul 3).

* Client Secret este afișat o singură dată, în acest e-mail. Păstrați-l într-un loc sigur și nu îl trimiteți nimănui.

B. Setări generale

C. Setări servicii curierat

Aici alegeți serviciile de livrare la adresă oferite clienților și modul în care sunt afișate. În modul Simplu este afișat doar tabelul de servicii.

Tabel servicii

Bifați serviciile pe care doriți să le oferiți; este obligatoriu cel puțin unul. Trageți de pictograma din stânga pentru a schimba ordinea, folosită atunci când tipul de selecție este „Folosește ordinea din tabel”.

Setări preț

D. Lockere / puncte de livrare

Serviciile cu livrare la locker sau la un punct de ridicare au propria filă, cu propriul tabel de servicii și propriile setări de preț (identice cu cele de la livrarea la adresă).

E. Predare la locker, locker la locker, servicii internaționale

Ultimele trei file configurează, în același fel, serviciile cu predare la locker (coletul este lăsat de dumneavoastră într-un locker, nu ridicat de curier), serviciile locker la locker și serviciile internaționale, folosite pentru adresele de livrare din afara României. Fiecare filă poate fi activată sau dezactivată independent.

2. Instalarea modulului

Modulul se instalează cu Composer, din Adobe Commerce Marketplace. Este gratuit. Aveți nevoie de:

• Magento Open Source sau Adobe Commerce 2.4.x;
• PHP 8.1 sau mai nou;
• acces SSH la server, cu Composer, și un cont pe Adobe Commerce Marketplace.

Comenzile de mai jos se rulează din directorul rădăcină al instalării Magento.

A. Obținerea extensiei

Autentificați-vă cu contul de Marketplace, adăugați extensia în coș și finalizați comanda (prețul este 0). Extensia apare apoi în contul dumneavoastră, la My Profile → My Purchases, și poate fi instalată cu cheile de acces ale aceluiași cont.

B. Cheile de acces Marketplace

Composer descarcă extensia de pe repo.magento.com folosind cheile de acces ale contului de Marketplace. Le creați din My Profile → Access Keys (pagina Access Keys), cu Create A New Access Key. Cheia publică (Public Key) este numele de utilizator, iar cheia privată (Private Key) este parola.

Dacă magazinul are deja cheile configurate (de exemplu, de la instalarea Magento), puteți trece la pasul următor. Altfel, adăugați-le în fișierul auth.json din directorul Magento:

composer config http-basic.repo.magento.com <Public Key> <Private Key>

* Nu adăugați auth.json în depozitul Git al magazinului: conține cheia privată a contului dumneavoastră.

C. Instalarea cu Composer

composer require colete-online/magento-module
bin/magento module:enable ColeteOnline_DeliveryMagento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

• composer require descarcă modulul și dependențele lui;
• module:enable activează modulul ColeteOnline_DeliveryMagento;
• setup:upgrade creează câmpurile de produs, statusurile de comandă și atributele de adresă ale modulului;
• setup:di:compile și setup:static-content:deploy regenerează codul și fișierele statice (necesare în modul production);
• cache:flush golește cache-ul, ca modificările să fie vizibile imediat.

Pe un magazin live, puteți încadra pașii între bin/magento maintenance:enable și bin/magento maintenance:disable, ca vizitatorii să nu vadă magazinul în timpul compilării.

D. Actualizarea

La apariția unei versiuni noi, actualizați modulul și rulați din nou pașii de instalare:

composer update colete-online/magento-module
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

3. Configurarea modulului

În panoul de administrare Magento mergeți la Stores → Configuration → Sales → Delivery Methods și deschideți grupul ColeteOnline Delivery. Toate setările modulului sunt în acest grup. După orice modificare apăsați Save Config.

Setările se pot face la nivel global (Default Config) sau diferit pe fiecare website, din selectorul Scope din stânga sus. Credențialele, modul de test și ordinea de afișare se setează la nivel de website; textele și regulile de comandă pot fi diferite și pe fiecare store view.

A. Credențiale și activare

1. Introduceți Client ID și Client Secret primite pe e-mail.
2. Opțional, apăsați Verify Credentials: modulul verifică datele pe loc și afișează „Credentials are valid — it is safe to save.”
3. Setați Enabled pe Yes și Sandbox/Testing Mode pe No.
4. Apăsați Save Config. Credențialele sunt verificate și la salvare; dacă sunt corecte, grupul afișează caseta „Authentication Successful” (sub Enabled).

B. Afișarea la checkout

C. Comenzi și plăți

D. Dimensiuni implicite și țări

4. Crearea unei comenzi

Deschideți comanda din Sales → Orders și alegeți fila ColeteOnline din stânga paginii. De aici pregătiți și generați comanda de curier: adresele, opțiunile, coletele și oferta curierului.

A. Adrese și opțiuni

* Pentru comenzile cu ramburs, contul dumneavoastră Colete Online trebuie să aibă un cont IBAN pentru plata rambursurilor (Cont → Setări → Rambursuri și conturi IBAN). Fără el, ofertele pentru comenzile cu ramburs nu pot fi calculate.

B. Colete și oferte

În Packages verificați coletele: greutatea și dimensiunile sunt completate din produse. Cu Add package adăugați un colet nou, iar din coloana Parcel mutați un produs în alt colet; Reset packages revine la împărțirea inițială. Apăsați apoi Show offers: în Available services apar ofertele curierilor, cu prețul cu și fără TVA. Serviciul ales de client la checkout este preselectat, dar îl puteți schimba.

* Înainte de a genera comanda, verificați dimensiunile fiecărui colet. Le puteți preseta pe fiecare produs pentru comenzile viitoare (vedeți Setări produse).

C. Generarea AWB-ului și eticheta

Apăsați Create courier order. După generare, fila afișează comanda de curier cu numărul AWB, lista de formate ale etichetei (A4, A5, A6 sau 10×15) și butonul de descărcare. Dacă ați lăsat activă setarea „Change Order Status After Courier Order Creation”, comanda trece în statusul Shipping.

Pentru o comandă care pleacă în mai multe transporturi, apăsați Add extra shipping order și creați încă o comandă de curier pentru aceeași comandă Magento.

5. Setări produse

Pentru estimarea corectă a prețurilor, fiecare produs trebuie să aibă greutatea și dimensiunile completate. Deschideți produsul din Catalog → Products; în secțiunea principală a paginii produsului completați:

• Weight — câmpul standard Magento pentru greutate;
• Width (For ColeteOnline) (cm), Length (For ColeteOnline) (cm) și Height (For ColeteOnline) (cm) — câmpurile adăugate de modul la instalare.

Un produs fără greutate sau fără dimensiuni primește valorile implicite din configurarea modulului (capitolul 3, secțiunea D). Pentru produsele configurabile se folosesc greutatea și dimensiunile variantei comandate.

* Modulul citește greutatea în kilograme. Verificați că în Stores → Configuration → General → General → Locale Options câmpul Weight Unit este kgs.

6. Checkout — experiența clientului

A. Completarea automată a adresei

Când țara de livrare este România, formularul de adresă primește câmpuri dedicate: Oras si Judet (RO), cu căutare după localitate, Strada (RO), cu sugestii de străzi din localitatea aleasă, și Nr. Clientul începe să scrie și alege din listă, fără să mai tasteze adresa completă.

Cod Postal (RO) este completat automat: întâi codul localității, apoi codul exact al străzii, după ce aceasta este aleasă. Astfel adresa ajunge la curier în formatul corect, iar riscul coletelor livrate greșit scade.

B. Tarife live

Imediat ce adresa este completă, clientul vede tarifele calculate în timp real pentru serviciile configurate în cheie, inclusiv livrarea la locker. Fiecare serviciu apare cu numele curierului și al serviciului, lângă titlul metodei de livrare (implicit „ColeteOnline Delivery”), alături de celelalte metode de livrare ale magazinului.

C. Alegerea lockerului pe hartă

Când clientul alege un serviciu de livrare la locker, sub lista de tarife apare secțiunea Select Pick-up Point / Locker, cu o listă de puncte și butonul Choose locker on map.

Butonul deschide harta interactivă: clientul caută după localitate sau numele punctului, vede distanța față de adresa lui, deschide detaliile unui punct (program, curier) și apasă Select this point. Punctul ales apare apoi selectat la checkout. Harta este activă automat după ce modulul se conectează cu credențiale valide; nu are o setare separată.

D. Metode de plată

La pasul de plată, modulul adaptează metodele disponibile la livrarea aleasă:

• metodele din lista Restricted Payment Methods for Locker/Pickup Delivery (implicit Cash On Delivery) nu sunt oferite împreună cu livrarea la punct fix;
• plata la livrare este oferită doar dacă serviciul ales acceptă ramburs. Modulul verifică serviciul cu ramburs înainte de a afișa metoda de plată;
• dacă plata la livrare schimbă prețul transportului (de exemplu, prin taxa de ramburs), clientul vede un mesaj cu prețul vechi și cel nou.

Modulul funcționează și cu checkout-ul pe mai multe adrese al Magento (Check Out with Multiple Addresses): fiecare adresă primește propriile tarife și propria alegere de locker.

7. Probleme frecvente

Nu apar tarife la checkout

• Enabled este pe Yes, iar grupul ColeteOnline Delivery afișează „Authentication Successful”.
• Sandbox/Testing Mode este pe No; cu Yes, cererile merg către mediul de test Colete Online, nu către cel real.
• Cheia de pe colete-online.ro are cel puțin un serviciu bifat într-o filă activă.
• Țara de livrare este permisă în Ship to Applicable Countries.
• Adresa este completă: localitate, stradă, număr și cod poștal.

Plata la livrare nu apare sau ofertele nu se calculează

• Metoda Cash On Delivery este activă în Magento (Stores → Configuration → Sales → Payment Methods).
• Contul Colete Online are un cont IBAN pentru plata rambursurilor (Cont → Setări → Rambursuri și conturi IBAN).
• Serviciul ales acceptă ramburs; pentru serviciile care nu îl acceptă, plata la livrare este ascunsă intenționat (capitolul 6, secțiunea D).

Modulul s-a dezactivat singur

Dacă autentificarea eșuează (de exemplu, cheia a fost ștearsă sau credențialele au fost schimbate) sau serverul Colete Online nu poate fi contactat, modulul se dezactivează automat, ca să nu blocheze checkout-ul. Primiți o notificare în panoul de administrare, iar grupul ColeteOnline Delivery afișează caseta „Module Auto-Disabled”, cu motivul și ora. Corectați credențialele și salvați configurarea. Cu Auto Re-enable on Authentication Recovery pe Yes, modulul se reactivează singur după o autentificare reușită.

Modificările nu se văd în magazin

Goliți cache-ul Magento, din System → Cache Management sau cu comanda:

bin/magento cache:flush

Adresele salvate înainte de instalare

Adresele din România salvate de clienți înainte de instalarea modulului nu au localitatea în formatul folosit de completarea automată, așa că clientul trebuie să o aleagă din nou din listă la următoarea comandă. Le puteți completa pe toate dintr-o dată, pe baza codului poștal:

bin/magento coleteonline:address:backfill-city-county --dry-run
bin/magento coleteonline:address:backfill-city-county

Cu --dry-run comanda doar raportează ce ar modifica; --limit=<număr> procesează doar primele adrese, pentru un test. Comanda poate fi rulată de mai multe ori: adresele deja completate sunt sărite.