Magazin online Medusa România – ghid complet pentru comercianți

Vrei să lansezi un magazin online în România, dar nu găsești o soluție care să combine flexibilitatea unui back‑end headless cu integrarea locală a curierilor și a plăților?

Răspunsul este Medusa: o platformă open‑source care poate fi adaptată rapid la cerințele pieței românești, cu suport pentru curieri, gateway‑uri de plată și emiterea facturilor electronice.

Ce este Medusa și de ce e potrivit pentru România

Arhitectura headless a Medusa

Medusa este o platformă de comerț electronic tip headless, construită pe Node.js și PostgreSQL. Backend‑ul expune un set complet de endpoint‑uri REST și GraphQL, permițând dezvoltatorilor să consume datele prin API‑uri independente de interfața de prezentare. Front‑end‑ul poate fi realizat în orice framework modern – de la Next.js la Vue sau chiar aplicații mobile native – fără a fi legat de un sistem de templating monolitic.

În practică, Medusa separă gestionarea catalogului, comenzilor și utilizatorilor de nivelul de afișare. Astfel, un magazin online poate fi integrat rapid cu site‑uri existente, aplicații de tip PWA sau canale de vânzare precum marketplace‑uri și rețele sociale. Pentru dezvoltatorii români, această separare înseamnă că pot reutiliza codul existent și pot actualiza UI‑ul fără să perturbe logica de business.

Avantajele API‑first și scalabilitatea

Prin designul API‑first, Medusa permite automatizarea fluxurilor de lucru – de exemplu, sincronizarea stocurilor cu ERP‑uri locale sau trimiterea de notificări prin SMS la fiecare comandă. Endpoint‑urile sunt documentate în Swagger și pot fi testate cu Postman, reducând timpul de integrare cu servicii terțe precum sistemele de curierat românesc.

Scalabilitatea este susținută de PostgreSQL și de modelul de microservicii opțional. Pentru traficul sezonier, cum ar fi Black Friday, se pot adăuga noduri suplimentare în clusterul de baze de date și se pot utiliza containere Docker orchestrate prin Kubernetes sau prin serviciile gestionate de Vultr. Această abordare evită blocajele tipic întâlnite la platforme monolitice când cererea crește brusc.

Alinierea cu nevoile comercianților români

Comercianții din România necesită integrarea rapidă cu curieri precum Fan Courier, Urgent Cargus și DHL România, precum și cu procesatori de plată locali (PayU, MobilPay). Fiind API‑first, Medusa permite dezvoltarea de conectori personalizați în câteva ore, folosind documentația publică a acestor furnizori. De asemenea, suportul pentru taxare și TVA conform legislației române poate fi implementat prin middleware în Node.js, fără a modifica codul de bază al platformei.

Platforma este deja utilizată în cadrul altor produse Qubitpage, cum ar fi CarphaCom, care combină Medusa v2 cu integrații locale de curierat și plată. Această experiență demonstrează că Medusa se poate adapta la cerințele specifice pieței românești, oferind în același timp un ecosistem extensibil pentru viitoare funcționalități, cum ar fi AI‑driven recommendation engines sau roboți de gestionare a stocurilor.

Prin adoptarea Medusa, comercianții români beneficiază de o soluție modernă, flexibilă și pregătită pentru creștere, fără a fi constrânși de limitările platformelor tradiționale de tip „all‑in‑one”.

Cum să instalezi Mediva pe un server Vultr

Instalarea Mediva pe un VPS Vultr este rapidă dacă urmezi pașii descriși mai jos. Vom crea un server cu Ubuntu 22.04, vom adăuga Docker și vom lansa containerul oficial Mediva. Pentru referință, poți verifica aplicația CarphaCom din Vultr Marketplace, care folosește aceeași metodă de distribuție Docker.

1. Crearea VPS‑ului. Conectează‑te la contul tău Vultr, selectează “Deploy New Instance”, alege regiunea românească (Bucharest) și imaginea Ubuntu 22.04 LTS. Setează dimensiunea minimă 2 vCPU și 4 GB RAM pentru testare.
2. Acces SSH. După pornire, copiază adresa IP și folosește comanda ssh root@<IP> din terminal. Acceptă cheia de securitate și setează o parolă puternică.
3. Instalarea Docker. Rulează următoarele comenzi în ordine: apt update && apt upgrade -y, apoi apt install -y ca-certificates curl gnupg lsb-release. Adaugă cheia Docker cu curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg și adaugă repository‑ul: echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list. În final, apt update && apt install -y docker-ce docker-ce-cli containerd.io și verifică cu docker run hello-world.
4. Descărcarea imaginii Mediva. Execută docker pull medusajs/medusa:latest. Această imagine conține backend‑ul Mediva, baza de date SQLite implicită și API‑ul REST.
5. Configurarea variabilelor de mediu. Creează un fișier .env în directorul de lucru cu cheile necesare, de exemplu:
   MEDUSA_BACKEND_URL=http://localhost:9000
