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}