ErpGeneral-Sedona

Pluginul ErpGeneral permite integrarea platformei Gremini cu sisteme ERP externe. Acest document descrie integrarea cu Sedona ERP — un sistem de gestiune comerciala utilizat pentru managementul clientilor, comenzilor, facturilor si produselor.

Prin integrarea Sedona, comenzile plasate in platforma sunt transmise automat in ERP, clientii sunt sincronizati, iar facturile generate in Sedona sunt descarcate si atasate comenzii in platforma.

Functionalitati principale

Sincronizare clienti — clientul este cautat in Sedona dupa external_id; daca nu exista, este creat automat
Trimitere proforma — comanda este trimisa in Sedona ca rezervare/proforma; ID-ul Sedona este salvat in platforma
Descarcare factura — factura emisa in Sedona pentru comanda respectiva este preluata si generata ca PDF, atasata comenzii
Sincronizare produse — produsele sunt identificate in Sedona dupa codul de bare; maparea este salvata local
Automatizare bazata pe evenimente — modificarile comenzii (produse, adresa, status, transport gratuit) declanseaza automat actualizari in Sedona

Configurare

Pasul 1 — Instalarea pluginului

Din Setari Magazin → Plugin-uri, cautati ErpGeneral si apasati Instalează.

Pasul 2 — Selectarea ERP-ului Sedona

Dupa instalare, intrati in setarile pluginului si selectati Sedona ca ERP activ pentru magazin.

Pasul 3 — Completarea credentialelor API

In setarile pluginului completati urmatoarele campuri:

Setare	Descriere
`SEDONA_API_URL`	URL-ul de baza al API-ului Sedona (ex: `https://erp.domeniu.ro/api`)
`SEDONA_API_USERNAME`	Utilizatorul pentru autentificare in Sedona
`SEDONA_API_PASSWORD`	Parola pentru autentificare in Sedona
`SEDONA_ADMINISTRATION_ID`	ID-ul gestiunii/administratiei din Sedona
`SEDONA_USER_ID`	ID-ul utilizatorului Sedona care efectueaza operatiunile
`SEDONA_MEASURING_UNIT_ID`	ID-ul unitatii de masura implicite din Sedona

Toate cele 6 campuri sunt obligatorii pentru functionarea integrararii.

Pasul 4 — Maparea produselor

Inainte de a trimite prima comanda, produsele din platforma trebuie mapate cu cele din Sedona.

Mergeti la Inventar → Set mappings for Sedona.

Maparea se face automat prin codul de bare al produsului:

Produsul este cautat in Sedona dupa campul code (codul de bare)
Daca este gasit, ID-ul Sedona este salvat local in tabelul erp_products
Daca produsul nu are cod de bare sau nu este gasit in Sedona, trimiterea comenzii va esua cu o eroare explicita

Important: Fiecare produs din comanda trebuie sa aiba un cod de bare valid si sa existe in Sedona inainte de prima trimitere.

Fluxul unei comenzi

1. Plasarea comenzii

La crearea unei comenzi noi in backend, pluginul poate fi configurat sa trimita automat proforma in Sedona. Clientul este sincronizat in prealabil.

2. Sincronizare client

Clientul este cautat in Sedona dupa external_id (ID-ul clientului din platforma). Daca nu exista, este creat. ID-ul Sedona al clientului este salvat ca nota pe comanda.

3. Trimitere proforma

Comanda este trimisa in Sedona ca rezervare. Sedona returneaza un ID de comanda care este stocat in platforma (tabel erp_order). In acest moment comanda are statusul proforma in ERP.

4. Emiterea facturii (in Sedona)

Factura se emite din interfata Sedona de catre operatorul ERP. Platforma nu emite factura — doar o preia dupa ce a fost creata in Sedona.

5. Descarcarea facturii

Dupa emiterea facturii in Sedona, aceasta poate fi descarcata in platforma:

