n8n-nodes-cpc1hn-member

Node n8n cộng đồng kết nối hệ thống CPC1 Hà Nội qua Laravel Passport OAuth2.

Tính năng

• ✅ Xác thực OAuth2 Authorization Code (Laravel Passport)
• ✅ URL authorize/token được cấu hình sẵn — không cần điền tay
• ✅ API Chung — Gọi bất kỳ endpoint nào (GET/POST/PUT/PATCH/DELETE)
• ✅ Smart Factory — Lấy dữ liệu cảm biến nhóm theo thiết bị
• ✅ Hỗ trợ Query Parameters, JSON Body, lọc theo device_id[]
• ✅ Tương thích n8n Queue Mode (main + worker)
• ✅ URL có thể override qua biến môi trường Docker
• ✅ Dùng được trong AI Agent (usableAsTool: true)

Cài đặt

Trong n8n: Settings → Community Nodes → Install

n8n-nodes-cpc1hn-member

Cấu hình

1. Credential: CPC1 Hà Nội OAuth2

| Field | Mô tả | |---|---| | Client ID | OAuth2 Client ID (lấy từ hệ thống CPC1HN) | | Client Secret | OAuth2 Client Secret | | API Base URL | URL gốc API, mặc định https://api.cpc1hn.com.vn |

Authorization URL và Access Token URL đã được cấu hình sẵn — không cần điền.

2. Node: CPC1 Hà Nội

Node có 2 resource — chọn trong dropdown Resource:

🔗 API Chung — Gọi API tùy chỉnh

| Field | Mô tả | |---|---| | API Version | Phiên bản API (hiện tại: v4) | | HTTP Method | GET / POST / PUT / PATCH / DELETE | | Endpoint | Đường dẫn API, ví dụ: /users, /me, /users/1 | | Gửi Body | Bật để gửi JSON body (chỉ hiện khi method là POST/PUT/PATCH) | | Body (JSON) | Nội dung JSON gửi kèm request | | Tùy chọn | Query Parameters, Bỏ qua lỗi SSL |

📊 Smart Factory — Lấy dữ liệu cảm biến

| Field | Mô tả | |---|---| | API Version | Phiên bản API (hiện tại: v4) | | Thời gian từ | Thời gian bắt đầu (date picker) | | Thời gian đến | Thời gian kết thúc (date picker) | | Lọc thiết bị | Danh sách Device ID cần lấy (bỏ trống = lấy tất cả) |

Output: Mỗi thiết bị trong data[] trở thành 1 n8n item riêng biệt để dễ xử lý downstream.

Cấu hình qua biến môi trường

Thêm vào file .env của n8n Docker để tùy chỉnh URL:

CPC1HN_AUTH_URL=https://sos.cpc1hn.com.vn/oauth/authorize
CPC1HN_TOKEN_URL=https://oauth.cpc1hn.com.vn/oauth/token
CPC1HN_DOCS_URL=https://sos.cpc1hn.com.vn
CPC1HN_API_BASE_URL=https://api.cpc1hn.com.vn

Sau khi thay đổi env, restart n8n và tạo lại credential mới để áp dụng.

Pre-fill Client ID / Secret

Thêm vào CREDENTIALS_OVERWRITE_DATA trong .env:

CREDENTIALS_OVERWRITE_DATA={"cpc1hnOAuth2Api":{"clientId":"xxx","clientSecret":"xxx"}}

Phát triển

# Cài dependencies
npm install

# Build
npm run build

# Theo dõi thay đổi (watch mode)
npm run dev

Mở rộng node — Thêm resource / operation / action mới

Cấu trúc dự án được tổ chức theo module để dễ mở rộng:

nodes/Cpc1hn/
├── Cpc1hn.node.ts                    ← File chính (chỉ wire, không chứa logic)
├── GenericFunctions.ts               ← Tiện ích dùng chung giữa các action
├── descriptions/
│   ├── index.ts                      ← Re-export tất cả descriptions
│   ├── shared.description.ts         ← apiVersion + resource (field dùng chung)
│   ├── ApiChung.description.ts       ← UI fields của resource "API Chung"
│   └── SmartFactory.description.ts   ← UI fields của resource "Smart Factory"
└── actions/
    ├── apiChung.action.ts            ← Execute logic của API Chung
    └── smartFactory.action.ts        ← Execute logic của Smart Factory

Ví dụ: Thêm resource "Nhân sự" với operation "Lấy danh sách nhân viên"

Bước 1 — Tạo file description descriptions/NhanSu.description.ts:

import type { INodeProperties } from 'n8n-workflow';

export const nhanSuDescription: INodeProperties[] = [
    // Operation
    {
        displayName: 'Operation',
        name: 'operation',
        type: 'options',
        noDataExpression: true,
        options: [
            {
                name: 'Lấy danh sách nhân viên',
                value: 'getEmployees',
                description: 'Lấy toàn bộ danh sách nhân viên',
                action: 'Lấy danh sách nhân viên',
            },
        ],
        default: 'getEmployees',
        displayOptions: { show: { resource: ['nhanSu'] } },
    },
    // Thêm các field khác ở đây...
];

Bước 2 — Tạo file action actions/nhanSu.action.ts:

import type { IExecuteFunctions, INodeExecutionData } from 'n8n-workflow';

export async function getEmployeesAction(
    ctx: IExecuteFunctions,
    itemIndex: number,
    apiBaseUrl: string,
): Promise<INodeExecutionData[]> {
    const apiVersion = ctx.getNodeParameter('apiVersion', itemIndex) as string;
    const response = await ctx.helpers.httpRequestWithAuthentication.call(
        ctx,
        'cpc1hnOAuth2Api',
        { method: 'GET', url: `${apiBaseUrl}/${apiVersion}/employees`, json: true },
    );
    return [{ json: response as object, pairedItem: { item: itemIndex } }];
}

Bước 3 — Đăng ký trong descriptions/index.ts:

export { nhanSuDescription } from './NhanSu.description';

Bước 4 — Thêm option vào descriptions/shared.description.ts (mục resource):

{ name: 'Nhân sự', value: 'nhanSu', description: 'Quản lý nhân viên' },

Bước 5 — Wire vào Cpc1hn.node.ts:

// Import
import { nhanSuDescription } from './descriptions';
import { getEmployeesAction } from './actions/nhanSu.action';

// Trong properties[]
...nhanSuDescription,

// Trong execute()
else if (resource === 'nhanSu' && operation === 'getEmployees') {
    returnItems.push(...(await getEmployeesAction(this, i, apiBaseUrl)));
}

Bước 6 — Build và publish:

npm run build
# Kiểm tra rồi tăng version trong package.json
npm publish --access public

Publish lên npm

npm publish --access public

Báo lỗi

Tạo issue tại: GitHub Issues

License

MIT © Tho Thanh Tâm