DATABASE_URL=sqlite://./medusa-db.sqlite
REDIS_URL=redis://redis:6379. Ajustează MEDUSA_BACKEND_URL dacă vei folosi un domeniu propriu.
6. Lansarea containerului. Rulează comanda: docker run -d --name medusa \\ -p 80:80 \\ -v $(pwd)/.env:/app/.env \\ medusajs/medusa:latest. Containerul va porni și va asculta pe portul 80 al VPS‑ului.
7. Verificarea instalării. Deschide browserul și accesează http://<IP>. Ar trebui să vezi mesajul “Medusa server is running”. Poți testa endpoint‑ul /admin cu un client API pentru a confirma funcționalitatea.
8. Configurarea firewall‑ului. Pentru securitate, permite doar porturile 80 și 443: ufw allow 80/tcp && ufw allow 443/tcp && ufw enable. Dacă folosești SSH pe alt port, adaugă regula corespunzătoare.

După acești pași, Mediva este gata pentru personalizare: adăugarea temelor, a plugin‑urilor de plată și a integrărilor cu curierii români. Pentru a gestiona serverul de la distanță, poți consulta secțiunea Remote Management de pe site‑ul Qubitpage.

Tip: Salvează fișierul .env în directorul /etc/medusa și montează-l în container cu opțiunea -v /etc/medusa/.env:/app/.env. Astfel, poți reînnoi variabilele fără a recrea imaginea.

Configurarea catalogului de produse și a variantelor

Medusa expune un API REST complet pentru gestionarea catalogului. Pentru a crea un produs nou, se trimite o cerere POST la /admin/products cu corpul JSON care conține titlul, descrierea, prețul și ID‑urile categoriilor. Un exemplu de comandă curl este:

curl -X POST https://api.example.com/admin/products \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tricou bumbac organic",
    "description": "Tricou 100% bumbac, 5 culori disponibile",
    "price": 1999,
    "status": "published",
    "categories": ["cat_12345"]
}'

După ce produsul a fost creat, se pot adăuga atributele (ex. mărime, culoare) ca options. Pentru fiecare variantă se folosește endpoint‑ul /admin/variants:

curl -X POST https://api.example.com/admin/variants \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tricou - M – Albastru",
    "product_id": "prod_67890",
    "options": [
      {"option_id": "opt_size", "value": "M"},
      {"option_id": "opt_color", "value": "Albastru"}
    ],
    "prices": [{"currency_code": "RON", "amount": 1999}]
}'

Crearea categoriilor se face printr-un POST la /admin/product-categories. Este recomandat să se definească o structură ierarhică (ex. „Îmbrăcăminte > Tricouri”) pentru a facilita navigarea utilizatorilor și filtrarea în interfața de administrare.

Gestionarea atributelor și opțiunilor

Medusa permite definirea de product options (ex. mărime, culoare) prin endpoint‑ul /admin/options. Un exemplu simplu:

curl -X POST https://api.example.com/admin/options \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Culoare",
    "values": ["Roșu","Albastru","Verde"]
}'

După ce opțiunile sunt înregistrate, acestea pot fi asociate produselor în corpul JSON al variantei, așa cum s-a arătat în secțiunea precedentă. Pentru a actualiza o opțiune existentă se folosește PUT /admin/options/{id}, iar pentru a șterge DELETE /admin/options/{id}.

Integrarea cu platforma CarphaCom

Qubitpage oferă servicii de dezvoltare custom pentru sincronizarea catalogului Medusa cu CarphaCom, platforma de e‑commerce bazată pe Medusa v2 și PostgreSQL. Echipa noastră poate implementa webhook‑uri care, la fiecare creare sau actualizare de produs, scriu automat datele în baza de date a CarphaCom, asigurând consistență între front‑end și back‑end.

Un scenariu tipic implică configurarea unui webhook în Medusa:

curl -X POST https://api.example.com/admin/webhooks \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "product.created",
    "url": "https://carphacom.example.com/webhook/medusa"
}'

Webhook‑ul recepționează payload‑ul produsului și, cu ajutorul unui script Python găzduit pe serverul Vultr, inserează în tabelul products al bazei CarphaCom. Pentru variante, se ascultă evenimentul variant.created și se actualizează tabelul product_variants. Acest flux permite comercianților să adauge produse prin API‑ul Medusa și să le vadă instantaneu în catalogul CarphaCom.

Servicii personalizate Qubitpage

De la definirea schemelor de categorii specifice pieței românești, la dezvoltarea de interfețe UI pentru gestionarea rapidă a variantelor, Qubitpage poate extinde API‑ul Medusa cu funcționalități proprii. Pentru detalii despre proiecte similare, vizitați pagina noastră de proiecte sau contactați echipa la contact.

Integrarea curierilor români prin API

1. Obținerea credențialelor și generarea token‑ului

Fiecare curier oferă un portal de dezvoltatori unde se creează o aplicație și se generează un client_id și un client_secret. Pentru Fan Courier, accesați developers.fancourier.ro, creați un cont și salvați cheia API. Urgent Cargus folosește un token static: solicitați-l prin e‑mail la support@urgentcargus.ro. GLS România oferă OAuth 2.0; după înregistrarea pe developer.gls-romania.com, rulați următorul request pentru a obține tokenul:

curl -X POST https://api.gls-romania.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_ID" \
  -d "client_secret=YOUR_SECRET"

Răspunsul conține access_token și durata în secunde; stocați-l în baza de date Medusa (metadata la modelul ShippingOption) pentru reîmprospătare automată.

2. Crearea serviciilor de expediere în Medusa

În directorul src/services adăugați trei fișiere: fanCourierService.ts, urgentCargusService.ts și glsService.ts. Fiecare exportă o funcție createShipment(order) care:

• Formatează adresa conform cerințelor API‑ului (ex. city, county, postal_code).
• Trimite un POST la endpointul de creare a coletului (/api/v1/shipments pentru Fan Courier, /v2/awb pentru Urgent Cargus, /shipments pentru GLS).
• Salvează numărul de tracking în câmpul shipping_data.tracking_number al comenzii.

Exemplu de request pentru Fan Courier:

curl -X POST https://api.fancourier.ro/v2/shipments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "recipient": {
          "name": "Ion Popescu",
          "address": "Str. Exemplu 10",
          "city": "București",
          "county": "București",
          "postal_code": "010101"
        },
        "package": {"weight": 2.5, "dimensions": "30x20x10"},
        "service": "standard"
      }'

3. Configurarea webhook‑urilor pentru statusul livrărilor

Vultr permite expunerea rapidă a unui endpoint public printr-un server Node.js pe portul 80. În Medusa, adăugați un router în src/api/routes/webhooks.ts și înregistrați-l în apiRoot. Pentru fiecare curier, specificați URL‑ul în portalul lor:

• Fan Courier: https://your‑domain.com/api/webhooks/fancourier
• Urgent Cargus: https://your‑domain.com/api/webhooks/urgentcargus
• GLS: https://your‑domain.com/api/webhooks/gls

Payload‑ul conține câmpuri precum tracking_number, status și timestamp. În handler, actualizați câmpul shipping_data.status al comenzii și declanșați un eveniment Medusa (order.updated) pentru a notifica utilizatorul prin e‑mail.

4. Testarea integrării în mediul de dezvoltare

Folosiți mediul Developer Edition al CarphaCom disponibil pe Vultr Marketplace pentru a replica un server de producție. În .env, setați variabilele FAN_COURIER_TOKEN, URGENT_CARGUS_TOKEN și GLS_CLIENT_ID/SECRET. Rulați comanda:

npm run test:webhooks -- --service=fancourier --order=12345

Verificați în interfața admin a Medusa că statusul comenzii trece de la pending la shipped și că tracking‑ul este vizibil în pagina clientului.

Tip: Pentru a evita expirarea token‑urilor, implementați un job cron care rulează la fiecare 55 de minute și reînnoiește tokenul prin același endpoint de autentificare. În Medusa, adăugați scriptul în src/jobs/refreshTokens.ts și programați-l cu node-cron.

