=== MetaBox Fulfillment ===
Tags: woocommerce, fulfillment, logistics, warehouse, shipping
Requires at least: 6.2
Tested up to: 6.9
Requires PHP: 8.0
Stable tag: 1.1.4
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.0 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.0 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.

== License ==

This plugin is distributed under the GPLv2 or later license.
See: https://www.gnu.org/licenses/gpl-2.0.html