Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#867 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
68/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
json, typescript
Lĩnh vực
api, backend

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement hacktoberfest help wanted

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.

Tool Endpoint Expected hints
plentymarkets_list_orders GET /orders (statusFrom, statusTo, createdAtFrom, createdAtTo, contactId, with[], page, itemsPerPage) read-only
plentymarkets_get_order GET /orders/{orderId} (with[]=orderItems, addresses) read-only
plentymarkets_list_variations GET /items/variations (numberExact, itemName, barcode, isActive) read-only
plentymarkets_list_stock GET /stockmanagement/stock (variationId, warehouseId) read-only
plentymarkets_list_warehouses GET /stockmanagement/warehouses read-only
plentymarkets_list_contacts GET /accounts/contacts (email, fullText, page) read-only
plentymarkets_get_contact GET /accounts/contacts/{contactId} read-only
plentymarkets_update_order_status PUT /orders/{orderId} with body {statusId} write, destructive, idempotent (derived from PUT). Ship it with "enabled": false so a workspace turns it on deliberately

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.

Ngôn ngữ chính
TypeScript
Star
856
Fork
82
Merge trung bình
6 giờ 30 phút
Pull request đã merge (30 ngày)
205

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của HelpCode-ai/anythingmcp

Tất cả issue của HelpCode-ai/anythingmcp

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.