InvoiceForge API 技能

使用VCG的InvoiceForge API生成专业PDF发票——纯软件发票生成，包含自动计算、PDF渲染和发票管理。

快速开始

1. 1. 获取API密钥：帮助用户注册免费InvoiceForge API密钥
2. 存储密钥：安全保存密钥
3. 创建发票：从结构化数据生成专业PDF发票

API密钥注册

第1步：获取用户邮箱

询问用户的邮箱地址以创建免费InvoiceForge账户。

第2步：通过API注册

bash curl -X POST https://invoiceforge.vosscg.com/v1/keys \ -H Content-Type: application/json \ -d {email:user@example.com}

预期响应：
json
{
api_key: your-api-key-here,
plan: free
}

第3步：存储API密钥

安全保存API密钥以备将来使用。

创建发票

创建完整发票

bash curl -X POST https://invoiceforge.vosscg.com/v1/invoices \ -H X-API-Key: YOUR_KEY \ -H Content-Type: application/json \ -d { seller: { name: Acme Consulting, email: billing@acme.com, address: 123 Main St, San Francisco, CA 94102 }, buyer: { name: Widget Corp, email: ap@widget.com, address: 456 Oak Ave, New York, NY 10001 }, items: [ {description: Strategy Consulting - March 2026, quantity: 40, unit_price: 250.00}, {description: Travel Expenses, quantity: 1, unit_price: 1200.00} ], tax_rate: 8.5, currency: USD, due_date: 2026-04-15, notes: Net 30. Wire transfer preferred. }

预期响应：
json
{
invoice_number: INV-000001,
subtotal: 11200.00,
tax_rate: 8.5,
tax_amount: 952.00,
total: 12152.00,
currency: USD,
status: draft,
created_at: 2026-03-04T...,
download_url: /v1/invoices/INV-000001/pdf
}

下载发票PDF

bash curl -H X-API-Key: YOUR_KEY \ https://invoiceforge.vosscg.com/v1/invoices/INV-000001/pdf \ -o invoice.pdf

列出所有发票

bash curl -H X-API-Key: YOUR_KEY \ https://invoiceforge.vosscg.com/v1/invoices?status=draft&page=1&limit=20

更新发票状态

bash curl -X PATCH https://invoiceforge.vosscg.com/v1/invoices/INV-000001/status \ -H X-API-Key: YOUR_KEY \ -H Content-Type: application/json \ -d {status: sent}

有效状态：draft、sent、paid、void

常见用例

自由职业者月度发票

当用户说为我的客户创建发票时：

1. 1. 询问卖家信息（他们的企业名称、邮箱、地址）
2. 询问买家信息（客户名称、邮箱、地址）
3. 询问明细项（服务、工时、费率）
4. 询问税率和到期日期
5. 通过API创建发票
6. 下载并分享PDF

批量开票

通过循环处理客户数据创建多张发票。每次POST请求都会创建一个带有自动递增编号的新发票。

发票跟踪

使用带状态筛选的列表端点跟踪：

• - draft — 已创建但未发送
• sent — 已发送给客户
• paid — 已收到付款
• void — 已取消

支持的货币

任何3字母ISO 4217代码：USD、EUR、GBP、CAD、AUD、JPY等。

速率限制

• - 免费版：每天100次请求，每月50张发票
• 专业版：无限制（Stripe计费）

API基础URL

https://invoiceforge.vosscg.com

端点汇总

方法	路径	描述
POST	/v1/keys	创建API密钥
POST

/v1/invoices | 创建发票 |

| GET | /v1/invoices | 列出发票 | | GET | /v1/invoices/:id/pdf | 下载PDF | | PATCH | /v1/invoices/:id/status | 更新状态 | | GET | /v1/health | 健康检查 | | GET | /v1/metrics | 服务指标 |

错误处理

• - 400 — 验证错误（缺少字段、数据错误）
• 401 — 缺少或无效的API密钥
• 404 — 未找到发票
• 403 — 访问被拒绝（非您的发票）
• 429 — 超出速率限制