n8n-nodes-pageyar

n8n Community Node for Pageyar — an Iran-market SaaS platform for Instagram DM pipelines.

Status: 1.0.0 — Regular Node covers 13 resources + Trigger Node ships (33 events, HMAC-verified via Pgy-Signature). Three copy-paste workflow templates ship in this README. Custom actions (/orders/{o}/status, webhook /test, /resend, etc.) are still deferred.

Install

In n8n → Settings → Community Nodes → Install, enter the package name and confirm:

n8n-nodes-pageyar

On a self-hosted n8n without that screen, install it from npm where n8n keeps its custom nodes, then restart n8n:

cd ~/.n8n/nodes    # or wherever your n8n custom nodes live
npm install n8n-nodes-pageyar

Two nodes appear:

• Pageyar — Transform group, CRUD against Pageyar shops (13 resources).
• Pageyar Trigger — Trigger group, receives real-time events from Pageyar shops.

Credential setup — Pageyar API

Plan requirement: The Pageyar public API requires the feature_api entitlement, which is only available on Pro or Enterprise plans. If the Test button returns 403 SUBSCRIPTION_LIMIT, upgrade your plan or contact Pageyar support.

1. In Pageyar panel → Settings → API → Generate token. Copy the token (starts with pgt_).
2. In n8n → Credentials → New → Pageyar API.
3. Fill:
   • Base URL: https://pageyar.com (or your shop subdomain — without /api/v1)
   • API Token: paste the pgt_... token
4. Test — this pings GET /api/v1/health.

Resources & operations (this release)

Each resource exposes a subset of the standard 7-op CRUD surface, depending on what Pageyar's public API supports.

Write operations (Create, Update, Upsert, Delete) all attach Idempotency-Key automatically. Read operations do not.

Pagination

Get Many responses attach a _pagination field to each row's json when the API returns a pagination envelope ({data: [...], meta: {pagination: {total, per_page, current_page, last_page, next_cursor}}}). Follow $json._pagination.next_cursor in a Loop-over-Items to walk pages.

Trigger Node

The Pageyar Trigger node receives events from your shop in real time. On workflow activation it:

1. Calls POST /api/v1/webhook-endpoints with n8n's generated webhook URL and the events you selected.
2. Stores the returned endpoint id + secret in n8n's workflow static data.
3. Verifies every incoming request against the Pgy-Signature header (HMAC-SHA256 of <timestamp>.<raw_body> with a 5-minute replay tolerance).

Deactivating the workflow calls DELETE /api/v1/webhook-endpoints/{id} to unregister.

Available events (33 total across products, categories, brands, customers, orders, payments, returns, discounts, inventory):

Idempotency

Every write operation (POST/PATCH/PUT/DELETE) automatically attaches an Idempotency-Key header derived from executionId + nodeName + itemIndex + operation. n8n retries within the same execution hit the same key, and Pageyar's API middleware serves the cached response for 24 hours.

Workflow templates

Three copy-paste starting points. Each is a two-node flow — swap the credential names and the destination-service IDs to match your setup.

1) New order → Google Sheets row

Every new order lands in a shared team spreadsheet — good for lightweight order tracking outside the Pageyar panel.

Nodes: Pageyar Trigger (event: order.created) → Google Sheets (operation: Append or Update)

Map columns like: id, customer.full_name, customer.phone, total, status, created_at.

{
  "name": "Pageyar: New order → Google Sheets",
  "nodes": [
    {
      "parameters": {
        "events": ["order.created"],
        "description": "n8n: new-order-to-sheets"
      },
      "name": "Pageyar Trigger",
      "type": "n8n-nodes-pageyar.pageyarTrigger",
      "typeVersion": 1,
      "position": [260, 300],
      "credentials": { "pageyarApi": { "id": "REPLACE_ME", "name": "Pageyar API" } }
    },
    {
      "parameters": {
        "operation": "append",
        "documentId": { "__rl": true, "value": "REPLACE_SHEET_ID", "mode": "id" },
        "sheetName": "Orders",
        "columns": {
          "mappingMode": "defineBelow",
          "value": {
            "id": "={{$json.data.id}}",
            "customer": "={{$json.data.customer.full_name}}",
            "phone": "={{$json.data.customer.phone}}",
            "total": "={{$json.data.total}}",
            "status": "={{$json.data.status}}",
            "created_at": "={{$json.data.created_at}}"
          }
        }
      },
      "name": "Append to Sheet",
      "type": "n8n-nodes-base.googleSheets",
      "typeVersion": 4,
      "position": [500, 300],
      "credentials": { "googleSheetsOAuth2Api": { "id": "REPLACE_ME", "name": "Google Sheets" } }
    }
  ],
  "connections": {
    "Pageyar Trigger": {
      "main": [[{ "node": "Append to Sheet", "type": "main", "index": 0 }]]
    }
  }
}

2) Card-to-card receipt uploaded → Telegram admin alert

