MetaBox Fulfillment

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.

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.

1. 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).

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

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)

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.

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