README

A small, framework-agnostic PHP toolkit for integrating any e‑commerce platform with Acumatica ERP (XRP) over its contract-based REST API.

It gives you the two hard, reusable pieces — talking to Acumatica securely, and securing the webhooks between your shop and the ERP — so you can focus on your own product/order mapping.

© MEGZO_tech — proprietary, source-available. Provided for evaluation/reference. Production or commercial use requires a paid commercial license and author attribution — see LICENSE. Not affiliated with Acumatica, Inc. — see TRADEMARKS.md.

🇷🇴 Descriere (RO)

Integrare PHP pentru Acumatica ERP (XRP). Un set de unelte care rezolvă cele două părți grele și refolosibile ale oricărei integrări de e‑commerce cu Acumatica: clientul REST securizat (autentificare OAuth2 ROPC, cu cache și reîmprospătare de token) și semnarea și verificarea HMAC a webhook‑urilor. Rămâne de făcut doar maparea propriilor produse și comenzi. În plus, traduce erorile Acumatica în cauza reală (de exemplu câmpul respins de ERP), nu doar „HTTP 500". Produs comercial MEGZO_tech, cu licență cu plată la megzo.biz.

🇭🇺 Leírás (HU)

PHP integráció az Acumatica ERP‑hez (XRP). Eszközkészlet, amely minden Acumatica e‑kereskedelmi integráció két nehéz, újrahasznosítható részét megoldja: a biztonságos REST‑klienst (OAuth2 ROPC hitelesítés, token‑gyorsítótárazással és ‑frissítéssel) és a webhookok HMAC‑aláírását és ‑ellenőrzését. Így csak a saját termékek és rendelések megfeleltetése marad hátra. Ráadásul az Acumatica hibáit a tényleges okukra fordítja le (például az ERP által elutasított mezőre), nem csak „HTTP 500" kódot mutat. Kereskedelmi MEGZO_tech termék, fizetős licenccel a megzo.biz oldalon.

What's in the box

• AcumaticaClient — a clean Acumatica REST client:
  • OAuth 2.0 Resource Owner Password Credentials (ROPC) auth with automatic token caching + refresh.
  • Helpers for Stock Items, Sales Orders and Customers (upsertStockItem, createSalesOrder, upsertCustomer).
  • findSalesOrder() for idempotent order pushes, getStockItemsModifiedSince() for reconciliation pulls.
  • Automatic conversion to/from Acumatica's {"field":{"value": …}} wire format (autoWrap / unwrap), including detail lines and custom (Usr-) fields.
  • testConnection() for a quick health check.
• Webhook\HmacSigner / Webhook\HmacVerifier — sign and verify HMAC-SHA256 webhook requests between the ERP/middleware and your shop (timestamped, replay-bounded, constant-time, multi-key for rotation).
• Contracts\ErpConnector — the interface to code your integration against (swap drivers, mock in tests).

Pure PHP — only ext-curl and ext-json. No framework, no platform lock-in.

Get a license

This is a commercial product. Purchase a license at megzo.biz; licensees receive the package and install it via the private distribution they're given (e.g. a Composer VCS/path repository) — it is not published on Packagist.

Quick start

1. Talk to Acumatica

use Megzo\Acumatica\AcumaticaClient;

$acu = new AcumaticaClient([
    'base_url'      => 'https://your.acumatica.com', // instance root, no trailing slash
    'endpoint_name' => 'Default',                    // your contract endpoint
    'version'       => '24.200.001',
    'client_id'     => '....@Company',
    'client_secret' => '....',
    'username'      => 'integration-user',
    'password'      => '....',
]);

$acu->testConnection(); // ['ok' => true, 'message' => 'Connected — OAuth + endpoint reachable.']

2. Push a product (Stock Item)