După ce webhook‑urile confirmă livrările, actualizați pagina Contact cu un mesaj de confirmare pentru clienți și includeți linkuri spre CarphaCom Remote pentru monitorizarea în timp real a comenzilor.

Comparativ: soluții de plată și facturare pentru Medusa în România

În România, alegerea unei soluții de plată trebuie să țină cont de comisioanele percepute, suportul local și calitatea documentației API. Stripe oferă o platformă globală cu integrare rapidă în Medusa, dar costurile de tranzacție sunt mai mari decât la furnizorii locali. PayU și MobilPay, deși au comisioane mai mici, necesită configurări suplimentare pentru a respecta reglementările locale privind 3‑DS și tokenizarea.

Integrarea cu sistemele de facturare electronică (e‑Factura) este obligatorie pentru majoritatea firmelor din România. Cele mai folosite gateway‑uri oferă module de emitere automată a facturilor, dar nivelul de documentație variază. Stripe furnizează ghiduri în limba engleză, în timp ce PayU și MobilPay includ documentație în română și suport telefonic dedicat.

Pentru comercianții care doresc să mențină totul pe un singur stack, Qubitpage recomandă combinarea PayU cu un furnizor de e‑Factura precum CarphaCom Remote, care se integrează nativ cu Medusa și permite generarea automată a facturilor în format XML conform ANAF.

În practică, comercianții cu volume mari de comenzi preferă PayU datorită costului redus și a suportului local în limba română. Pentru start‑up‑uri care vizează piețe internaționale, Stripe rămâne o alegere viabilă, cu condiția să se implementeze un modul separat pentru emiterea facturilor.

Orice soluție aleasă trebuie să fie testată în mediul de dezvoltare Medusa, apoi să fie validată în sandbox‑ul furnizorului de plată. Pentru ghiduri detaliate de configurare, consultați secțiunea Remote Integration de pe site‑ul Qubitpage.

Testarea și lansarea magazinului în producție

Verificarea fluxului de comandă

Înainte de a deschide magazinul, creează un cont de client de test și plasează o comandă completă. Folosește metoda de plată integrată (ex. PayU sau Stripe) și asigură-te că pagina de checkout redirecționează corect spre confirmarea comenzii. Verifică că starea comenzii trece de la pending la awaiting_fulfillment în panoul de administrare Medusa.

Deschide consola de dezvoltare și urmărește răspunsurile API pentru /admin/orders și /store/orders. Orice eroare 4xx/5xx trebuie rezolvată înainte de lansare.

Simularea livrărilor cu CarphaCom Robotised

Integrarea cu CarphaCom Robotised permite simularea completă a procesului de livrare în medii de tip warehouse. Pornește simulatorul NVIDIA Isaac Sim și rulează scenariul order_fulfillment.yaml furnizat în repository‑ul GitHub. Verifică că robotul preia pachetul, îl scanează și transmite statusul shipped către Medusa prin webhook.

Dacă nu dispui de GPU dedicat, poți utiliza serviciul Cloud Vultr cu plan GPU și să rulezi scriptul de inițializare disponibil în Carpathron Remote. Monitorizează log‑urile din dashboard‑ul CarphaCom pentru a confirma că fiecare pas este înregistrat.

Generarea și verificarea facturii

După confirmarea livrării, Medusa declanșează generarea facturii prin modulul de facturare configurat (ex. Facturis sau invoicex). Descarcă PDF‑ul și verifică:

• datele fiscale ale companiei (CUI, adresă, IBAN)
• lista de produse, cantitățile și prețurile unitare
• calculul TVA‑ului conform legislației românești (19% pentru majoritatea bunurilor)
• totalul final și termenul de plată

Testează și funcționalitatea de retransmisie a facturii prin e‑mail, asigurându‑te că antetul și footerul conțin link‑urile de contact și politica de returnare.

Monitorizare în producție cu Carpathron Remote

După lansare, activează monitorizarea în timp real cu Carpathron Remote. Instalează agentul pe serverul Vultr folosind comanda:

curl -sSL https://raw.githubusercontent.com/qubitpage/carpathron-remote/main/install.sh | bash

Agentul colectează metrici de performanță (CPU, memorie, I/O) și evenimente Medusa (order_created, order_fulfilled). Configurează alerte prin webhook către Slack sau Telegram pentru a fi notificat instantaneu în caz de eșec.

Checklist final

