kiotviet-client

name	kiotviet-client
description	Dùng khi cần client reverse API KiotViet, token, gian hàng, chi nhánh, sản phẩm, khách hàng, bảng giá, hóa đơn, đơn hàng, tồn kho, công nợ, báo cáo, nhà cung cấp, danh mục, job import, hoặc script API.

KiotViet Client

Mục tiêu

Skill này là nguồn thật cho mọi thao tác KiotViet trong dự án.

Nó dùng reverse API từ phiên đăng nhập hợp lệ. Không dùng Public API Business.

Khi dùng

Dùng khi cần:

• Kiểm tra phiên KiotViet.
• Tải khách hàng, sản phẩm, bảng giá, hóa đơn, đơn hàng.
• CRUD khách hàng, nhà cung cấp, danh mục.
• Xem tồn kho, sổ kho, sản phẩm dưới mức tối thiểu.
• Xem công nợ khách hàng/NCC, phiếu thu chi.
• Báo cáo lợi nhuận, tồn kho, doanh thu theo nhân viên/thời gian.
• Tạo, sửa, hủy đơn hàng.
• Import sản phẩm, bảng giá, hóa đơn từ Excel.
• Tạo, sửa, xóa sản phẩm bằng endpoint UI.
• Bảo trì endpoint đã reverse từ HAR.

Không dùng khi người dùng chỉ hỏi khái niệm chung.

Tệp chính

.agents/skills/kiotviet-client/
├── SKILL.md
├── scripts/
│   ├── api_client.py
│   ├── check_session.py
│   ├── ensure_session.py
│   ├── kiotviet_download_templates.py
│   ├── kiotviet_export.py
│   └── kiotviet_write_gate.py
└── references/
    └── client-book.md

Cấu hình bắt buộc

Cấu hình có thể đặt trong biến môi trường hoặc file .env ở thư mục dự án.

Tạo từ mẫu:

cp .env.example .env

Điền các biến:

export KIOTVIET_TOKEN="JWT token từ localStorage.kf-accessToken"
export KIOTVIET_RETAILER="mã gian hàng"
export KIOTVIET_BRANCH_ID="ID chi nhánh"
export KIOTVIET_GROUP_ID="ID nhóm"
export KIOTVIET_FINGERPRINT_KEY="localStorage.FingerPrintKey"
export KIOTVIET_RETAILER_ID="ID retailer từ get_current_retailer"

Không ghi các giá trị này vào repo.

Biến môi trường shell ưu tiên hơn giá trị trong .env.

Lệnh kiểm tra nhanh

test -d ~/.venv/claude || uv venv ~/.venv/claude
uv pip install --python ~/.venv/claude/bin/python requests urllib3
~/.venv/claude/bin/python .agents/skills/kiotviet-client/scripts/ensure_session.py
~/.venv/claude/bin/python .agents/skills/kiotviet-client/scripts/check_session.py

Nếu lỗi 401 hoặc 403, dừng lại và yêu cầu người dùng làm mới token.

ensure_session.py giải mã hạn JWT, refresh khi token còn dưới 24 giờ, rồi cập nhật .env.

Ép refresh:

~/.venv/claude/bin/python .agents/skills/kiotviet-client/scripts/ensure_session.py --force-refresh

Nếu token đã chết hẳn, mở lại phiên bằng Chrome DevTools MCP:

~/.venv/claude/bin/python .agents/skills/reverse-engineering-api/scripts/start_chrome_mcp.py \
  --retailer "$KIOTVIET_RETAILER"

Script chỉ mở Chrome với profile .browser-profiles/kiotviet. Agent dùng Chrome DevTools MCP để đọc localStorage và cập nhật .env.

Output tiếng Việt trên Windows

Các script CLI in tiếng Việt hoặc JSON ensure_ascii=False phải gọi configure_utf8_output() ở đầu main().

Nếu chạy trực tiếp trên Windows mà terminal vẫn lỗi dấu, đặt PYTHONIOENCODING=utf-8 trước khi chạy.

Xuất dữ liệu chuẩn

~/.venv/claude/bin/python .agents/skills/kiotviet-client/scripts/kiotviet_export.py \
  --output-root data \
  --types customers products pricebooks

Kết quả nằm ở:

data/raw/YYYYMMDD_HHMMSS/

kiotviet_export.py tự chạy ensure_session.py trước khi xuất dữ liệu.

Tải template import

Template import gốc lưu trong:

templates/

Tải đủ mẫu hàng hóa, bảng giá, và hóa đơn:

~/.venv/claude/bin/python .agents/skills/kiotviet-client/scripts/kiotviet_download_templates.py \
  --types all \
  --output-dir templates

Tên file chuẩn:

templates/MauFileSanPham.xlsx
templates/MauFileBangGia.xlsx
templates/MauFileDanhSachHoaDon.xlsx

Nguyên tắc an toàn

• Chỉ dùng tài khoản KiotViet người dùng có quyền hợp lệ.
• Không bypass đăng nhập, captcha, chống bot, hoặc phân quyền.
• Không lưu token, cookie, mật khẩu, HAR chứa secret vào repo.
• Trước thao tác ghi, luôn chạy ensure_session.py, rồi chạy check_session.py.
• Trước thao tác ghi, luôn tạo và kiểm qa_report.json.
• Dùng kiotviet_write_gate.validate_apply_gate để chặn apply thiếu QA hoặc sai xác nhận.
• Với import, update, tạo mới, hoặc xóa, luôn tạo báo cáo trước và xin xác nhận.
• Method ghi bắt buộc có confirmed=True.
• Chỉ truyền confirmed=True sau khi user xác nhận rõ sẽ cập nhật gì và sẽ tạo mới gì.

Hợp đồng xác nhận ghi

Trước khi truyền confirmed=True, báo rõ:

• sẽ cập nhật gì.
• sẽ tạo mới gì.
• sẽ xóa gì nếu có.
• số lượng bản ghi bị tác động.
• mã hàng hoặc mã đối tượng liên quan.
• giá trị trước/sau với trường quan trọng.
• phạm vi chi nhánh hoặc toàn hệ thống.

Nếu thiếu một mục quan trọng, dừng và bổ sung report trước.

Bảo trì endpoint

Khi endpoint lỗi do KiotViet đổi giao diện, dùng skill reverse-engineering-api.

Quy trình ngắn:

1. Lấy HAR từ thao tác thật.
2. Lọc endpoint api-man1.kiotviet.vn.
3. So sánh request mới với method trong api_client.py.
4. Vá client nhỏ nhất.
5. Chạy check_session.py và lệnh nghiệp vụ liên quan.

Chi tiết endpoint, helper, ví dụ nằm trong references/client-book.md.