Fires whenever a customer uploads a bank transfer receipt on their order — you get an instant Telegram DM with the amount + order link so a human can approve/reject quickly.

Nodes: Pageyar Trigger (event: payment.receipt_uploaded) → Telegram (operation: Send Message)

{
  "name": "Pageyar: Receipt uploaded → Telegram alert",
  "nodes": [
    {
      "parameters": {
        "events": ["payment.receipt_uploaded"],
        "description": "n8n: receipt-uploaded-alert"
      },
      "name": "Pageyar Trigger",
      "type": "n8n-nodes-pageyar.pageyarTrigger",
      "typeVersion": 1,
      "position": [260, 300],
      "credentials": { "pageyarApi": { "id": "REPLACE_ME", "name": "Pageyar API" } }
    },
    {
      "parameters": {
        "chatId": "REPLACE_TELEGRAM_CHAT_ID",
        "text": "=رسید تازه آپلود شد\nسفارش #{{$json.data.order.id}} — مبلغ {{$json.data.amount}} تومان\nمشتری: {{$json.data.order.customer.full_name}}\n{{$json.data.order.panel_url}}",
        "additionalFields": { "parse_mode": "Markdown" }
      },
      "name": "Notify Admin",
      "type": "n8n-nodes-base.telegram",
      "typeVersion": 1.2,
      "position": [500, 300],
      "credentials": { "telegramApi": { "id": "REPLACE_ME", "name": "Telegram Bot" } }
    }
  ],
  "connections": {
    "Pageyar Trigger": {
      "main": [[{ "node": "Notify Admin", "type": "main", "index": 0 }]]
    }
  }
}

3) New customer → HubSpot contact

Sync every new Pageyar customer into HubSpot as a contact for CRM follow-up.

Nodes: Pageyar Trigger (event: customer.created) → HubSpot (resource: Contact, operation: Create or Update)

{
  "name": "Pageyar: New customer → HubSpot contact",
  "nodes": [
    {
      "parameters": {
        "events": ["customer.created"],
        "description": "n8n: customer-to-hubspot"
      },
      "name": "Pageyar Trigger",
      "type": "n8n-nodes-pageyar.pageyarTrigger",
      "typeVersion": 1,
      "position": [260, 300],
      "credentials": { "pageyarApi": { "id": "REPLACE_ME", "name": "Pageyar API" } }
    },
    {
      "parameters": {
        "resource": "contact",
        "operation": "upsert",
        "email": "={{$json.data.email || $json.data.phone + '@pageyar.local'}}",
        "additionalFields": {
          "firstName": "={{$json.data.full_name}}",
          "phoneNumber": "={{$json.data.phone}}",
          "lifecycleStage": "lead"
        }
      },
      "name": "Upsert HubSpot Contact",
      "type": "n8n-nodes-base.hubspot",
      "typeVersion": 2.2,
      "position": [500, 300],
      "credentials": { "hubspotOAuth2Api": { "id": "REPLACE_ME", "name": "HubSpot" } }
    }
  ],
  "connections": {
    "Pageyar Trigger": {
      "main": [[{ "node": "Upsert HubSpot Contact", "type": "main", "index": 0 }]]
    }
  }
}

Regenerating a resource

Resources are generated from Pageyar's OpenAPI spec. To refresh after Pageyar's API changes:

cd path/to/n8n-nodes-pageyar
npm run gen:product          # reads ../pageyar/public/docs/openapi.json by default
npm run gen:order
npm run gen:customer
npm run gen:category
npm run gen:brand
npm run gen:discount-code
npm run gen:shipping-method
npm run gen:shipping-quote
npm run gen:delivery-blackout
npm run gen:return-reason
npm run gen:reward-rule
npm run gen:webhook-endpoint
npm run gen:webhook-delivery

Do NOT hand-edit nodes/Pageyar/resources/*.ts — regeneration will overwrite.

To add a NEW resource, extend RESOURCE_PLURALS in scripts/generate-node.ts (already prewired for all 23 public API resources) and add a matching gen:<name> script to package.json.

راهنمای فارسی

راهنمای اپراتور (نصب، credential، رویدادها) در docs/README-fa.md موجود است.

Known limitations (alpha)

• additionalFields: Per-resource typed fields collections are not populated yet — use the raw Body (JSON) input for now.
• Icon: The node icon is a placeholder; the final logo ships in a later session.
• Custom actions: A handful of Pageyar endpoints (POST /orders/{id}/status, /orders/{id}/repeat, POST /webhook-endpoints/{id}/test, /regenerate-secret, POST /webhook-deliveries/{id}/resend, POST /categories/reorder) don't fit the CRUD codegen and aren't in the Regular Node yet.
• Sub-resources: Nested paths like /customers/{id}/addresses or /orders/{id}/items need codegen extension for two-parameter paths.

Development

npm install
npm run build   # tsc + gulp build:icons
npm test        # jest
npm run lint    # eslint-plugin-n8n-nodes-base

License

MIT © 2026 milad azizi basir