square_api_client/api/team_api.rs
1//! Pull employee data into accounting and payroll systems with the Team API.
2//!
3//! The Team API allows applications to retrieve a roster of team members registered in the Square
4//! Point of Sale system, which can be useful in payroll and account contexts.
5//!
6//! The Team API is best used in conjunction with the Labor API, where you provide team member IDs
7//! to manage shifts, breaks, and wages.
8
9use crate::{
10 config::Configuration,
11 http::client::HttpClient,
12 models::{
13 errors::ApiError, BulkCreateTeamMembersRequest, BulkCreateTeamMembersResponse,
14 BulkUpdateTeamMembersRequest, BulkUpdateTeamMembersResponse, CreateTeamMemberRequest,
15 CreateTeamMemberResponse, RetrieveTeamMemberResponse, RetrieveWageSettingResponse,
16 SearchTeamMembersRequest, SearchTeamMembersResponse, UpdateTeamMemberRequest,
17 UpdateTeamMemberResponse, UpdateWageSettingRequest, UpdateWageSettingResponse,
18 },
19};
20
21const DEFAULT_URI: &str = "/team-members";
22
23pub struct TeamApi {
24 /// App config information
25 config: Configuration,
26 /// HTTP Client for requests to the Team API endpoints
27 client: HttpClient,
28}
29
30impl TeamApi {
31 /// Instantiates a new `TeamApi`
32 pub fn new(config: Configuration, client: HttpClient) -> Self {
33 Self { config, client }
34 }
35
36 /// Creates a single `TeamMember` object.
37 ///
38 /// The `TeamMember` object is returned on successful creates. You must provide the following
39 /// values in your request to this endpoint:
40 /// * `given_name`
41 /// * `family_name`
42 ///
43 /// Learn about [Troubleshooting the Team
44 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
45 pub async fn create_team_member(
46 &self,
47 body: &CreateTeamMemberRequest,
48 ) -> Result<CreateTeamMemberResponse, ApiError> {
49 let response = self.client.post(&self.url(), body).await?;
50
51 response.deserialize().await
52 }
53
54 /// Creates multiple `TeamMember` objects.
55 ///
56 /// The created `TeamMember` objects are returned on successful creates. This process is non-
57 /// transactional and processes as much of the request as possible. If one of the creates in the
58 /// request cannot be successfully processed, the request is not marked as failed, but the body
59 /// of the response contains explicit error information for the failed create.
60 ///
61 /// Learn about [Troubleshooting the Team
62 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
63 pub async fn bulk_create_team_members(
64 &self,
65 body: &BulkCreateTeamMembersRequest,
66 ) -> Result<BulkCreateTeamMembersResponse, ApiError> {
67 let url = format!("{}/bulk-create", self.url());
68 let response = self.client.post(&url, body).await?;
69
70 response.deserialize().await
71 }
72
73 /// Updates multiple `TeamMember` objects.
74 ///
75 /// The updated `TeamMember` objects are returned on successful updates. This process is non-
76 /// transactional and processes as much of the request as possible. If one of the updates in the
77 /// request cannot be successfully processed, the request is not marked as failed, but the body
78 /// of the response contains explicit error information for the failed update.
79 ///
80 /// Learn about [Troubleshooting the Team
81 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
82 pub async fn bulk_update_team_members(
83 &self,
84 body: &BulkUpdateTeamMembersRequest,
85 ) -> Result<BulkUpdateTeamMembersResponse, ApiError> {
86 let url = format!("{}/bulk-update", self.url());
87 let response = self.client.post(&url, body).await?;
88
89 response.deserialize().await
90 }
91
92 /// Returns a paginated list of `TeamMember` objects for a business.
93 ///
94 /// The list can be filtered by the following:
95 /// * location IDs
96 /// * `status`
97 pub async fn search_team_members(
98 &self,
99 body: &SearchTeamMembersRequest,
100 ) -> Result<SearchTeamMembersResponse, ApiError> {
101 let url = format!("{}/search", self.url());
102 let response = self.client.post(&url, body).await?;
103
104 response.deserialize().await
105 }
106
107 /// Retrieves a `TeamMember` object for the given `TeamMember.id`.
108 ///
109 /// Learn about [Troubleshooting the Team
110 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
111 pub async fn retrieve_team_member(
112 &self,
113 team_member_id: &str,
114 ) -> Result<RetrieveTeamMemberResponse, ApiError> {
115 let url = format!("{}/{}", self.url(), team_member_id);
116 let response = self.client.get(&url).await?;
117
118 response.deserialize().await
119 }
120
121 /// Updates a single `TeamMember` object.
122 ///
123 /// The `TeamMember` object is returned on successful updates.
124 ///
125 /// Learn about [Troubleshooting the Team
126 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
127 pub async fn update_team_member(
128 &self,
129 team_member_id: &str,
130 body: &UpdateTeamMemberRequest,
131 ) -> Result<UpdateTeamMemberResponse, ApiError> {
132 let url = format!("{}/{}", self.url(), team_member_id);
133 let response = self.client.put(&url, body).await?;
134
135 response.deserialize().await
136 }
137
138 /// Retrieves a `WageSetting` object for a team member specified by `TeamMember.id`.
139 ///
140 /// Learn about [Troubleshooting the Team
141 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
142 pub async fn retrieve_wage_setting(
143 &self,
144 team_member_id: &str,
145 ) -> Result<RetrieveWageSettingResponse, ApiError> {
146 let url = format!("{}/{}/wage-setting", self.url(), team_member_id);
147 let response = self.client.get(&url).await?;
148
149 response.deserialize().await
150 }
151
152 /// Creates or updates a `WageSetting` object.
153 ///
154 /// The object is created if a `WageSetting` with the specified `team_member_id` does not exist.
155 /// Otherwise, it fully replaces the `WageSetting` object for the team member. The `WageSetting`
156 /// is returned on a successful update.
157 ///
158 /// Learn about [Troubleshooting the Team
159 /// API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
160 pub async fn update_wage_setting(
161 &self,
162 team_member_id: &str,
163 body: &UpdateWageSettingRequest,
164 ) -> Result<UpdateWageSettingResponse, ApiError> {
165 let url = format!("{}/{}/wage-setting", self.url(), team_member_id);
166 let response = self.client.put(&url, body).await?;
167
168 response.deserialize().await
169 }
170
171 /// Constructs the basic entity URL including domain and entity path. Any additional path
172 /// elements (e.g. path parameters) will need to be appended to this URL.
173 fn url(&self) -> String {
174 format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
175 }
176}