Integrarea MPL¶

MPL este serviciul de colete al Magyar Posta, operatorul poștal maghiar. Modulul eyssen_delivery_mpl conectează direct un magazin online și un depozit Odoo la API-ul MPL v2: clienții aleg la finalizarea comenzii între livrarea la domiciliu și ridicarea de la un punct de colete MPL (Csomagautomata, PostaPont sau Postán maradó), depozitul tipărește etichete de expediere PDF în format A6 direct din comanda de livrare, stările de urmărire sunt sincronizate automat cu catalogul de evenimente de urmărire MPL, iar o metodă de plată dedicată MPL COD, cu ramburs (COD), transmite suma de încasat împreună cu fiecare etichetă.

Vezi și

Configurare cont¶

Expedierea prin MPL necesită un contract comercial cu Magyar Posta și acces la API-ul MPL v2. Integrarea se autentifică prin acreditări de client OAuth2, deci următoarele valori trebuie obținute de la Magyar Posta înainte de configurarea Odoo:

o pereche Client ID / Client Secret pentru mediul de test (sandbox);
o pereche Client ID / Client Secret pentru mediul de producție;
codul contabil al clientului (Vevőkód), trimis împreună cu cererile API pentru expedieri și puncte de colete;
numărul de acord din opt caractere (Megállapodásszám) al contractului Magyar Posta.

Sfat

Începeți cu datele de autentificare de test și cu comutatorul Mediu setat pe Test. Modulul comunică apoi cu sandbox-ul Magyar Posta, astfel încât etichetele și expedierile create în timpul testării nu intră niciodată în rețeaua MPL reală. Comutați transportatorul pe Production doar după ce fluxul a fost verificat de la un capăt la altul.

Configurare metodă de livrare¶

Două metode de expediere vin preconfigurate cu modulul: Punct de colete MPL (ridicare dintr-un punct de colete) și Livrare la domiciliu MPL. Pentru a le consulta sau a crea una, accesați Stoc ‣ Configurare ‣ Metode de livrare și setați câmpul Furnizor la MPL. În acest fel, pe formular apar două file suplimentare: fila Configurare MPL și fila Prețuri.

Pentru câmpurile generice comune tuturor transportatorilor — cum ar fi Livrare produs, disponibilitatea pe Țări sau pragul de gratuitate — consultați Conectori de transportatori.

Notă

Pentru a genera etichete de expediere MPL la validarea unei comenzi de livrare, setați opțiunea Nivel de integrare la Obține preț și creează livrare. Etichetele pot fi create și manual, în orice moment, cu butonul Tipărește eticheta MPL de pe transfer.

screenshot: setup-configuration-mpl-configuration-tab

menu: Inventory ‣ Configuration ‣ Delivery Methods ‣ MPL Home delivery
shows: An MPL shipping method form with Provider set to "MPL" and the "MPL Configuration" tab open, showing the Test and Production Client ID/Secret pairs, the Accounting Code and the Agreement Number.
highlight: The "MPL Configuration" tab (red frame).
data: Shipping method "MPL Home delivery"; use throw-away credentials.
module: eyssen_delivery_mpl
notes: English UI, light theme, 1440px width.

Date de autentificare¶

Câmpurile din fila Configurare MPL sunt vizibile doar utilizatorilor cu drepturi Administrare: Setări:

ID client test / Secret client test: perechea de acreditări sandbox, utilizată cât timp Mediu al transportatorului este setat pe Test.
ID client producție / Secret client producție: perechea de acreditări live, utilizată în Production. Secretele sunt mascate pe ecran.
Accounting Code (Vevőkód): codul contabil de client Magyar Posta, transmis ca antet la înregistrarea expedierilor și la interogările catalogului de puncte de colete.
Agreement Number (Megállapodásszám): numărul de contract din opt caractere, transmis ca acord al expeditorului la fiecare expediere.

Dacă o etichetă este creată sau o sincronizare este declanșată manual fără acreditări pentru mediul activ, operațiunea se oprește cu un mesaj de eroare explicit. Sincronizarea planificată a catalogului înregistrează eroarea în jurnal și reîncearcă la următoarea rulare.

Tipuri de livrare¶

Câmpul Tip de livrare din fila Configurare MPL stabilește comportamentul transportatorului:

	Livrare la domiciliu	Punct de ridicare
