如何使用 CleverInvo API 自动化开票

如果您每月发送的发票不止几张，您可能希望能自动化这个过程。也许您希望在项目管理工具中的项目完成时自动生成发票。或者您希望 CRM 在交易关闭时创建发票。又或者您只是想为所有固定客户批量生成月度发票，而不用点击表单五十次。

CleverInvo API 让这一切成为可能。本指南涵盖基础知识：身份验证、创建客户、生成发票以及设置 Webhook 以响应发票事件。

---

前提条件

API 在 Business 层级可用。您需要：

1. Business 计划的 CleverInvo 账户
2. API 密钥（从仪表板 > API 密钥生成）
3. 对 REST API 和 JSON 的基本了解

所有 API 请求使用 HTTPS 并返回 JSON 响应。基础 URL 为：

https://cleverinvo.com/api/v1

身份验证

在 Authorization 头中包含您的 API 密钥：

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients

所有没有有效 API 密钥的请求将收到 401 Unauthorized 响应。

---

管理客户

在创建发票之前，您需要在系统中有一个客户。客户 API 处理这个。

创建客户

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme 公司",
    "email": "[email protected]",
    "address": "商业大道 123 号，400 室\n纽约，NY 10001",
    "taxId": "US-EIN-12-3456789",
    "phone": "+1-555-0100"
  }'

列出客户

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

获取、更新或删除客户

# 获取
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients/cli_abc123def456

# 更新
curl -X PUT https://cleverinvo.com/api/v1/clients/cli_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1-555-0200"}'

# 删除
curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients/cli_abc123def456

---

创建发票

这是 API 真正价值所在。您可以通过单个 API 调用生成专业的、编号的发票。

创建发票

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "USD",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "网站重新设计 - 第一阶段",
        "quantity": 1,
        "unitPrice": 5000.00
      },
      {
        "description": "前端开发",
        "quantity": 40,
        "unitPrice": 150.00
      },
      {
        "description": "内容迁移",
        "quantity": 8,
        "unitPrice": 100.00
      }
    ],
    "notes": "感谢您的惠顾。",
    "terms": "30天内付款。逾期付款将按每月 1.5% 收取利息。"
  }'

系统自动：

• 分配下一个连续发票编号
• 计算行合计、小计和总计
• 生成 PDF 并返回 URL
• 将状态设置为 DRAFT

带税发票

要包含税款，请在每个行项目中添加 taxRate：

{
  "lineItems": [
    {
      "description": "咨询服务",
      "quantity": 20,
      "unitPrice": 200.00,
      "taxRate": 20
    }
  ]
}

API 将计算每行的税额并在响应中包含 taxTotal。

---

管理发票状态

发票经历一个生命周期：DRAFT（草稿）、SENT（已发送）、VIEWED（已查看）、PAID（已付款）、PARTIALLY_PAID（部分付款）、OVERDUE（逾期）。

更新状态

# 标记为已发送
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# 标记为已付款
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

---

常见集成模式

模式 1：CRM 到发票

当 CRM 中的交易关闭时，自动创建客户（如果是新客户）并生成发票：

async function onDealClosed(deal) {
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
      address: deal.customerAddress,
    });
  }

  const invoice = await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });

  console.log(`已为 ${client.name} 创建发票 ${invoice.invoiceNumber}`);
}

模式 2：月度固定费用计费

每月 1 号为所有固定客户生成发票：

async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });
  const today = new Date();
  const dueDate = addDays(today, 30);

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "USD",
        issueDate: today.toISOString().split("T")[0],
        dueDate: dueDate.toISOString().split("T")[0],
        lineItems: [
          {
            description: `月度固定费用 - ${format(today, "yyyy年M月")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
        terms: "Net 30",
      });
    }
  }
}

模式 3：工时跟踪集成

从工时跟踪工具中提取小时数并生成发票：

async function invoiceTrackedHours(clientId, startDate, endDate) {
  const entries = await timeTracker.getEntries({ clientId, startDate, endDate });

  const lineItems = groupByProject(entries).map((group) => ({
    description: `${group.projectName}（${group.totalHours} 小时）`,
    quantity: group.totalHours,
    unitPrice: group.hourlyRate,
  }));

  const invoice = await cleverinvo.invoices.create({
    clientId,
    currency: "USD",
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems,
    notes: `从 ${startDate} 到 ${endDate} 跟踪的工时`,
  });

  return invoice;
}

---

速率限制

API 强制执行速率限制以确保公平使用：

层级	限制
Business	每分钟 100 个请求

如果超出限制，API 返回 429 Too Many Requests 并带有 Retry-After 头。

---

错误处理

所有错误返回一致的 JSON 结构：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "clientId 是必填项",
    "details": [
      {"field": "clientId", "message": "此字段为必填"}
    ]
  }
}

常见错误代码：

代码	HTTP 状态	含义
UNAUTHORIZED	401	无效或缺失的 API 密钥
FORBIDDEN	403	您的层级不支持 API 访问
NOT_FOUND	404	资源不存在
VALIDATION_ERROR	422	请求数据无效
RATE_LIMITED	429	请求过多
INTERNAL_ERROR	500	服务器错误（请联系支持）

---

下一步

CleverInvo API 旨在适配您现有的工作流程——无论是简单的定时任务还是复杂的多系统集成。从单个用例开始，让它运行起来，然后扩展。

完整的 API 文档可在 /docs/api 获取，包括 OpenAPI 规范和更多代码示例。

获取您的 API 密钥 ->