添加和更新项目

在本节课中，我们将向 FreshBooks 账户添加一些项目，以便为客户创建发票和付款。我们将使用以下接口：

• 创建项目：/accounting/account/{ACCOUNT_ID}/items/items
• 更新项目：/accounting/account/{ACCOUNT_ID}/items/items/{ITEM_ID}

我们的应用程序需要具备 user:billable_items:read 和 user:billable_items:write 权限，才能通过 FreshBooks API 对项目执行不同操作。

创建项目

本节介绍如何在 FreshBooks 账户中创建一个新项目。我们使用 /accounting/account/{ACCOUNT_ID}/items/items 接口来创建新项目，该接口采用 HTTP 的 POST 请求方式。

请求参数

bodyParameters 对象包含一个 item 对象，其中包含与该项目相关的信息。以下是 item 对象的部分字段说明：

1// 导入所需库
2const fetch = require('node-fetch');
3
4// 定义接口地址
5const endpointUrl = 'https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/items/items';
6
7const headerParameters = {
8  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
9  'Content-Type': 'application/json',
10};
11
12// 定义请求体参数
13const bodyParameters = JSON.stringify({
14  "item": {
15    "name": "示例项目",
16    "qty": "1",
17    "inventory": "10",
18    "unit_cost": {
19      "amount": "49.00",
20      "code": "EUR"
21    },
22    "vis_state": 0,
23    "description": "关于示例项目的简要说明"
24  }
25});
26
27// 设置 API 请求选项
28const options = {
29  method: 'POST',
30  headers: headerParameters,
31  body: bodyParameters,
32};
33
34// 发起 API 请求的函数
35async function createItem() {
36  try {
37    const response = await fetch(`${endpointUrl}`, options);
38    printResponse(response);
39  } catch (error) {
40    // 打印错误信息
41    printError(error);
42  }
43}
44
45// 调用函数发起请求
46createItem();

执行后，系统将成功创建一个项目，并返回该项目的 ID。请记下返回的项目 ID，后续操作会用到。

让我们分析上述代码中的关键部分：

• 第 5 行：定义了用于创建项目的接口地址。
• 第 14 至 25 行：定义了 item 对象，包含项目的各项属性。
• 第 37 行：使用 fetch 函数发起 POST 请求。
• 第 46 行：调用 createItem 函数执行请求。

响应字段

上述代码成功执行后，将返回一个嵌套的项目对象。响应中的货币代码可能与代码中指定的不同，这是因为 FreshBooks 账户的基础货币会覆盖代码中设定的货币。

注意：请再次运行上述代码，尝试不同的参数值。我们需要至少再添加一个项目，以便在后续章节中使用。

更新项目

我们已在 FreshBooks 账户中创建了一个名为“示例项目”的项目。现在，我们来更新它。

请求参数

在下面的代码中，我们将更新项目的 name 和 description 字段。

注意：如果访问令牌已过期，请先重新生成再运行代码。

1// 导入所需库
2const fetch = require('node-fetch');
3
4// 定义接口地址
5const endpointUrl = 'https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/items/items/{{ITEM_ID}}';
6
7const headerParameters = {
8  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
9  'Content-Type': 'application/json',
10};
11
12// 定义请求体参数
13const bodyParameters = JSON.stringify({
14  "item": {
15    "name": "已更新的示例项目",
16    "description": "关于已更新示例项目的补充说明"
17  }
18});
19
20// 设置 API 请求选项
21const options = {
22  method: 'PUT',
23  headers: headerParameters,
24  body: bodyParameters,
25};
26
27// 发起 API 请求的函数
28async function updateItem() {
29  try {
30    const response = await fetch(`${endpointUrl}`, options);
31    printResponse(response);
32  } catch (error) {
33    // 打印错误信息
34    printError(error);
35  }
36}
37
38// 调用函数发起请求
39updateItem();

让我们分析上述代码中的关键部分：

• 第 5 行：定义了本次请求的接口地址。
• 第 14 至 18 行：定义了要更新的 item 对象，包含新的 name 和 description。
• 第 30 行：使用 fetch 函数发起 PUT 请求。
• 第 39 行：调用 updateItem 函数执行请求。

响应字段

代码成功执行后，将返回更新后的 item 对象，其中包含新的名称和描述。各字段的具体含义可参考“请求参数与响应字段”课程内容。