Destinație	Adresa de livrare a clientului.	Un punct de colete MPL ales de client.
Finalizarea comenzii	Se comportă ca orice alt transportator.	Deschide selectorul de puncte de colete; comanda nu poate fi confirmată până când nu este ales un punct.
Etichetă	Înregistrată ca expediere cu livrare la domiciliu.	Înregistrată pentru ridicare de la punctul selectat, folosind tipul de serviciu al punctului.

Un punct de colete este unul dintre cele trei tipuri de puncte de serviciu MPL, toate oferite împreună în selector:

Csomagautomata (automat de colete) — un locker automat, de regulă disponibil non-stop;
Postán maradó (păstrare la oficiul poștal) — coletul este păstrat pentru ridicare la un oficiu poștal;
PostaPont — un punct de ridicare cu personal, de obicei operat de partenerii de retail ai Magyar Posta.

Tipul punctului ales de client este stocat pe comanda de vânzare împreună cu identificatorul și numele punctului și este transmis către MPL la crearea etichetei.

Opțiunea Creează adresă de livrare pentru punctul de ridicare (dezactivată implicit, doar pentru transportatorii cu puncte de colete) face ca magazinul online să creeze, sub client, o adresă de livrare separată pentru punctul de colete ales și să o seteze ca adresă de livrare a comenzii. Când clientul trece ulterior la o altă metodă de livrare, adresa de livrare revine la client, iar adresa temporară a punctului de colete este curățată automat.

Stabilirea prețurilor¶

Fila Prețuri, adăugată de modul, acceptă două moduri de stabilire a prețurilor:

Prețuri pe intervale: adăugați una sau mai multe Reguli de preț (după greutate, volum, preț sau cantitate). Regulile sunt evaluate în ordine, iar prima regulă care se potrivește stabilește prețul de expediere; dacă nicio regulă nu se potrivește, metoda rămâne afișată la finalizarea comenzii, dar nu poate fi selectată — Odoo afișează Not available for current order.
Preț fix de rezervă: atunci când nu este definită nicio regulă de preț, prețul de expediere este prețul de vânzare al produsului Livrare produs al metodei, stabilit prin lista de prețuri a comenzii; câmpul Preț fixat modifică prețul de vânzare de bază al acelui produs, iar regulile listei de prețuri aplicate produsului de livrare îl înlocuiesc pentru fiecare listă de prețuri.

Mecanismele standard ale transportatorului — pragul de gratuitate, marjele și taxele — se aplică peste ambele moduri, exact ca pentru orice altă metodă de expediere.

Notă

Selectarea oricărei metode MPL la finalizarea comenzii adaugă pe comandă și o linie de produs Serviciu de manipulare (preț de vânzare implicit: 2 000 în moneda companiei — adică 2 000 HUF într-o bază de date maghiară — stabilit prin lista de prețuri a comenzii). Linia este eliminată automat când clientul trece la o metodă non-MPL. Pentru a dezactiva acest supliment, setați prețul de vânzare al produsului Handling service la 0.

Ramburs (plata la livrare)¶

Modulul include un furnizor de plată numit MPL ramburs, cu cardul la punctul de colete sau la livrare. Ca orice furnizor, trebuie activat și publicat înainte de a apărea la finalizarea comenzii și este oferit doar când site-ul are o metodă de expediere MPL publicată, iar coșul conține produse fizice.

Suma de încasat este calculată pentru fiecare livrare (transfer) de ieșire — expedierile parțiale, liniile de servicii și plățile în avans facturate sunt toate tratate de calculul comun descris în Plata ramburs (COD), iar rezultatul este stocat în câmpul Sumă ramburs al transferului.
Suma este transmisă ca număr întreg: comenzile în HUF sunt trimise ca atare; comenzile în altă monedă sunt convertite în HUF la cursul valutar curent la crearea etichetei, iar codul monedei comenzii este transmis alături de sumă. Verificați cu Magyar Posta comenzile COD în valută înainte de a vă baza pe acest comportament.
Câmpul Cont bancar ramburs din fila Configurare MPL este trimis ca cont de plată pentru sumele încasate.
Metodele de plată oferite împreună cu fiecare metodă de expediere MPL — precum și experiența de finalizare a comenzii specifică rambursului — sunt controlate de filtrarea plăților pentru fiecare transportator, descrisă în Metode de plată în funcție de livrare. În configurația implicită, transportatorii MPL livrați permit doar propriul furnizor COD — atât timp cât nu este activat furnizorul COD al altui transportator, deoarece furnizorii COD sunt validați separat (vezi Metode de plată în funcție de livrare) — așa că adăugați furnizorii de plată prin card sau transfer bancar ai magazinului la transportatori pentru a oferi o alegere.

