Documentație plugin Colete Online pentru OpenCart
Integrarea cu OpenCart vă permite să oferiți clienților magazinului dumneavoastră toți curierii din România direct din platforma OpenCart. Prin instalarea plugin-ului veți putea configura metodele de livrare afișate în checkout, veți genera AWB-uri direct din pagina comenzii și veți facilita completarea rapidă și corectă a adreselor cu ajutorul funcției de completare automată.
Pentru metodele de livrare puteți fie să le oferiți clienților servicii prestabilite (de exemplu, cel mai ieftin curier), fie să le permiteți acestora să aleagă dintre curierii pe care îi selectați din cheia de OpenCart, inclusiv livrarea la locker cu alegerea punctului pe hartă.
În zona de administrare puteți gestiona comenzile de curier, având acces la toate informațiile esențiale legate de statusul și evoluția acestora. De asemenea, aveți posibilitatea de a modifica datele unei comenzi (adresă, colete, opțiuni) înainte de a genera comanda de curier, astfel încât toate detaliile să fie corecte pentru o livrare fără probleme.
Plugin-ul este disponibil în două variante, una pentru OpenCart 3.0.x și una pentru OpenCart 4.x, ambele disponibile gratuit în marketplace-ul oficial OpenCart. Pașii de configurare sunt identici; diferă doar ecranul de instalare și stilul interfeței de administrare. Capturile din acest ghid sunt făcute pe OpenCart 4, iar acolo unde OpenCart 3 arată diferit este menționat explicit.
* Pentru estimarea corectă a prețurilor pentru curieri, produsele din magazin trebuie să conțină toate detaliile privitoare la greutate și dimensiune. În cazul în care curierul sesizează o declarare greșită a greutății sau a dimensiunii coletului, veți fi taxat suplimentar pentru declararea incorectă.
1. Setările cheii OpenCart
A. Crearea cheii
Pentru a conecta magazinul, trebuie să intrați în platforma Colete Online și să generați o cheie API. Din meniul Integrări alegeți crearea unei chei noi de tip OpenCart.
După generarea cheii va trebui să configurați setările acesteia și să le salvați (aceste setări pot fi modificate ulterior).
După ce salvați setările veți primi un e-mail cu Client ID și Client Secret, pe care le veți folosi în setările plugin-ului din OpenCart.
B. Setări generale
Nume cheie: Numele cu care puteți identifica cheia ulterior.
URL: Adresa site-ului dumneavoastră.
Adresă ridicare: Adresa implicită de unde se ridică comenzile.
Comentariu: Câteva detalii despre cheie.
C. Servicii de curierat
Din tabelul de servicii alegeți curierii pe care doriți să îi oferiți clienților. Fiecare serviciu poate fi activat, dezactivat și ordonat, iar pentru fiecare puteți seta modul de afișare a prețului.
D. Lockere / puncte de livrare
Pentru serviciile cu livrare la locker puteți controla ce puncte fixe sunt disponibile clienților și cum sunt afișate prețurile acestora.
2. Instalarea plugin-ului
Instalați plugin-ul din marketplace-ul oficial OpenCart. Este varianta recomandată: acolo găsiți întotdeauna ultima versiune verificată, iar actualizările ulterioare apar în același loc. Extensia este gratuită.
Pagina oficială a extensiei: Colete Online în marketplace-ul OpenCart
Pe pagina extensiei apăsați Download și alegeți pachetul corespunzător versiunii dumneavoastră de OpenCart: coleteonline.ocmod.zip pentru OpenCart 4, respectiv coleteonline-oc3-<versiune>.ocmod.zip pentru OpenCart 3. Cele două arhive nu sunt interschimbabile.
* Nu redenumiți arhiva pentru OpenCart 4: numele coleteonline.ocmod.zip trebuie păstrat exact, deoarece OpenCart 4 denumește folderul extras după numele arhivei, iar acel nume este folosit în rutare și în namespace-ul PHP.
A. OpenCart 4
În panoul de administrare mergeți la Extensions → Installer, apăsați Upload și selectați arhiva coleteonline.ocmod.zip. Așteptați mesajul de confirmare „Success: You have modified extensions!”.
Apoi mergeți la Extensions → Extensions, alegeți tipul Shipping, găsiți Colete Online și apăsați butonul verde + (Install). Apăsați apoi pictograma de editare pentru a deschide setările.
B. OpenCart 3
Pentru OpenCart 3 pașii sunt aceiași: Extensions → Installer pentru încărcarea arhivei, apoi Extensions → Extensions → Shipping pentru instalarea și editarea metodei Colete Online.
* Dacă primiți „Permission Denied” pe o pagină Colete Online, acordați grupului de utilizatori admin permisiunea (access și modify) pentru rutele extensiei din System → Users → User Groups.
3. Setările plugin-ului
Pe ecranul de setări, la API credentials, introduceți Client ID și Client secret primite pe e-mail, activați Status, setați un Sort order și apăsați Save. La conectarea reușită apare bannerul verde „Colete Online credentials are valid. Connected successfully.” și se afișează filele de configurare.
Client ID
client_id-ul primit de la Colete Online pe e-mail, după generarea cheii de integrare.
Client secret
client_secret-ul corespunzător cheii. Se afișează mascat după salvare.
Status
Activează sau dezactivează metoda de livrare Colete Online în magazin. Cât timp este dezactivată, nu apare nicio ofertă la checkout.
Sort order
Poziția metodei Colete Online față de celelalte metode de livrare afișate la checkout. Valoarea mai mică apare mai sus.
După conectare, o parte dintre setările de afișare și de preț sunt transferate și administrate pe colete-online.ro; un mesaj în partea de sus a paginii („Change your settings on colete-online.ro”) vă duce acolo.
Setările mutate pe platformă sunt: adresa implicită de ridicare, tipul de selecție, ordinea de afișare, selecția serviciilor, limita de afișare, numele personalizate, tabelul de servicii, tipul de preț (sumă fixă / procent / rotunjire), prioritizarea punctelor fixe și trimiterea e-mailului către destinatar. Le găsiți în setările cheii de OpenCart de pe colete-online.ro (vezi capitolul 1).
Testing mode
Trimite comenzile către serverul de test al Colete Online, pentru a verifica fluxul fără a genera AWB-uri reale.
Opțiuni disponibile:
- Nu → comenzile merg către curierii reali (valoarea normală pentru un magazin live)
- Da → comenzile sunt create pe serverul de test și nu ajung la curier
* Nu uitați să reveniți pe „Nu” înainte de a deschide magazinul; altfel comenzile clienților nu vor ajunge niciodată la curier.
Filele de configurare
Fiecare filă reglează un aspect al comportamentului la checkout și la comenzi. Fiecare câmp are o notă de ajutor; valorile implicite sunt potrivite pentru majoritatea magazinelor.
Currency — moneda folosită pentru tarife.
Calculate in custom currency
Moneda în care sunt calculate tarifele de livrare.
Opțiuni disponibile:
- Use shop base currency → se folosește moneda de bază a magazinului (recomandat)
- Use custom currency → se calculează în altă monedă; opțiune avansată, de folosit cu atenție
Custom base currency
Moneda în care se calculează prețurile. Implicit RON.
Se afișează doar dacă ați ales „Use custom currency”.
Fallback price — preț de rezervă când nu există tarif live.
Display a fallback price
Ce se afișează la checkout atunci când tariful real nu poate fi calculat (adresă incompletă, curier indisponibil, problemă tehnică).
Opțiuni disponibile:
- Do not display a fallback price → nu se afișează nimic; clientul nu vede nicio metodă Colete Online
- Display a fallback price if there are issues → prețul de rezervă apare doar la probleme tehnice
- Display a fallback always (even if wrong address) → prețul de rezervă apare inclusiv când adresa este greșită
Fallback price amount
Prețul afișat când nu se poate calcula o ofertă. Se introduce fără TVA.
Se afișează doar dacă prețul de rezervă este activat.
Fallback service name
Numele sub care apare serviciul de rezervă la checkout. Implicit „ColeteOnline”.
Se afișează doar dacă prețul de rezervă este activat.
Free shipping — reguli de livrare gratuită după valoarea comenzii și/sau cupon.
Allow free shipping
Condițiile în care livrarea este oferită gratuit.
Opțiuni disponibile:
- No free shipping → dezactivat
- By amount → gratuit peste o valoare a comenzii
- By coupon → gratuit pe baza unui cupon de transport gratuit din OpenCart
- By amount or coupon → oricare dintre cele două condiții
For order amount bigger than
Valoarea de la care livrarea devine gratuită, calculată fără costul transportului.
Se afișează doar dacă ați ales o variantă bazată pe valoarea comenzii.
Append text for free shipping
Text adăugat după numele curierului atunci când livrarea este gratuită (de exemplu „— livrare gratuită”).
Se afișează doar dacă livrarea gratuită este activată.
Packaging — reguli de ambalare (totul într-un colet sau per produs, plic, dimensiuni implicite).
Packaging method
Cum sunt împachetate produsele comenzii pentru estimarea tarifului și pentru AWB.
Opțiuni disponibile:
- All in a package → toate produsele într-un singur colet
- Each in a package → fiecare produs în coletul lui
Packaging type
Tipul ambalajului declarat curierului.
Opțiuni disponibile:
- Use parcel → colet obișnuit
- Prefer envelope → plic
* Plicul este destinat documentelor și poate anula despăgubirea în caz de pierdere. Folosiți-l doar dacă înțelegeți riscul.
Packages content
Cum este compus textul de conținut trimis curierului.
Opțiuni disponibile:
- Automatically from the product names → din numele produselor din comandă
- Use a fixed content string when the automatically generated string is too big → text fix doar când cel generat automat depășește limita curierului
- Use a fixed content string always → întotdeauna același text fix
Packages content fixed string
Textul fix trimis curierului drept conținut al coletului.
Se afișează doar dacă ați ales una dintre variantele cu text fix.
Default weight (kg)
Greutatea folosită când produsul nu are greutate setată. Implicit 1 kg.
Default width / length / height (cm)
Dimensiunile folosite când produsul nu are dimensiuni setate. Implicit 15 cm pe fiecare latură.
* Valorile implicite sunt doar o plasă de siguranță. O declarare greșită a greutății sau a dimensiunilor duce la taxare suplimentară din partea curierului — completați datele reale pe fiecare produs.
Orders — automatizarea comenzilor (AWB automat, status personalizat, deschidere la livrare, asigurare, referință client, note, link de urmărire).
Trigger courier order on customer order
Generează automat AWB-ul, fără intervenție din admin, când comanda ajunge într-unul dintre statusurile configurate în OpenCart ca „processing” sau „complete”.
Opțiuni disponibile:
- Nu → AWB-ul se creează manual, din pagina comenzii
- Da → AWB-ul se creează automat
Create a custom Shipping status for orders
Adaugă în OpenCart un status de comandă dedicat livrării, pe care comenzile îl pot folosi.
Change order status when AWB is created
Trece automat comanda în statusul de livrare în momentul în care AWB-ul este generat.
Se afișează doar dacă statusul dedicat de livrare este activat.
Default AWB format
Formatul preselectat în lista de descărcare a AWB-ului din pagina comenzii: A4 sau A6 (etichetă). Implicit A4.
Open at delivery
Dacă destinatarul poate deschide coletul la livrare, înainte de a-l accepta.
Opțiuni disponibile:
- Nu → opțiunea nu este oferită
- Always → se solicită pentru toate comenzile
- Let the user decide → clientul alege la checkout
Open at delivery user text
Textul afișat clientului pentru opțiunea de deschidere la livrare.
Se afișează doar dacă opțiunea de deschidere la livrare este activată.
Insurance
Dacă se adaugă asigurare pe comenzile de curier.
Opțiuni disponibile:
- Nu → fără asigurare
- Da → asigurare pe toate comenzile
- Only when no repayment → asigurare doar când comanda nu are ramburs
Client order reference
Referința trimisă curierului pentru comandă. [orderId] este înlocuit cu id-ul comenzii din OpenCart. Implicit „#[orderId]”.
Add custom order note
Notă trimisă curierului la crearea comenzii. Se pot folosi [content] (conținutul coletului) și [skuContent] (conținutul cu coduri SKU).
Add order tracking link to mail
Include linkul de urmărire a coletului în e-mailul trimis clientului.
Advanced — comportamentul formularului de checkout (autocompletare, validare) și câmpurile suplimentare de produs.
Order checkout form
Ce formular de adresă este folosit la checkout.
Opțiuni disponibile:
- Use Colete Online form → formularul Colete Online, cu autocompletare și validare a adresei
- Use default OpenCart form → formularul standard OpenCart, fără autocompletare
* Aproape toate setările de mai jos se aplică numai formularului Colete Online; pe formularul standard OpenCart ele dispar.
Show postal code
Unde este așezat codul poștal în formularul de adresă.
Opțiuni disponibile:
- Before address → înaintea câmpului de adresă
- After address → după câmpul de adresă
- Don't show → ascuns
* Ascunderea funcționează doar cu câmpul de stradă setat pe autocompletare, pentru că de acolo se completează automat codul poștal. Se aplică adreselor din România; o adresă internațională păstrează formatul temei. Excepție: dacă validarea adresei este activă și codul poștal nu se potrivește cu adresa introdusă, câmpul reapare și blochează trimiterea până la corectare.
Validate postal code, city and county before submit
Verifică, înainte de trimiterea comenzii, că respectiva combinație cod poștal / localitate / județ este validă.
Display city field
Cum este afișat câmpul de localitate.
Opțiuni disponibile:
- Display with autocomplete → cu sugestii din baza de localități
- Display OpenCart default field → câmpul standard OpenCart
Auto-select highlighted city suggestion
La ieșirea din câmp, alege automat sugestia evidențiată, fără ca vizitatorul să fie nevoit să dea click pe ea.
Se afișează doar dacă localitatea este afișată cu autocompletare.
Street field type
Cum funcționează câmpul de stradă.
Opțiuni disponibile:
- Display with autocomplete → cu sugestii de străzi
- Display without autocomplete → câmp liber, fără sugestii
- Display OpenCart default field → câmpul standard OpenCart
Auto-select highlighted street suggestion
La ieșirea din câmp, alege automat strada evidențiată în listă.
Se afișează doar dacă strada este afișată cu autocompletare.
Show street number
Dacă se afișează un câmp separat pentru numărul străzii.
Opțiuni disponibile:
- Yes and mandatory → afișat și obligatoriu
- Yes but not mandatory → afișat, dar opțional
- Don't show → ascuns
Use optimized address search
Autocompletare mai rapidă pentru localitate și stradă: caută după o pauză mai scurtă și refolosește rezultatele recente pentru căutări mai înguste, în loc să întrebe serverul la fiecare tastă.
Validate email
Validează adresa de e-mail în timpul checkout-ului.
Validate phone
Validează numărul de telefon în timpul checkout-ului.
Show email field first
Mută câmpul de e-mail pe prima poziție în formularul de checkout.
Show phone field for shipping address
Adaugă un câmp de telefon editabil la pasul de adresă de livrare, astfel încât curierul să primească un număr diferit de cel din contul sau din datele de facturare.
* Pe OpenCart 4 această setare este activată implicit și trebuie să rămână așa: checkout-ul OpenCart 4 nu are câmp propriu de telefon, iar fără ea comanda ajunge fără telefon de contact, caz în care platforma refuză generarea AWB-ului. Setarea nu modifică opțiunile proprii OpenCart pentru telefon din formularul de guest checkout.
Enable advanced product fields
Activează câmpurile suplimentare de livrare în pagina de produs din admin (vezi capitolul 5).
Custom display name for aggregated services
Numele afișat clientului atunci când o comandă necesită mai multe comenzi de curier și acestea sunt prezentate ca o singură opțiune. Implicit „ColeteOnline”.
Delivery to fixed points — harta ColPicker și restricțiile de plată pentru livrarea la punct fix.
Enable locker map picker
Permite clientului să aleagă un locker sau un punct de livrare pe hartă, direct în checkout.
Hide delivery to fixed points for payment methods
Metodele de plată pentru care livrarea la punct fix nu este permisă. Pentru o comandă cu una dintre aceste metode de plată, opțiunile de locker nu mai apar.
Se afișează doar dacă harta de lockere este activată.
Add custom text for restricted payment methods
Afișează un mesaj propriu atunci când livrarea la punct fix este indisponibilă din cauza metodei de plată alese.
Se afișează doar dacă harta de lockere este activată.
Text for restricted payment methods
Mesajul afișat în acest caz.
Se afișează doar dacă mesajul personalizat de mai sus este activat.
Add custom text when products cannot be delivered to fixed points
Afișează un mesaj propriu atunci când comanda conține produse care nu pot fi livrate la locker (de exemplu din cauza dimensiunilor).
Se afișează doar dacă harta de lockere este activată.
Text for not eligible for locker products
Mesajul afișat în acest caz.
Se afișează doar dacă mesajul personalizat de mai sus este activat.
Pe OpenCart 3 setările sunt identice, cu stilul interfeței clasice:
4. Crearea unei comenzi
După instalare, în pagina fiecărei comenzi (Sale → Orders) apare panoul Colete Online. De aici pregătiți și generați AWB-ul: adresa de ridicare și cea de livrare, opțiunile coletului, coletele și ofertele curierilor.
A. Adrese și opțiuni
Adresă ridicare / livrare: preluate automat; adresa de ridicare poate fi schimbată din „Change”.
Repayment value: suma ramburs (plata la livrare) încasată de la client.
Insurance value: valoarea asigurată a coletului.
Package type / Order content: tipul coletului și conținutul declarat.
Open at delivery: permite deschiderea coletului la livrare.
B. Colete și oferte
Verificați coletele (greutate și dimensiuni L × W × H) și apăsați Show offers pentru a vedea ofertele curierilor cu prețuri, ca să alegeți serviciul potrivit.
* Înainte de a genera comanda, completați dimensiunile fiecărui colet. Le puteți preseta pe fiecare produs pentru comenzile viitoare ().
C. Generarea AWB-ului și eticheta
Apăsați Create courier order pentru a genera AWB-ul. După generare, panoul afișează numărul AWB și butonul de descărcare a etichetei (A4 sau A6), iar în istoricul comenzii apare intrarea cu AWB-ul creat.
D. Comenzi suplimentare și AWB automat
Puteți adăuga o comandă de livrare suplimentară pentru aceeași comandă cu Add extra shipping order. De asemenea, din fila Orders a setărilor puteți activa generarea automată a AWB-ului la schimbarea comenzii într-un status de procesare sau finalizare, precum și generarea în masă din lista de comenzi.
5. Setări produse
Pentru estimarea corectă a prețurilor, fiecare produs trebuie să aibă greutatea și dimensiunile (lungime, lățime, înălțime) completate. În OpenCart acestea se setează în pagina produsului (Catalog → Products → Edit), fila Data, secțiunea de dimensiuni și greutate. Valorile completate aici sunt preluate automat în panoul comenzii.
Dacă activați câmpurile avansate de produs din fila Advanced a setărilor, în fila Data a produsului apar opțiuni suplimentare Colete Online: tipul produsului (normal / „white” — colet mare, separat), numărul de cutii și marcarea produsului ca neeligibil pentru livrarea la locker.
Pe OpenCart 3 aceleași câmpuri arată astfel:
6. Checkout — experiența clientului
A. Completarea automată a adresei
La checkout, clienții primesc sugestii pentru localitate, județ și stradă și completarea automată a codului poștal după introducerea adresei. Datele sunt verificate automat, reducând riscul comenzilor refuzate sau livrate greșit. Pentru orașele cu sectoare (de exemplu București) codul poștal este completat în funcție de sector.
B. Tarife live și servicii
Clientul vede tarifele în timp real pentru fiecare serviciu de curierat configurat, inclusiv livrarea la locker.
C. Alegerea lockerului pe hartă
Pentru serviciile cu livrare la locker, clientul deschide harta interactivă (ColPicker) și alege exact punctul de ridicare.
D. Reguli de plată pentru livrarea la locker
Pentru livrarea la punct fix, metodele de plată nepotrivite (de exemplu ramburs în numerar la locker) sunt ascunse automat, cu un mesaj explicativ pentru client.
