=== MetaBox Fulfillment === Tags: woocommerce, fulfillment, logistics, warehouse, shipping Requires at least: 6.2 Tested up to: 6.9 Requires PHP: 8.1 Stable tag: 1.1.13 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html A MetaBox fulfillment rendszer és a WooCommerce összekötése: rendelés export, státusz- és készletszinkron, szállítási és fizetési mód mapping. == Leírás == A **MetaBox Fulfillment** célja, hogy a WooCommerce áruházadat biztonságosan és automatizáltan összekösse a MetaBox fulfillment rendszerrel. Mit csinál a plugin? * Új rendeléseket áttölt a MetaBox rendszerbe (automatikusan és/vagy kézzel). * A MetaBox-ból visszajött **rendelés státuszokat** visszaírja WooCommerce-be. * Kezeli a **készletszinkront** (MetaBox → WooCommerce). * Lehetővé teszi a **szállítási módok** és **fizetési módok** párosítását a MetaBoxhoz. * Egyszerű admin felületet ad a MetaBox fiók és beállítások kezeléséhez. * Egyszerűen áttölthetővé teszi az egyes termékeket a MetaBoxba. A plugin tervezésénél kiemelt szempont volt: * Biztonság: a MetaBox rendszer felé csak a plugin kommunikál, befelé nem engedünk közvetlen hívást. * Stabilitás: saját adatbázistáblák, egyértelmű mappingek, naplózás. * Jövőállóság: külön kezelt rendelés-, státusz- és készletkezelési beállítások. == Fő funkciók == * **MetaBox fiók beállítás** * API kapcsolat beállítása (partner azonosító, API kulcs, backend URL). * Kapcsolati állapot ellenőrzése (ping/health check). * **Rendelések kezelése** * Új rendelések automatikus áttöltése a MetaBoxba (opcionálisan kapcsolható). * Manuális áttöltés meglévő rendeléseknél (pl. rendelés lista / rendelés szerkesztőből). * Meta adatok a rendelésen: * `_mtbxfc_pushed_to_fulfillment` – sikeres áttöltés jelölése * `_mtbxfc_push_response` – utolsó API válasz mentése * **Státusz mapping (MetaBox ↔ WooCommerce)** * Fulfillment (MetaBox) státuszok párosítása WooCommerce rendelés státuszokkal. * A státusz szinkron csak olyan sorokra fut, ahol van mapping. * WordPress cron segítségével fut, konfigurálható intervallummal. * **Készletkezelés** * Készlet szinkron beállítások (intervallum, kapcsolók). * Saját log tábla a szinkronizálási futásokhoz. * **Szállítási módok** * WooCommerce szállítási mód instance-ok párosítása MetaBox szállítási típusokkal (pl. HOME_DELIVERY, PICKUP_POINT stb.) és futárszolgálatokkal (GLS, MPL, stb.). * **Fizetési módok** * WooCommerce fizetési gateway-ek összekötése MetaBox oldali beállításokkal (pl. melyik fizetés tekintendő utánvétnek, COD). * **Termék áttöltés** * Egyedi termék MetaBoxba történő áttöltése / frissítése termékszerkesztőből. * Alap adatok, ár, súly, méretek, barcode, SKU továbbítása. * **Dashboard Widget** * A WordPress Vezérlőpulton megjelenő kis widget, amely mutatja a MetaBox kapcsolat állapotát (online/offline), és rövid infót ad a kapcsolatról. == Rendszerkövetelmények == * WordPress 6.0 vagy újabb * WooCommerce 7.0 vagy újabb * PHP 8.1 vagy újabb * Aktív MetaBox fulfillment fiók (partner azonosítóval és API kulccsal) == Telepítés == 1. **Plugin feltöltése** * Töltsd le a bővítményt `.zip` formátumban. * WordPress adminban: *Bővítmények → Új hozzáadása → Bővítmény feltöltése*. * Válaszd ki a zip fájlt, majd *Telepítés* és *Bekapcsolás*. VAGY * Csomagold ki a zipet, és a plugin mappáját másold a `/wp-content/plugins/` könyvtárba. * A WordPress admin felületen kapcsold be a bővítményt. 2. **MetaBox fiók beállítása** * Menj a **MetaBox → MetaBox Fiók** menüpontra. * Add meg a MetaBox által kiadott API adatokat (pl. partner azonosító, API kulcs – attól függően, mit kér a felület). * Mentsd a beállításokat. * Ellenőrizd a kapcsolatot (státusz jelzés a felső sávban / dashboard widgetben). 3. **Rendelés áttöltés beállítása** * Menj a **MetaBox → Megrendelések kezelése** oldalra. * Kapcsold be, ha szeretnéd, hogy új rendelések automatikusan átkerüljenek a MetaBoxba. * Állítsd be, hogy mely WooCommerce rendelés státusz(ok) esetén történjen az áttöltés. 4. **Státusz mapping** * Menj a **MetaBox → Státuszok kezelése** oldalra. * Itt tudod párosítani, hogy a MetaBoxból érkező státuszok (pl. PACKING, SHIPPED) mely WooCommerce rendelés státuszokra váltsanak. * Csak a párosított státuszokat fogja a plugin frissíteni WooCommerce-ben. 5. **Szállítási módok és futárok** * Menj a **MetaBox → Szállítási módok** oldalra. * Válaszd ki, hogy az egyes WooCommerce szállítási mód instance-ok mely MetaBox szállítási típusnak és futárszolgáltatónak felelnek meg. * A plugin ezt használja az order payload építésénél. 6. **Fizetési módok** * Menj a **MetaBox → Fizetési módok** oldalra. * Itt tudod megadni, melyik WooCommerce fizetési mód számít utánvétnek (COD), stb. * A plugin ez alapján számítja például az utánvét összegét. 7. **Készlet szinkron beállítása** * Menj a **MetaBox → Készletkezelés** oldalra. * Kapcsold be a készletszinkront, és állítsd be az intervallumot. * A plugin WP-Cronon keresztül fogja frissíteni a készleteket. == Használat == === Rendelések áttöltése MetaBoxba === * Ha az automatikus áttöltés be van kapcsolva, a megfelelő státuszba kerülő új rendeléseket a plugin automatikusan elküldi a MetaBox API felé. * Ha valamiért kézzel szeretnél áttölteni: * Nyisd meg a rendelés adatlapját WooCommerce-ben. * Használd a MetaBox-hoz kapcsolódó műveletet (pl. rendelés sor művelet / gomb – a pluginben definiált hely szerint). * Siker/hiba esetén a rendszer: * rendelés megjegyzést ír, * illetve admin értesítést (notice) jeleníthet meg. === Termék áttöltése === * Nyisd meg a WooCommerce termék szerkesztő felületét. * A MetaBox Fulfillment meta boxban hagyd bepipálva az áttöltést / frissítést. * Mentsd a terméket. * A plugin ekkor felépíti a termék payloadot, és elküldi a MetaBoxnak. * Siker esetén meta mezőkben jelzi, hogy a termék már át lett küldve. === Rendelés státusz szinkron === * A MetaBox rendszer időnként visszaküldi az aktuális rendelés státuszokat. * A plugin a beállított időközönként (WP-Cron) lekérdezi a változásokat: * csak azokat a sorokat dolgozza fel, amelyek az utolsó futás óta módosultak, * csak azokat a státuszokat írja át, amelyekre létezik mapping. * Ha valamelyik fulfillment státuszra nincs mapping, azt egyszerűen kihagyja (nem nyúl a rendeléshez). == Cron és időzítés == A plugin több helyen is a WordPress beépített cron rendszerét használja: * **Rendelés státusz szinkron (MetaBox → WooCommerce)** * Saját hook: `mtbxfc_order_status_sync` * Dinamikus, perc alapú intervallum (a beállításoknál konfigurálható). * **Készletszinkron (MetaBox → WooCommerce)** * Saját hook a készlethez (pl. `mtbxfc_stock_sync` – a konkrét név a kódban definiált). Ha a tárhelyeden a WP-Cron nem fut megbízhatóan, érdemes valódi cron jobot beállítani, ami rendszeresen hívja a `wp-cron.php`-t. Ha valami nem működik: 1. Ellenőrizd a MetaBox fiók beállításait (API kulcs, URL, partner azonosító stb.). 2. Nézd meg a WooCommerce rendelés megjegyzéseit – a plugin oda is ír. 3. Kapcsold be a WordPress debug / error logot és nézd meg a MetaBoxkal kapcsolatos sorokat. == Gyakori kérdések == = Nem frissül a rendelés státusza WooCommerce-ben. Miért? = * Nézd meg, hogy a **Státuszok kezelése** oldalon van-e mapping az adott MetaBox státuszra. * Ha nincs, a plugin szándékosan nem nyúl a Woo rendeléshez. * Ellenőrizd, hogy a cron fut-e (van-e futás a logban). = A rendelés nem megy át MetaBoxba. = * Ellenőrizd, hogy be van-e állítva a MetaBox fiók és érvényes-e az API kulcs. * Nézd meg a rendelés megjegyzéseit – általában ott szerepel, ha a MetaBox API hibát dob. * Ellenőrizd a bővítmény logját (WordPress error_log). = Miért jelzi azt, hogy „Nincs konfigurálva”? = * Ha a MetaBox API kulcs vagy az API URL hiányzik, a plugin „nincs konfigurálva” állapotot jelez. * A MetaBox → MetaBox Fiók oldalon töltsd ki és mentsd a fiókbeállításokat. == Támogatás == Ez a bővítmény MetaBox fulfillment rendszerrel dolgozik. Ha technikai problémád van a plugin működésével kapcsolatban, készíts: * WordPress / WooCommerce verzió adatokat, * a releváns log sorokat (MetaBox-hoz kapcsolódó hibák), * és egy rövid leírást arról, mit próbáltál. Ezek birtokában sokkal gyorsabban behatárolható a hiba oka. == Licence == A bővítmény a GPLv2 vagy újabb licenc alatt kerül terjesztésre. ============= == English == ============= Connect your WooCommerce store to your MetaBox fulfillment system. Automatic order export, status and stock sync, shipping and payment method mapping – all in a single plugin. == Description == The **MetaBox Fulfillment** safely and automatically connects your WooCommerce store to the MetaBox fulfillment system. What does the plugin do? * Sends new orders to MetaBox (automatically and/or manually). * Syncs **order statuses** from MetaBox back to WooCommerce. * Handles **stock synchronization** (MetaBox → WooCommerce). * Lets you map **shipping methods** and **payment methods** to MetaBox. * Provides a simple admin UI to manage your MetaBox account and settings. * Makes it easy to send individual products to MetaBox. Design goals: * **Security:** only the plugin talks to MetaBox; no direct inbound calls into your store. * **Stability:** dedicated database tables, clear mappings, logging. * **Future-proof:** separate settings for orders, statuses and stock handling. == Main Features == * **MetaBox account setup** * Configure the API connection (partner ID, API key, backend URL). * Check connection health (ping / health check). * **Order handling** * Automatically export new orders to MetaBox (optional). * Manually push existing orders (e.g. from the order list / order edit screen). * Order-level meta data: * `_mtbxfc_pushed_to_fulfillment` – marks successful export * `_mtbxfc_push_response` – stores the last API response * **Status mapping (MetaBox ↔ WooCommerce)** * Map fulfillment (MetaBox) statuses to WooCommerce order statuses. * Status sync only runs for rows that have a mapping. * Uses WordPress cron with a configurable interval. * **Stock handling** * Stock sync settings (interval, switches). * Own log table for sync runs. * **Shipping methods** * Map WooCommerce shipping method instances to MetaBox shipping types (e.g. HOME_DELIVERY, PICKUP_POINT, etc.) and carriers (GLS, MPL, etc.). * **Payment methods** * Map WooCommerce payment gateways to MetaBox-side settings (e.g. which ones are considered Cash on Delivery / COD). * Used to calculate COD amounts. * **Product export** * Send or update a single product in MetaBox from the product edit screen. * Sends basic data, price, weight, dimensions, barcode, SKU. * **Dashboard Widget** * A small widget on the WordPress Dashboard that shows the MetaBox connection status (online/offline) and a short summary. == Requirements == * WordPress 6.0 or newer * WooCommerce 7.0 or newer * PHP 8.1 or newer * An active MetaBox fulfillment account (with partner ID and API key) == Installation == 1. **Upload the plugin** * Download the plugin as a `.zip` file. * In WordPress admin: *Plugins → Add New → Upload Plugin*. * Select the zip file, then click *Install* and *Activate*. OR * Unzip the archive and upload the plugin folder into `/wp-content/plugins/`. * Activate the plugin from the WordPress admin. 2. **Configure your MetaBox account** * Go to **MetaBox → MetaBox Account** in the admin menu. * Enter the API details provided by MetaBox (partner ID, API key, etc., depending on the UI). * Save the settings. * Check the connection (status indicator in the top bar / dashboard widget). 3. **Configure order export** * Go to **MetaBox → Order Handling**. * Enable automatic export if you want new orders to be sent automatically. * Configure which WooCommerce order status(es) should trigger the export. 4. **Status mapping** * Go to **MetaBox → Status Mapping**. * Map the statuses coming from MetaBox (e.g. PACKING, SHIPPED) to your WooCommerce order statuses. * The plugin will only change orders for statuses that have mappings. 5. **Shipping methods and carriers** * Go to **MetaBox → Shipping Methods**. * For each WooCommerce shipping method instance, select the corresponding MetaBox shipping type and carrier. * The plugin uses this when building the order payload. 6. **Payment methods** * Go to **MetaBox → Payment Methods**. * Define which WooCommerce payment methods are COD (Cash on Delivery), etc. * The plugin uses this to calculate the COD amount, for example. 7. **Configure stock sync** * Go to **MetaBox → Stock Handling**. * Enable stock synchronization and set the interval. * The plugin will refresh stock via WP-Cron. == Usage == === Sending orders to MetaBox === * If automatic export is enabled, new orders reaching the configured status will be sent to the MetaBox API. * If you want to export manually: * Open the order details in WooCommerce. * Use the MetaBox-related action (e.g. a row action or button, depending on the plugin UI). * On success/failure the system: * adds an order note, * and may display an admin notice. === Exporting products === * Open the WooCommerce product edit screen. * In the MetaBox Fulfillment meta box, keep the checkbox enabled to export/update the product. * Save the product. * The plugin will build the product payload and send it to MetaBox. * On success, it stores meta fields indicating that the product has been exported. === Order status synchronization === * The MetaBox system periodically sends back the current order statuses. * The plugin, at the configured interval (via WP-Cron), fetches the changes: * only processes rows changed since the last run, * only updates WooCommerce orders if there is a mapping for the given status. * If a fulfillment status has no mapping, the plugin simply skips it (does not touch the Woo order). == Cron and Scheduling == The plugin uses the built-in WordPress cron system in several places: * **Order status sync (MetaBox → WooCommerce)** * Custom hook: `mtbxfc_order_status_sync` * Dynamic, minute-based interval (configurable in settings). * **Stock sync (MetaBox → WooCommerce)** * Own hook for stock (defined in the code, e.g. `mtbxfc_stock_sync`). If WP-Cron is not reliable on your hosting, consider setting up a real cron job that regularly hits `wp-cron.php`. If something doesn’t seem to run: 1. Check your MetaBox account settings (API key, URL, partner ID, etc.). 2. Look at the WooCommerce order notes – the plugin writes messages there. 3. Enable WordPress debug / error logging and search for MetaBox-related entries. == Frequently Asked Questions == = Order status is not updated in WooCommerce. Why? = * Check the **Status Mapping** page to ensure there is a mapping for that specific MetaBox status. * If there is no mapping, the plugin intentionally does not change the WooCommerce order. * Verify that cron is running (check logs for status sync runs). = The order is not sent to MetaBox. = * Make sure your MetaBox account is configured and the API key is valid. * Check the order notes – usually MetaBox API errors will be written there. * Look into the plugin logs / WordPress error log for MetaBox-related messages. = Why does it show “Not configured”? = * If the MetaBox API key or API URL is missing, the plugin reports a “not configured” state. * Fill out and save the account settings under **MetaBox → MetaBox Account**. == Support == This plugin is designed to work with the MetaBox fulfillment system. If you have technical issues with the plugin: * Collect your WordPress / WooCommerce version information, * gather relevant log entries (MetaBox-related errors), * and write a short description of what you tried. With this information, the root cause can be identified much faster. == Changelog == = 1.1.13 = * Match V2 order status updates using the WooCommerce order ID before the first underscore in external_id. = 1.1.12 = * Include the pickup-point ID in address2 for Csomagpiac MPL PostaPont orders. = 1.1.11 = * Send GLS ParcelShop orders as parcel-point deliveries with the GLS pickup-point ID. = 1.1.10 = * Added manual MetaBox submission from the WooCommerce order editor. * Show which products block submission on the order's MetaBox card. * Added bulk product submission and match existing MetaBox products by SKU in the selected connection. = 1.1.9 = * Added V2 stock and order status synchronization with separate checkpoints for each API connection. * Verify the complete external order ID before applying a status update. * Check connectivity against the selected MetaBox API and keep external WordPress notices above the plugin interface. = 1.1.8 = * Added support for GLS and Foxpost parcel-locker orders using the gls_shipping_method_parcel_locker and foxpost_package_point shipping methods, preserving existing vp_pont and home-delivery handling. * Read locker addresses and identifiers from the plugins' order metadata, send the locker ID separately in address2, and set the correct carrier and PARCEL_LOCKER delivery type. * Prevent locker identifiers and leftover apartment numbers from being appended to the street address for these shipping methods. * Stop order export with an error when these integrations have a missing locker ID, incomplete address, or malformed Foxpost address. = 1.1.7 = * Fixed order status synchronization to resume from the stored last-run time, preventing delayed cron runs from skipping changes. * Use the WordPress timezone and record the run start time so changes made during a request remain in the next sync window. * Invalidate the cached last-run time after writing a sync log entry. == License == This plugin is distributed under the GPLv2 or later license. See: https://www.gnu.org/licenses/gpl-2.0.html