添加和更新项目

概述

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

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

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

创建项目

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

请求参数

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

1import requests
2import json
3
4url = "https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/items/items"
5
6payload = json.dumps({
7    "item": 
8    {
9        "name": "示例项目",
10        "qty": "1",
11        "inventory": "10",
12        "unit_cost": {
13            "amount": "49.00",
14            "code": "EUR"
15        },
16        "vis_state": 0,
17        "description": "关于示例项目的简要说明"
18    }
19})
20
21headers = {
22  'Content-Type': 'application/json',
23  'Authorization': 'Bearer {{AUTH_CODE}}'
24}
25
26response = requests.request("POST", url, headers=headers, data=payload)
27if response.status_code != 200:
28    print("发生错误。")
29
30print(json.dumps(response.json(), indent=4))

执行成功后，系统将创建一个新项目，并返回其 ID。请记录返回的项目 ID，以便在后续操作中使用。

让我们分析上述代码中的高亮部分：

• 第 4 行：定义了创建项目的 URL。
• 第 7 至 18 行：定义了包含项目属性的 item 对象。
• 第 26 行：发起 POST 请求。
• 第 30 行：打印响应结果。

响应

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

注意：为了后续章节的使用，我们需要在 FreshBooks 账户中至少再添加一个项目。

更新项目

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

请求参数

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

1import requests
2import json
3
4url = "https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/items/items/{{ITEM_ID}}"
5
6payload = json.dumps({
7    "item": 
8    {
9        "name": "已更新的示例项目",
10        "description": "关于已更新示例项目的最新说明"
11    }
12})
13
14headers = {
15    'Content-Type': 'application/json',
16    'Authorization': 'Bearer {{AUTH_CODE}}'
17}
18
19response = requests.request("PUT", url, headers=headers, data=payload)
20if response.status_code != 200:
21    print("发生错误。")
22
23print(json.dumps(response.json(), indent=4))

让我们分析上述代码中的高亮部分：

• 第 9 至 10 行：定义了需要更新的项目名称和描述。
• 第 19 行：发起 PUT 请求。
• 第 23 行：打印响应结果。

响应

上述代码成功执行后，返回的 item 对象将包含更新后的名称和描述。