WooCommerce API nodes for Node-RED

2026-10-14 23:18:22 +02:00
commit e3b89fc74c
17 changed files with 1049 additions and 0 deletions
@@ -0,0 +1,182 @@
+# nextcloud-nodered-woocommerce
+
+Node-RED nodes for the [WooCommerce](https://woocommerce.com/) REST API. Part of the
+[nextcloud-nodered](https://kode.hannesahlin.se/n3wk/) suite.
+
+## Package
+
+`node-red-contrib-nextcloud-woocommerce`
+
+## Nodes
+
+| Node | Type | Purpose |
+|------|------|---------|
+| `woocommerce-config` | config | Base URL + Consumer Key + Consumer Secret |
+| `woocommerce-order` | function | list (with filters), get, updateStatus, addNote, getNotes |
+| `woocommerce-customer` | function | search (by email), get, create |
+| `woocommerce-product` | function | list, get (for enriching order data) |
+
+## Installation
+
+### Prerequisites
+
+- An existing [nextcloud-node-red](https://kode.hannesahlin.se/n3wk/nextcloud-nodered-ocs-api) installation.
+- WooCommerce API key with Read permission (preferably Read/Write), bound to an Administrator user.
+
+### Quick install (recommended)
+
+```bash
+git clone https://github.com/kode-tjenester/nextcloud-nodered-woocommerce.git
+cd nextcloud-nodered-woocommerce
+export NODERED_DIR=/path/to/your/nextcloud-node-red
+bash bootstrap-install.sh
+cd $NODERED_DIR
+docker compose build --no-cache
+docker compose up -d
+```
+
+### Manual install
+
+```bash
+export NODERED_DIR=/path/to/your/nextcloud-node-red
+bash integrate-into-nodered.sh
+```
+
+The integrate script:
+1. Copies all `.js` and `.html` files into `$NODERED_DIR/nodes/`.
+2. Copies the package to `$NODERED_DIR/opt/nextcloud-nodes/node-red-contrib-nextcloud-woocommerce/`.
+3. Patches `$NODERED_DIR/entrypoint.sh` to install the nodes on container start.
+4. Is idempotent — safe to run multiple times.
+
+## Authentication
+
+| Method | Details |
+|--------|---------|
+| Consumer Key | From WooCommerce → Settings → Advanced → REST API |
+| Consumer Secret | Paired with Consumer Key |
+
+**Important:** Base URL must be `https://shop.hanssonit.se/wp-json/wc/v3/`.
+The API key must have at least Read permission. The user the key is bound to
+must be an Administrator or have equivalent capabilities.
+
+## Node Details
+
+### woocommerce-order
+
+Operations: `list`, `get`, `updateStatus`, `addNote`, `getNotes`.
+
+**List with filters:**
+```
+msg.status   = "processing" | "completed" | "on-hold" | ...
+msg.after    = "2026-10-01T00:00:00"  (ISO 8601)
+msg.before   = "2026-10-31T23:59:59"
+msg.customer = customer ID
+msg.product  = product ID
+msg.limit    = per_page (default 10)
+msg.page     = page number
+```
+
+**Update status:**
+```
+msg.orderId  = 31921
+msg.status   = "completed"
+```
+
+**Add note:**
+```
+msg.orderId      = 31921
+msg.note         = "Customer contacted via phone"
+msg.customerNote = true  (optional — visible to customer)
+```
+
+### woocommerce-customer
+
+Operations: `search` (by email), `get`, `create`.
+
+**Search by email:**
+```
+msg.email = "lars@lrginvest.se"
+```
+
+### woocommerce-product
+
+Operations: `list`, `get`.
+
+Useful for enriching order `line_items` with product name, SKU, images.
+
+## Vertical Integration Flow: WooCommerce → Zammad → Nextcloud
+
+This is the trigger half of the vertical flow. Combined with
+[nextcloud-nodered-zammad](https://github.com/kode-tjenester/nextcloud-nodered-zammad)
+and the existing Nextcloud OCS nodes:
+
+### Step 1: Poll for new orders (or webhook)
+
+Use `woocommerce-order` with operation `list` and `msg.status = "processing"`
+on a schedule (inject node with cron), or trigger via a WooCommerce webhook.
+
+### Step 2: Extract order info in a Function node
+
+```javascript
+msg.title = "Order #" + msg.payload.number + " – " +
+    msg.payload.billing.first_name + " " + msg.payload.billing.last_name +
+    (msg.payload.billing.company ? " (" + msg.payload.billing.company + ")" : "");
+
+msg.customer = msg.payload.billing.email;
+
+msg.body = "Products:\n";
+for (let item of msg.payload.line_items) {
+    msg.body += "- " + item.name + " x" + item.quantity +
+        " (" + msg.payload.currency + " " + item.total + ")\n";
+}
+msg.body += "\nTotal: " + msg.payload.currency + " " + msg.payload.total + "\n";
+msg.body += "Address: " + msg.payload.billing.address_1 + ", " +
+    msg.payload.billing.city + " " + msg.payload.billing.postcode + "\n";
+msg.body += "Phone: " + msg.payload.billing.phone + "\n";
+msg.body += "Email: " + msg.payload.billing.email;
+
+msg.ticketId = msg.payload.id;
+msg.tag = "woocommerce-order";
+
+return msg;
+```
+
+### Step 3: Create Zammad ticket
+
+`zammad-ticket` node (operation: create) receives the Function output.
+Title: `Order #31921 – Lars Gardelin (LRG Invest AB)`
+Customer: billing email
+Body: product list + amount + address + phone
+
+### Step 4: Tag the ticket
+
+`zammad-ticket` (operation: addTag) with `msg.tag = "woocommerce-order"`.
+
+### Step 5: Organize in Nextcloud
+
+Existing Nextcloud OCS nodes:
+- Create/update customer folder
+- Create note or Deck card with order details
+- Optional: calendar event for follow-up
+- Link back to Zammad ticket in note/card
+
+### Example Flow JSON
+
+See `flows/woocommerce-to-zammad.json` for a complete example flow
+(no real credentials included).
+
+## Integration with Other Packages
+
+- **nextcloud-nodered-zammad**: Creates and manages Zammad tickets from WooCommerce orders.
+- **nextcloud-nodered-ocs-api**: Provides Nextcloud OCS nodes for creating folders, notes, deck cards, etc.
+- **nextcloud-nodered-agent**: Agent-based nodes for complex orchestration.
+
+## Credentials Security
+
+- Consumer Key and Secret are stored **only** in the Node-RED config node (encrypted at rest).
+- Never commit credentials to git (`.gitignore` excludes them).
+- The config node uses Node-RED's built-in credential encryption.
+
+## License
+
+MIT