Manual — din pagina comenzii, butonul „Download order invoices from Sedona"
Manual — butonul „Fetch invoice from Sedona manually"

Factura este generata ca PDF si atasata comenzii ca document extern. De asemenea, este incarcata pe S3 (daca este configurat) si se declanseaza evenimentul EVENT_ORDER_DOCUMENT_UPLOADED.

Actiuni disponibile in pagina comenzii

Din pagina unei comenzi din backend, sectiunea ERP expune urmatoarele butoane de actiune:

Actiune	Descriere
Send order to Sedona	Trimite comanda in Sedona ca proforma (rezervare)
Fetch invoice from Sedona manually	Preia factura emisa in Sedona pentru aceasta comanda
Send customer to Sedona manually	Sincronizeaza manual clientul comenzii in Sedona
Download order invoices from Sedona	Descarca toate facturile Sedona asociate comenzii

Automatizari bazate pe evenimente

Pluginul asculta urmatoarele evenimente din platforma si actioneaza automat:

Eveniment	Actiune
Comanda noua creata in backend	Trimitere automata proforma in Sedona
Produse modificate pe comanda	Actualizare comanda in Sedona + retransmitere proforma
Adresa comenzii modificata	Actualizare comanda in Sedona
Locker-ul comenzii modificat	Actualizare comanda in Sedona
Comanda modificata	Actualizare comanda in Sedona
Status comanda schimbat	Reactie configurabila (ex: trimitere automata)
Transport gratuit modificat	Actualizare comanda in Sedona
Comanda de retur plasata	Trimitere automata proforma pentru retur

Structura tehnica

Integrarea este construita in shared/plugins/ErpGeneral/lib/Service/ERP/Sedona/ si urmeaza o arhitectura in straturi:

Sedona/
├── DTO/           — obiecte de transfer date (Order, Customer, Invoice, Product, Vat, Department...)
├── Handler/       — comunicare directa cu API-ul Sedona (request/response per entitate)
├── Mapper/        — transformare date platforma ↔ format Sedona
├── Service/       — logica de business (InvoiceGenerator, ProductSynchronizer, NameCleaner)
└── Enum/          — constante pentru cheile de configurare

Handler-ele disponibile:

Handler	Endpoint Sedona
`CustomerHandler`	`/clienti/get`, `/clienti/add`
`OrderHandler`	`/comenzi/get`, `/comenzi/add`
`InvoiceHandler`	`/facturi/get`
`ProductHandler`	`/produse/get`
`VatHandler`	gestionare cote TVA
`DepartmentHandler`	gestionare departamente/categorii
`MeasuringUnitHandler`	unitati de masura

Note importante

Daca pentru o comanda exista mai mult de o factura in Sedona, descarcarea va esua cu eroare explicita — situatia trebuie rezolvata direct in Sedona.
Liniile duplicate din factura (acelasi lineId) sunt deduplicate automat la descarcare.
Daca un produs din comanda nu are cod de bare sau nu este mapat in Sedona, trimiterea proformei va fi blocata cu eroare.
Sincronizarea clientului este disponibila si ca task de fundal (UpsyncCustomerFromOrderToErp) pentru executie asincrona.
Numele produselor sunt procesate de serviciul NameCleaner inainte de a fi trimise in Sedona, pentru a evita caractere invalide.

Functionalitati principale​

Configurare​

Pasul 1 — Instalarea pluginului​

Pasul 2 — Selectarea ERP-ului Sedona​

Pasul 3 — Completarea credentialelor API​

Pasul 4 — Maparea produselor​

Fluxul unei comenzi​

1. Plasarea comenzii​

2. Sincronizare client​

3. Trimitere proforma​

4. Emiterea facturii (in Sedona)​

5. Descarcarea facturii​

Actiuni disponibile in pagina comenzii​

Automatizari bazate pe evenimente​

Structura tehnica​

Note importante​