Important

Când o expediere COD este împărțită în mai multe pachete, integrarea curentă transmite suma COD integrală cu fiecare pachet. Expediați comenzile COD ca un singur pachet sau verificați cu Magyar Posta cum se încasează expedierile COD cu mai multe pachete, pentru a evita taxarea în exces a clientului.

Validarea numărului de telefon¶

MPL necesită un număr de mobil sau de telefon maghiar valid pentru fiecare expediere. La crearea unei etichete, modulul ia numărul Mobil al adresei de livrare, apoi numărul Telefon, apoi recurge la contactul părinte și normalizează rezultatul în formatul internațional +36 (numerele introduse cu prefixul național 06 sunt convertite automat). Dacă nu se găsește niciun număr sau numărul nu este maghiar, crearea etichetei se oprește cu o eroare de blocare — sub acest aspect, integrarea este destinată exclusiv pieței interne.

Catalogul de puncte de colete¶

Selectorul din magazinul online nu interoghează Magyar Posta la fiecare vizualizare de pagină. În schimb, modulul păstrează un catalog local al tuturor punctelor de colete MPL (nume, adresă, coordonate și tip de punct de serviciu), menținut la zi de acțiunea planificată zilnică MPL: Sincronizare locuri de livrare:

lista completă a locațiilor Csomagautomata, Postán maradó și PostaPont este descărcată din API-ul MPL, folosind acreditările unei metode de expediere MPL configurate;
intrările existente sunt actualizate pe loc, cele noi sunt adăugate, iar punctele care nu mai există la Magyar Posta sunt eliminate;
fiecare intrare consemnează când a fost sincronizată ultima dată.

O comandă care stochează deja un punct ales continuă să funcționeze chiar dacă acel punct dispare ulterior din catalog — identificatorul și numele punctului sunt copiate pe comandă în momentul selectării.

Sfat

Imediat după instalare, catalogul este gol până la prima rulare a acțiunii planificate. Selectorul din backend ajută în această situație: căutarea după cod poștal sau oraș preia în timp real punctele corespunzătoare din API-ul MPL și le stochează local.

Finalizarea comenzii pe site: alegerea unui punct de colete¶

Când un client selectează la finalizarea comenzii o metodă de expediere MPL cu punct de colete, se deschide imediat un selector pe tot ecranul, iar finalizarea comenzii nu poate continua până când nu este ales un punct — până atunci, sub metoda de expediere este afișat un avertisment. Punctul selectat este afișat sub metodă, stocat pe comandă și restaurat automat când clientul revine ulterior la finalizarea comenzii.

Selectorul are două moduri, stabilite prin configurarea site-ului:

	Widget cu hartă	Listă cu căutare
Cerință	Cheie API Google Maps setată în setările site-ului	niciuna (implicit)
Interfață	Widgetul de hartă oficial PostaPont al Magyar Posta, pe o hartă Google	Listă încorporată cu filtre de tip (Csomagautomata / Postán maradó / PostaPont), căutare text și paginare
Sursa datelor	Încărcate în timp real de la Magyar Posta	Catalogul local de puncte de colete
Tipul punctului de serviciu	Nu este furnizat de widget — expedierile sunt înregistrate cu modul de livrare generic PostaPont	Stocat odată cu selecția și transmis către MPL

Pentru a activa modul cu hartă, accesați Site web ‣ Configurare ‣ Setări, găsiți blocul MPL și introduceți o Cheie API Google Maps. Lăsați cheia necompletată pentru a utiliza lista cu căutare, care nu necesită niciun serviciu extern în afara sincronizării zilnice a catalogului.

