API & MCP

KOPA xuất bản 2 interface cho automation và integration:

• REST API — https://api.getkopa.com
• MCP server — https://mcp.getkopa.com/mcp

Authentication#

API tokens (Personal Access Token)#

1. Vào KOPA → Settings → Account → API tokens.
2. + Tạo token mới → đặt tên, chọn scope.
3. KOPA hiện token một lần — copy ngay.

Format:

kopa_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sử dụng token#

Đính kèm header:

Authorization: Bearer kopa_pat_xxxx

REST API#

OpenAPI spec#

• Spec: https://api.getkopa.com/openapi.json
• Interactive UI (Swagger): https://api.getkopa.com/docs

Endpoints chính#

GET  /api/v1/companies
GET  /api/v1/companies/{id}/journal-entries
POST /api/v1/companies/{id}/journal-entries
GET  /api/v1/companies/{id}/reports/balance-sheet
GET  /api/v1/companies/{id}/reports/p-l
GET  /api/v1/banking/transactions
GET  /api/v1/documents
POST /api/v1/documents/upload
GET  /api/v1/sessions
POST /api/v1/sessions

Rate limits#

• Starter: 100 requests/phút.
• Growth: 1,000 requests/phút.
• Enterprise: custom.

Header response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1714128000

Errors#

KOPA dùng standard HTTP status codes:

• 200 — OK.
• 400 — Bad request.
• 401 — Unauthorized.
• 403 — Forbidden (no permission).
• 404 — Not found.
• 422 — Validation error.
• 429 — Rate limited.
• 5xx — Server error.

Body lỗi:

{
  "error": {
    "code": "validation_error",
    "message": "amount must be positive",
    "field": "amount",
    "trace_id": "tr_xxx"
  }
}

Webhooks#

KOPA gửi webhook cho events:

• journal_entry.created
• journal_entry.approved
• document.received
• period.closed
• alert.triggered

Cấu hình tại Settings → Webhooks.

MCP server#

KOPA xuất bản MCP server read-only cho dữ liệu kế toán.

Server card#

https://getkopa.com/.well-known/mcp/server-card.json

{
  "serverInfo": {
    "name": "kopa-accounting",
    "version": "1.0.0",
    "description": "KOPA Vietnamese accounting tools (read-only)"
  },
  "transport": {
    "type": "streamable-http",
    "endpoint": "https://mcp.getkopa.com/mcp"
  },
  "auth": {
    "type": "bearer"
  },
  "capabilities": ["tools"]
}

Tools#

MCP server expose 20+ tool read-only:

• getCompanies — list công ty.
• getJournalEntries(filters) — bút toán.
• getBalanceSheet(period) — bảng cân đối.
• getPLStatement(period) — P&L.
• getCashFlow(period) — lưu chuyển tiền tệ.
• getBankBalance(account) — số dư.
• getCustomers / getSuppliers — danh sách đối tượng.
• getInventory — tồn kho.
• searchDocuments(query) — search chứng từ.
• getKPI(name, period) — KPI value.
• runReport(name, params) — chạy báo cáo.

Setup với Claude Desktop#

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "kopa": {
      "url": "https://mcp.getkopa.com/mcp",
      "auth": {
        "type": "bearer",
        "token": "kopa_pat_xxxx"
      }
    }
  }
}

Khởi động lại Claude Desktop. Hỏi:

"Theo data từ KOPA, doanh thu tháng 4 của Sao Mai bao nhiêu?"

Claude sẽ gọi tool getPLStatement và trả lời.

Setup với Cursor#

Tương tự — edit ~/.cursor/mcp.json với cấu hình giống Claude Desktop.

Setup với ChatGPT#

OpenAI sắp hỗ trợ MCP native. Tạm thời dùng Custom GPT + KOPA REST API.

SDK#

KOPA cung cấp SDK official cho:

• TypeScript / JavaScript — npm install @kopa/sdk
• Python — pip install kopa (Q3 2026)

import { KopaClient } from '@kopa/sdk';

const client = new KopaClient({ token: 'kopa_pat_xxx' });

const entries = await client.journalEntries.list({
  companyId: 'co_xxx',
  period: '2024-04',
});

API discovery (RFC 9727)#

KOPA publish discovery endpoints theo standard:

• API catalog: https://getkopa.com/.well-known/api-catalog
• OpenID Connect: https://getkopa.com/.well-known/openid-configuration
• OAuth Protected Resource: https://getkopa.com/.well-known/oauth-protected-resource
• Agent Skills: https://getkopa.com/.well-known/agent-skills/index.json

Hỗ trợ#

• Email: api@getkopa.com
• GitHub: github.com/getkopa/sdk-issues
• Status page: status.getkopa.com