1. Flux de comandă: testare completă cu plată și confirmare.
2. Livrare simulată: rulare scenariu CarphaCom Robotised și verificare webhook‑uri.
3. Factură: generare PDF, verificare date fiscale și trimitere e‑mail.
4. Backup: crearea snapshot‑ului bazei de date PostgreSQL pe Vultr.
5. Monitorizare: instalare Carpathron Remote și configurare alerte.
6. DNS & SSL: confirmare că domeniul are certificat Let’s Encrypt activ și redirecționare HTTPS.
7. Documentație: actualizare pagină Contact cu informații de suport și SLA.

Odată ce toate punctele de pe checklist sunt bifate, poți publica magazinul și începe să primești comenzi reale. Continuă să revizuiești log‑urile zilnice și să ajustezi parametrii de performanță pe măsură ce volumul de trafic crește.

Frequently asked questions

Cum pot adăuga un curier nou în Medusa dacă nu există un plugin oficial?

În primul rând, creează un modul de tip shipping provider în directorul src/modules al proiectului tău Medusa. În fișierul respectiv, implementează funcțiile calculatePrice și validateAddress conform API‑ului curierului ales, apoi înregistrează provider‑ul în medusa-config.js. După repornirea serverului, curierul va apărea în panoul de administrare și poate fi selectat la checkout.

Ce diferență există între planul Pro și Max al Carpathron Remote pentru suport tehnic la instalare?

Planul Pro oferă acces la suport prin ticket cu timp de răspuns de 24 de ore și asistență pentru configurarea de bază a bazei de date și a mediului de dezvoltare. Planul Max adaugă suport telefonic 8/5, intervenție pe server în timp real și configurarea avansată a integrărilor cu curieri și gateway‑uri de plată. Astfel, Max este orientat spre implementări complexe și lansări rapide.

Este posibil să folosesc Medusa cu un front‑end React în loc de Next.js?

Da. Medusa expune un API REST și GraphQL care poate fi consumat de orice aplicație front‑end, inclusiv un proiect creat cu create‑react‑app. Trebuie să configurezi autentificarea prin token și să implementezi endpoint‑urile de produse, coș și checkout în componentele React. Pentru SEO, poți adăuga server‑side rendering cu frameworks ca Remix sau Vite‑SSR.

Cum pot genera automat facturi electronice în format XML pentru ANAF?

Instalează pachetul medusa-plugin-anaf-invoice (disponibil pe GitHub) și configurează‑l în medusa-config.js cu certificatul digital și codul fiscal al companiei. La finalizarea comenzii, plugin‑ul creează un fișier XML conform standardului e‑Factura și îl trimite către API‑ul ANAF printr-un request HTTPS. Poți salva copia locală în bucket‑ul S3 pentru arhivare.

Ce opțiuni de hosting recomandă Qubitpage pentru un magazin cu trafic mediu?

Qubitpage sugerează utilizarea unui VPS cu 4 vCPU, 8 GB RAM și SSD de 100 GB, disponibil pe Vultr sau DigitalOcean, pentru a asigura scalabilitatea la creșterea sesiunilor de checkout. Se recomandă configurarea unui cluster Docker cu Nginx ca reverse proxy și PostgreSQL dedicat, plus un CDN pentru active statice. Pentru backup și monitorizare, Qubitpage configurează snapshot‑uri zilnice și alertă prin Grafana/Prometheus.

Concluzie – Medusa este alegerea potrivită pentru comerțul online în România

Implementarea Medusa pe platforma CarphaCom oferă un control complet asupra catalogului, stocurilor și procesului de checkout, fără a depinde de servicii terțe. Utilizând PostgreSQL pentru datele critice și Next.js pentru interfața rapidă, comercianții pot scala fără întreruperi și pot adapta rapid fluxurile de lucru la cerințele locale, inclusiv integrarea cu curierii și metodele de plată românești.

Configurarea inițială pe Vultr Marketplace simplifică instalarea, iar documentația oficială a Medusa v2 permite adăugarea de webhook‑uri personalizate pentru notificări de livrare și actualizări de inventar. Prin adoptarea unei arhitecturi headless, echipele pot dezvolta experiențe mobile sau desktop independente, menținând în același timp un singur backend coerent.

În final, Medusa combină flexibilitatea open‑source cu suportul specializat al Qubitpage, facilitând tranziția rapidă la comerțul digital și reducând costurile operaționale. Pentru a începe implementarea sau pentru consultanță tehnică, vizitați pagina noastră de produse.