Utilizatorii din back-office pot alege sau modifica punctul fără magazinul online: atât comanda de vânzare, cât și transferul afișează un câmp Punct de colete MPL cu un buton Selectați pe hartă care deschide dialogul Selectați punctul de colete MPL — o listă cu căutare, cu filtrele Locker de colete, Păstrare la oficiul poștal și PostaPont. Câmpul se blochează după ce expedierea a fost înregistrată la MPL sau comanda este finalizată ori anulată.

Etichete de expediere¶

Etichetele sunt generate în format PDF A6, gata pentru imprimantele de etichete:

Cu Nivel de integrare setat la Obține preț și creează livrare, validarea comenzii de livrare înregistrează automat expedierea la MPL.
Butonul Tipărește eticheta MPL de pe transfer creează manual expedierea în orice moment; el dispare după ce există o etichetă.
În caz de succes, transferul stochează ID colet MPL, Număr colet MPL (când expedierea este înregistrată prin validarea transferului, numărul este copiat și în referința standard de urmărire; butonul manual Tipărește eticheta MPL completează doar câmpurile MPL) și Etichetă MPL descărcabilă, iar PDF-ul etichetei este atașat în chatter-ul transferului împreună cu numărul de urmărire.

Când produsele sunt ambalate în mai multe pachete, se înregistrează un colet pentru fiecare pachet, iar greutatea de expediere a fiecărui pachet este transmisă individual (greutățile sunt trimise în grame, cu un minim de 100 g și o valoare implicită de 1 kg când nu este setată nicio greutate). Când MPL returnează numere de urmărire pentru fiecare pachet, fiecare înregistrare de pachet stochează propriul număr, astfel încât coletele pot fi urmărite individual; în caz contrar, pachetele împart numărul de urmărire al expedierii.

Important

Tipărește eticheta MPL nu este un buton de retipărire. Apăsarea lui șterge datele coletului stocate și înregistrează la MPL o expediere nouă. Din acest motiv, este ascuns după ce există o etichetă; reînregistrarea unei expedieri este oferită doar utilizatorilor cu modul dezvoltator activat. Pentru a retipări o etichetă existentă, descărcați în schimb fișierul Etichetă MPL stocat sau atașamentul din chatter.

Notă

Adresa expeditorului transmisă către MPL este întotdeauna adresa companiei, nu adresa depozitului. Comercianții care expediază din mai multe depozite apar față de MPL sub adresa înregistrată a companiei.

Urmărire și stări¶

Modulul include catalogul de evenimente de urmărire MPL — 46 de stări în fazele de preluare, procesare, transport și livrare — ca înregistrări editabile în Stoc ‣ Configurare ‣ Stări livrare MPL, fiecare având Cod județ, Categorie stare, Nume stare MPL și o casetă Stare livrat.

Stările sunt reîmprospătate automat de două acțiuni planificate, fiecare rulând la fiecare trei ore:

Transfer: Actualizează informațiile de urmărire MPL interoghează fiecare transfer care are un număr de colet MPL și nu este încă finalizat sau anulat;
Colet: Actualizează informațiile de urmărire MPL interoghează pachetele individuale, până la 50 la fiecare rulare, distanțând verificările repetate ale aceluiași pachet conform Interval de verificare a urmăririi configurat (implicit: 60 de minute).

Cea mai recentă stare, codul ei și marcajul de timp sunt afișate pe transfer (Stare colet, Cod stare colet, Data stării coletului) și pe fiecare pachet; transferul are și un buton Actualizează starea MPL pentru reîmprospătare la cerere.

Două automatizări se bazează pe catalogul de stări:

Data livrării: când un eveniment de urmărire corespunde unei stări a cărei casetă Stare livrat este bifată, data la care clientul a primit efectiv bunurile este înscrisă pe transfer (data efectivă a primirii de către client), folosind marcajul de timp al livrării raportat de MPL. Aceasta alimentează progresul livrării la nivel de comandă, descris în Starea și datele livrării.
Validare automată: pe tipul de operație (Stoc ‣ Configurare ‣ Tipuri operațiuni), grupul Validare la livrarea MPL oferă Validează transferul la livrare împreună cu o listă Validează la stările MPL. Când fiecare pachet al unui transfer ajunge într-una dintre stările selectate, transferul este validat automat. Acest lucru permite un flux cu validare amânată: lăsați comanda de livrare deschisă după tipărirea etichetei, lăsați acțiunile planificate să urmărească coletul și permiteți ca Odoo să închidă transferul când MPL raportează livrarea.

