导入
创建和更新客户
学习如何使用 FreshBooks API 创建新客户并更新客户信息。
在本节中，我们将使用 /accounting/account/{ACCOUNT_ID}/users/clients 端点创建一个新客户。该端点采用 HTTP 的 POST 方法，在我们的 FreshBooks 账户中创建一个新客户。在接下来的课程中，我们将向此客户进行付款并发送发票。
请求参数
该端点接收一个 client 对象作为参数。以下是 client 对象字段的说明：
| 参数名称 | 类型 | 可选性 | 描述 |
|---|---|---|---|
| 字符串 | 可选 | 与客户关联的有效邮箱地址 | |
| fname | 字符串 | 可选 | 客户的名字 |
| lname | 字符串 | 可选 | 客户的姓氏 |
| organization | 字符串 | 可选 | 客户公司的名称。如果未提供组织名称，系统将自动根据客户的名和姓组合生成 |
| p_street | 字符串 | 可选 | 与账单相关的街道地址 |
| p_city | 字符串 | 可选 | 定义账单城市 |
| p_province | 字符串 | 可选 | 定义账单省份 |
| p_code | 字符串 | 可选 | 定义账单邮政编码 |
1// 导入所需库 2const fetch = require('node-fetch'); 3 4// 定义端点 URL 5const endpointUrl = 'https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients'; 6 7const headerParameters = { 8 'Authorization': 'Bearer {{ACCESS_TOKEN}}', 9 'Content-Type': 'application/json', 10}; 11 12// 定义请求体参数 13const bodyParameters = JSON.stringify({ 14 "client": { 15 "email": "<客户邮箱>", 16 "fname": "Educative", 17 "lname": "Inc.", 18 "organization": "Educative, Inc.", 19 "p_street": "---", 20 "p_city": "Bellevue", 21 "p_province": "Washington", 22 "p_code": "425" 23 } 24}); 25 26// 设置 API 调用选项 27const options = { 28 method: 'POST', 29 headers: headerParameters, 30 body: bodyParameters, 31}; 32 33// 执行 API 调用的函数 34async function createClient() { 35 try { 36 const response = await fetch(`${endpointUrl}`, options); 37 printResponse(response); 38 } catch (error) { 39 // 输出错误信息 40 printError(error); 41 } 42} 43 44// 调用函数执行 API 请求 45createClient();
响应字段
以下是 client 对象中一些重要字段的说明：
| 字段名称 | 类型 | 描述 |
|---|---|---|
| accounting_systemid | 字符串 | 账户的唯一标识符 |
| bus_phone | 字符串 | 客户的公司电话号码 |
| company_industry | 字符串 | 客户公司所属的行业类型 |
| currency_code | 字符串 | 客户偏好的货币代码，为三位字母代码 |
| 字符串 | 客户的邮箱地址 | |
| id | 整数 | 客户的唯一业务 ID |
| organization | 字符串 | 客户公司的名称 |
1// 导入所需库 2const fetch = require('node-fetch'); 3 4// 定义端点 URL 5const endpointUrl = 'https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients/{{CLIENT_ID}}'; 6 7const headerParameters = { 8 'Authorization': 'Bearer {{ACCESS_TOKEN}}', 9 'Content-Type': 'application/json', 10}; 11 12// 定义请求体参数 13const bodyParameters = JSON.stringify({ 14 "client": { 15 "fname": "Educative Inc.", 16 "lname": "" 17 } 18}); 19 20// 设置 API 调用选项 21const options = { 22 method: 'PUT', 23 headers: headerParameters, 24 body: bodyParameters, 25}; 26 27// 执行 API 调用的函数 28async function updateClient() { 29 try { 30 const response = await fetch(`${endpointUrl}`, options); 31 printResponse(response); 32 } catch (error) { 33 // 输出错误信息 34 printError(error); 35 } 36} 37 38// 调用函数执行 API 请求 39updateClient();
让我们来看一下上述代码中的高亮部分：
- 第 5 行：我们定义了
endpointUrl用于更新客户信息。这与创建客户时使用的 URL 类似，唯一的区别是 URL 末尾附加了客户的 ID。 - 第 13 至 18 行：我们定义了
bodyParameters对象，其中包裹了包含字段的client对象。 - 第 30 行：我们调用了
fetch函数。 - 第 39 行：我们调用了
updateClient函数。
响应字段
该端点返回的响应对象结构与创建新客户时的响应相同，各字段的详细信息请参见“请求参数与响应字段”一课。不过我们可以看到，已定义字段的值已被成功更新。
我们可以通过对创建客户所用的 URL 发送 HTTP GET 请求，获取 FreshBooks 账户中所有客户的信息。
请求参数
该端点不接受任何参数。以下是具体实现代码：
注意：请参考附录中的“重新生成访问令牌”一课来更新访问令牌。
1// 导入所需库 2const fetch = require('node-fetch'); 3 4// 定义端点 URL 5const endpointUrl = 'https://api.freshbooks.com/accounting/account/{{ACCOUNT_ID}}/users/clients'; 6 7const headerParameters = { 8 'Authorization': 'Bearer {{ACCESS_TOKEN}}', 9 'Content-Type': 'application/json', 10}; 11 12// 设置 API 调用选项 13const options = { 14 method: 'GET', 15 headers: headerParameters, 16}; 17 18// 执行 API 调用的函数 19async function listAllClients() { 20 try { 21 const response = await fetch(`${endpointUrl}`, options); 22 printResponse(response); 23 } catch (error) { 24 // 输出错误信息 25 printError(error); 26 } 27} 28 29// 调用函数执行 API 请求 30listAllClients();
让我们来看一下上述代码中的高亮部分：
- 第 5 行：我们定义了
endpointUrl。 - 第 21 行：我们调用了
fetch函数。 - 第 30 行：我们调用了
listAllClients函数。
响应字段
上述代码成功执行后，将返回我们 FreshBooks 账户中的所有客户信息。各字段的详细信息请参见“请求参数与响应字段”一课。