API 参考文档

商业计划

将 CleverInvo 集成到您的工作流程中。以编程方式管理客户、创建发票并下载 PDF。

身份验证

所有 API 请求都需要 Bearer 令牌。从您的控制面板创建 API 密钥，然后将其包含在 Authorization 标头中。

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

客户

GET/api/v1/clients

列出所有活跃客户。支持分页和搜索。

响应
{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/clients

创建新客户。受您的计划客户限制约束。

请求体
{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}
响应
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
GET/api/v1/clients/:id

通过 ID 获取单个客户。

响应
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
PUT/api/v1/clients/:id

更新客户。所有字段均可修改。

请求体
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
响应
{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}
DELETE/api/v1/clients/:id

软删除客户。将 isActive 设置为 false。有现有发票的客户无法硬删除。

响应
204 No Content

发票

GET/api/v1/invoices

列出发票。支持分页、搜索以及按 clientId 或状态筛选。

响应
{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/invoices

创建发票并自动生成 PDF。受计划限制约束。

请求体
{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}
响应
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

获取完整的发票详情，包括明细项和客户信息。

响应
{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}
PUT/api/v1/invoices/:id

更新发票。仅草稿发票可修改。

请求体
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
响应
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

永久删除发票及其生成的 PDF。

响应
204 No Content
GET/api/v1/invoices/:id/pdf

将发票下载为 PDF 文件。返回带有 Content-Disposition 标头的二进制 PDF。

响应
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

分页

列表端点接受以下查询参数：

参数默认值描述
page1页码（最小值：1）
limit20每页项目数（1–100）
search—按名称、电子邮件或发票编号筛选（最多 255 个字符）
clientId—按客户筛选发票（仅限发票）
status—按状态筛选：DRAFT、SENT、VIEWED、PAID、PARTIALLY_PAID、OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

错误

API 返回标准 HTTP 状态码。错误响应包含带有 error 字段的 JSON 正文。

状态码描述
400错误请求 — 无效参数或缺少必填字段
401未授权 — 无效或缺少 API 密钥
403禁止 — 已达到计划限制（客户、发票或功能）
404未找到 — 资源不存在或无法访问
429请求过多 — 超出速率限制
500内部服务器错误 — 意外故障，请稍后重试
{
  "error": "Missing required field: name"
}

速率限制

API 请求的速率限制为每个 API 密钥 每分钟 120 个请求。

超出限制时，请求将返回 429 Too Many Requests。请等待后重试。