创建和更新客户

概述

在上一课中，我们提取了已认证用户的 ACCOUNT_ID。这里的“用户”指的是管理并操作应用程序的管理员。用户负责发起所有 API 调用。而“客户”则是用户所维护记录的实体。

本章将介绍与客户和联系人相关的一些操作。在本课中，我们将使用以下端点创建并更新客户：

• 创建和列出客户：{base_url}/accounting/account/{ACCOUNT_ID}/users/clients
• 更新客户：{base_url}/accounting/account/{ACCOUNT_ID}/users/clients/{CLIENT_ID}

注意：
这些客户相关的端点需要 user:clients:read 和 user:clients:write 权限才能执行相应操作。

创建客户

本节我们将使用 {base_url}/accounting/account/{ACCOUNT_ID}/users/clients 端点创建一个新客户。该端点使用 HTTP 的 POST 方法，在 FreshBooks 账户中创建一个新的客户。后续课程中，我们将向此客户进行付款并发送发票。

请求头（Headers）

请求头通常包含以下内容：

• Content-Type：定义请求的格式，通常值为 application/json。
• Authorization：定义 FreshBooks 端点使用的认证类型。这些端点使用 Bearer Token 进行身份验证，以确认请求的有效性。

请求参数

该端点接收一个名为 client 的对象作为参数。以下是 client 对象的字段说明：

1import requests
2import json
3
4url = "https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients"
5
6payload = json.dumps({
7    "client": {
8        "email": "<客户邮箱>",
9        "fname": "John",
10        "lname": "Doe",
11        "organization": "Example, Inc.",
12        "p_street": "---",
13        "p_city": "Bellevue",
14        "p_province": "Washington",
15        "p_code": "425"
16    }
17})
18
19headers = {
20    'Content-Type': 'application/json',
21    'Authorization': 'Bearer {{AUTH_CODE}}'
22}
23
24response = requests.request("POST", url, headers=headers, data=payload)
25if response.status_code != 200:
26    print("发生错误。")
27
28print(json.dumps(response.json(), indent=4))

响应中的 id 字段即为新建客户的 ID，后续调用时将其作为 CLIENT_ID 使用。

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

• 第 4 行：定义用于创建客户的 URL。
• 第 6 至 17 行：定义 payload 对象，其中包含 client 对象及表格中列出的八个字段。
• 第 19 至 22 行：设置请求头，指定内容类型和授权信息。
• 第 24 行：发起 POST 请求。
• 第 25 至 26 行：检查响应状态码，并根据结果输出提示信息。
• 第 28 行：打印响应内容。

响应

成功调用后，系统将创建客户并返回一个包含全部信息的 client 对象。以下是 client 对象中一些重要字段的说明：

更新客户

现在我们已经创建了一个客户，接下来尝试对其进行更新。我们需要在相同端点末尾添加客户 ID，即 users/clients/{CLIENT_ID}。以下是更新客户信息的代码示例：

1import requests
2import json
3
4url = "https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients/{{CLIENT_ID}}"
5
6payload = json.dumps({
7    "client": {
8        "fname": "Educative Inc.",
9        "lname": ""
10    }
11})
12
13headers = {
14    'Content-Type': 'application/json',
15    'Authorization': 'Bearer {{AUTH_CODE}}'
16}
17
18response = requests.request("PUT", url, headers=headers, data=payload)
19if response.status_code != 200:
20    print("发生错误。")
21
22print(json.dumps(response.json(), indent=4))

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

• 第 4 行：定义用于更新客户信息的 URL。与创建客户时使用的 URL 类似，唯一的区别是末尾附加了客户 ID。
• 第 6 至 11 行：定义 payload 对象，其中包含 client 对象，以及要更新的字段。
• 第 13 至 16 行：设置请求头。
• 第 18 行：发起 PUT 请求以更新客户信息。
• 第 22 行：打印响应内容。

响应

该端点返回的响应结构与创建客户时相同。我们可以看到，客户信息已按要求更新。

列出所有客户

我们可以通过对创建客户所用的 URL 发送 HTTP GET 请求，获取 FreshBooks 账户中所有客户的列表。

请求参数

该端点不接受任何参数。以下是具体实现代码：

1import requests
2import json
3
4url = "https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients"
5
6payload = {}
7
8headers = {
9    'Content-Type': 'application/json',
10    'Authorization': 'Bearer {{AUTH_CODE}}'
11}
12
13response = requests.request("GET", url, headers=headers, data=payload)
14if response.status_code != 200:
15    print("发生错误。")
16
17print(json.dumps(response.json(), indent=4))

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

• 第 4 行：定义请求的 URL。
• 第 13 行：发起 GET 请求，调用第 4 行指定的 URL。
• 第 17 行：打印响应结果。

响应

上述代码成功执行后，将返回 FreshBooks 账户中的所有客户信息。响应字段与之前讨论的内容一致。