Atenționare

Când utilizați fluxul cu validare amânată, setați Nivel de integrare al metodei de expediere la Obține preț (sau debifați Generează etichete de expediere pe tipul de operație). Cu Obține preț și creează livrare, validarea automată înregistrează expedierea la MPL a doua oară, deoarece butonul Tipărește eticheta MPL nu completează referința standard de urmărire care suprimă înregistrarea din momentul validării.

Important

Niciuna dintre cele 46 de stări livrate nu este presetată ca livrată. Bifați Stare livrat pe rândurile terminale Kézbesített (livrat) după instalare — altfel nici înscrierea datei livrării, nici o configurare de validare automată bazată pe livrare nu are efect.

Notă

Acțiunea planificată la nivel de transfer omite în mod deliberat transferurile deja finalizate. Dacă livrările sunt validate imediat la momentul expedierii, urmărirea se reîmprospătează doar prin acțiunea la nivel de pachet și prin butonul manual Actualizează starea MPL.

Configurare¶

Listă de verificare pentru lansarea MPL în producție:

Instalați eyssen_delivery_mpl.
Pe fiecare metodă de expediere MPL (Stoc ‣ Configurare ‣ Metode de livrare), completați fila Configurare MPL: acreditările pentru Mediu ales, Accounting Code (Vevőkód), Agreement Number (Megállapodásszám) și — pentru COD — Cont bancar ramburs.
Alegeți Tip de livrare pentru fiecare metodă, configurați fila Prețuri și publicați metodele pe site.
Activați și publicați furnizorul de plată MPL ramburs, cu cardul la punctul de colete sau la livrare și verificați furnizorii de plată activați ai fiecărui transportator (vezi Metode de plată în funcție de livrare).
În Site web ‣ Configurare ‣ Setări, blocul MPL: opțional, setați o Cheie API Google Maps pentru selectorul cu hartă și ajustați Interval de verificare a urmăririi, dacă este necesar.
În Stoc ‣ Configurare ‣ Stări livrare MPL, bifați Stare livrat pe rândurile de tip livrat.
Opțional, configurați validarea automată pe tipul de operație de ieșire (Validează transferul la livrare + Validează la stările MPL).
Setați prețul de vânzare al produsului Serviciu de manipulare (0 dezactivează suplimentul de la finalizarea comenzii).
Lăsați acțiunea planificată zilnică MPL: Sincronizare locuri de livrare să populeze catalogul de puncte de colete sau declanșați o căutare inițială după cod poștal din selectorul din backend.

Utilizare¶

Un client finalizează comanda pe site și alege o metodă de expediere MPL. Pentru o metodă cu punct de colete, se deschide selectorul, iar clientul alege o locație Csomagautomata, Postán maradó sau PostaPont; finalizarea comenzii este blocată până când este selectat un punct.
Clientul plătește — cu metoda MPL COD sau cu orice alt furnizor activat pentru transportator — iar punctul de colete ales este stocat pe comanda de vânzare.
Depozitul procesează comanda de livrare. Validarea ei (sau apăsarea Tipărește eticheta MPL) înregistrează expedierea la MPL, calculează suma COD, când este cazul, și atașează eticheta PDF A6 — cu numere de urmărire pentru fiecare pachet, când MPL le furnizează.
Acțiunile planificate urmăresc coletul prin stările de urmărire MPL. Când se ajunge la o stare marcată cu Stare livrat, data primirii de către client este înscrisă și — dacă este configurat pe tipul de operație — transferul este validat automat.

Domeniu de aplicare și module¶

eyssen_delivery_mpl — conectorul de transportator MPL: tipul de metodă de expediere MPL cu variantele livrare la domiciliu și punct de colete, catalogul și selectoarele de puncte de colete, generarea etichetelor PDF A6, sincronizarea urmăririi cu validare automată și furnizorul de plată MPL COD.

Calculul sumei COD, filtrarea plăților pentru fiecare transportator și câmpurile de stare a livrării la care se conectează conectorul sunt componente comune, documentate în Plata ramburs (COD), Metode de plată în funcție de livrare și Starea și datele livrării.