🎃 New adapter: PlentyONE / plentymarkets (e-commerce ERP)

Start with packages/backend/src/adapters/de/hrworks.json and docs/connectors/login-token-auth.md to understand LOGIN_TOKEN, then review the adapter checklist in .github/CONTRIBUTING.md. Build de/plentymarkets.json and its live spec, checking endpoints against the PlentyONE REST reference; run the adapter validator and npx jest src/adapters/de/plentymarkets from packages/backend. Done means all eight tools and acceptance checks pass, including the disabled write tool and live warehouse/order checks when a trial system is available.

Part of the October Challenge #846.

Why

PlentyONE (formerly plentymarkets) is one of the most widely used e-commerce ERPs among German online retailers: orders, items and variations, stock across warehouses, and customer contacts for shops and marketplaces such as Amazon, eBay and Otto. The catalog has JTL-Wawi, Xentral, weclapp and Billbee, but no plentymarkets (grep -ril plenty packages/backend/src/adapters finds nothing). With an adapter, a user could ask "which orders from yesterday are still in status 5?", "how much stock of SKU X is in the main warehouse?" or "show customer 1234's last orders".

Self-hosted vs Cloud

• Self-hosted: available in Community and Business; no edition gating.
• Cloud (DEPLOYMENT_MODE=cloud): available. PlentyONE systems are public SaaS (https://p<PID>.my.plentysystems.com), so the SSRF guard allows them. On Cloud trial plans, installs count toward the connector limit (license-guard.service.ts:65).
• Who can use it: any role except VIEWER can install it (adapters.controller.ts:207). The username and password live encrypted in the organization's own connector authConfig. The cached bearer token is encrypted too and keyed by connector (docs/connectors/login-token-auth.md, "Security notes"). Nothing is shared across organizations.

What to build

packages/backend/src/adapters/de/plentymarkets.json. Start with npm run adapter:new -- plentymarkets --region de --auth LOGIN_TOKEN.

• API docs: https://developers.plentymarkets.com/en-gb/developers/main/rest-api-guides/getting-started.html (REST reference: https://developers.plentymarkets.com/en-gb/plentymarkets-rest-api/index.html; order guide: https://developers.plentymarkets.com/en-gb/developers/main/rest-api-guides/order-data.html).
• Base URL: {{PLENTY_URL}}/rest, where PLENTY_URL is e.g. https://p12345.my.plentysystems.com. The exact URL is shown under Setup → Settings → API → Data.
• Auth: LOGIN_TOKEN. POST {{PLENTY_URL}}/rest/login with {"username": "${username}", "password": "${password}"} returns {token_type, expires_in: 86400, access_token, refresh_token}. Map tokenJsonPath: "access_token", expiryJsonPath: "expires_in", expiryFormat: "ttl_seconds", refreshOn401: true, and set proactiveRefreshSeconds well below 86400 (e.g. 3600). Copy the shape from de/hrworks.json:15-28.
• Env vars: PLENTY_URL, PLENTY_USERNAME, PLENTY_PASSWORD. In instructions, recommend a dedicated REST user with only the needed rights (Setup → Settings → User → Accounts). That user also counts toward the concurrent API user limit (default 3; a 429 means the limit was hit).
• Rate limits depend on the plan (Basic: 80 reads/min, 40 writes/min). Put this in instructions.
• Category: e-commerce. probe: plentymarkets_list_warehouses.

Hints come from the HTTP method (docs/tool-definition.md:503-545); do not hand-write annotations. Check each path and parameter against the REST reference and note any deviation in the PR.

Where to look

• packages/backend/src/adapters/de/hrworks.json:15-28 — a working LOGIN_TOKEN adapter (POST credentials, read token, refresh).
• docs/connectors/login-token-auth.md — authConfig fields (loginUrl, loginBody, tokenJsonPath, expiryJsonPath, expiryFormat).
• packages/backend/src/adapters/de/jtl-wawi.json — a comparable German commerce ERP; copy how its instructions explain orders vs items vs stock.
• packages/backend/src/adapters/intl/todoist.live.spec.ts — spec template; live calls behind RUN_PLENTYMARKETS_LIVE=1.
• .github/CONTRIBUTING.md:136 — the "Add an adapter" checklist; #150 — adapter guide.

Acceptance criteria

• de/plentymarkets.json with the 8 tools above; the write tool has "enabled": false.
• validate-adapters.mjs --warn is clean (the validator requires instructions ≥ 800 chars and each tool description ≥ 60 chars, scripts/validate-adapters.mjs:32); catalog.ts is regenerated; adapter-count.mjs --check passes.
• de/plentymarkets.live.spec.ts: static checks (auth type LOGIN_TOKEN, loginUrl ends with /rest/login, tokenJsonPath is access_token, write tool disabled); with RUN_PLENTYMARKETS_LIVE=1 it logs in and lists warehouses and orders on a trial system. npx jest src/adapters/de/plentymarkets passes in packages/backend.
• No password or token appears in the spec, the fixtures or the PR.
• Logo at packages/frontend/public/logos/connectors/plentymarkets.svg.
• Docs updated: optional content/guides/en/plentymarkets-to-mcp.mdx.

Out of scope

• Creating orders, items or contacts; deleting anything; stock corrections (/stockmanagement/.../correction).
• The plugin/Ceres interface, webhooks (event procedures), marketplace-specific endpoints.
• Using refresh_token. Re-login through LOGIN_TOKEN is enough.

Free account: PlentyONE offers a 30-day free test system without obligation (start from https://www.plentyone.com). Enable REST access for a user in it.

Size

M (1–2 days). The login flow and the order filters need testing against a real trial system.

How to claim

Comment "I'd like to work on this" and we'll assign you. Rules in #846.