$acu->upsertStockItem([
    'InventoryID'  => 'GIFT-001',
    'Descr'        => 'Personalised mug',
    'ItemClass'    => 'STOCKITEM',
    'DefaultPrice' => 49.90,
    // custom Usr- field:
    // 'custom' => ['ItemSettings' => ['UsrShopItem' => ['type' => 'CbBoolean', 'value' => true]]],
]);

3. Create a Sales Order from a shop order (idempotent)

$orderNbr = 'WEB-10532';

if (! $acu->findSalesOrder($orderNbr)) {
    $acu->createSalesOrder([
        'OrderType'        => 'SO',
        'CustomerID'       => 'WEBSHOP',
        'CustomerOrderNbr' => $orderNbr, // external ref → idempotency
        'Details'          => [
            ['InventoryID' => 'GIFT-001', 'OrderQty' => 2, 'UnitPrice' => 49.90],
        ],
    ]);
}

4. Secure your inbound webhooks

The sender (your ERP / middleware) signs the request:

use Megzo\Acumatica\Webhook\HmacSigner;

$headers = (new HmacSigner($secret))->headers('my-key-id', $jsonBody);
// X-Megzo-Key / X-Megzo-Timestamp / X-Megzo-Signature  → attach to the HTTP request

The receiver (your shop endpoint) verifies it:

use Megzo\Acumatica\Webhook\HmacVerifier;

$verifier = new HmacVerifier(['my-key-id' => $secret], 'sha256', 300); // 300s replay window
$ok = $verifier->verify(
    $request->header('X-Megzo-Key'),
    $request->header('X-Megzo-Timestamp'),
    $request->header('X-Megzo-Signature'),
    $rawRequestBody, // sign/verify the EXACT bytes
);

Signature = base64( hmac_sha256( timestamp + "." + rawBody, secret ) ).

See examples/ for runnable scripts.

Going live? Read docs/GO_LIVE_TROUBLESHOOTING.md — the actual 422/500 causes & fixes (most are ERP config, not code), and how AcumaticaException::summarize() makes them visible. A full, real-world CodeIgniter 4 reference integration (the first order it posted live was Acumatica SalesOrder 000010) is maintained privately by MEGZO_tech and available to commercial-license holders.

How it fits a real integration

                         ┌─────────────────────────┐
   Acumatica (ERP)  ◀───▶│   AcumaticaClient        │  catalog/price/stock ← ERP
                         │   (OAuth ROPC + REST)    │  orders / products    → ERP
                         └─────────────────────────┘
   ERP / middleware ───signed webhook───▶  HmacVerifier  ───▶  your shop
   your shop  ───▶  HmacSigner  ───signed webhook───▶  ERP / middleware

Your application supplies the platform-specific parts — reading products/orders, mapping fields, queueing — and depends on ErpConnector. This library stays out of your framework's way.

Security notes

• Sign and verify the exact raw body bytes (don't re-encode/pretty-print between).
• Keep the replay window tight (default 300s) and pair it with a nonce/dedup store if you need strict once-only delivery.
• Each ROPC sign-in consumes an Acumatica license seat — the client caches and refreshes the token to avoid churning seats.
• Store credentials/secrets outside the web root; never commit them (see .env.example).

Requirements

• PHP 8.1+, ext-curl, ext-json.
• An Acumatica contract-based REST endpoint and an integration user authorized for OAuth.

Contributing

Bug reports are welcome via issues. By submitting a contribution you assign it to MEGZO_tech under this project's proprietary license. Run the suite with composer test.

License & trademarks

Proprietary — © 2026 MEGZO_tech. All rights reserved. This is source-available for evaluation/reference, not open source. Any production or commercial use requires a paid commercial license and must keep author attribution to MEGZO_tech — see LICENSE. Purchase a license at megzo.biz (or forint@megzo.biz).

"Acumatica" is a trademark of Acumatica, Inc.; in Romania "Acumatica XRP" is a registered trademark of SeniorSoftware (exclusive Acumatica reseller in Romania). This project is independent and not affiliated with either — see TRADEMARKS.md. Not legal advice; have counsel review before relying on these terms.