squareup/api/
bookings_api.rs

1//! Create and manage bookings for Square sellers.
2//!
3//! The Bookings API allows you to create, retrieve, update, and cancel appointments online.
4//! When used with other Square APIs (such as the Locations API, Team API, Catalog API, and
5//! Customers API), the Bookings API lets you create online-booking applications for users to
6//! book services provided by Square sellers.
7
8use crate::models::{
9    BulkRetrieveBookingsRequest, BulkRetrieveBookingsResponse,
10    BulkRetrieveTeamMemberBookingProfilesRequest, BulkRetrieveTeamMemberBookingProfilesResponse,
11    CancelBookingRequest, CancelBookingResponse, CreateBookingRequest, CreateBookingResponse,
12    ListBookingsParameters, ListBookingsResponse, ListLocationBookingProfilesParameters,
13    ListLocationBookingProfilesResponse, ListTeamMemberBookingProfilesParameters,
14    ListTeamMemberBookingProfilesResponse, RetrieveBookingResponse,
15    RetrieveBusinessBookingProfileResponse, RetrieveLocationBookingProfileResponse,
16    RetrieveTeamMemberBookingProfileResponse, SearchAvailabilityRequest,
17    SearchAvailabilityResponse, UpdateBookingRequest, UpdateBookingResponse,
18};
19use crate::{
20    SquareClient, config::Configuration, http::client::HttpClient, models::errors::SquareApiError,
21};
22
23const DEFAULT_URI: &str = "/bookings";
24
25/// The Bookings API allows you to create, retrieve, update, and cancel appointments online.
26pub struct BookingsApi {
27    /// App config information
28    config: Configuration,
29    /// HTTP Client for requests to the Catalog API endpoints
30    http_client: HttpClient,
31}
32
33impl BookingsApi {
34    /// Instantiates a new `BookingsAPI`
35    pub fn new(square_client: SquareClient) -> BookingsApi {
36        BookingsApi {
37            config: square_client.config,
38            http_client: square_client.http_client,
39        }
40    }
41
42    /// Retrieve a collection of [Bookings].
43    ///
44    /// To call this endpoint with buyer-level permissions, set AppointmentsRead for
45    /// the OAuth scope. To call this endpoint with seller-level permissions, set
46    /// AppointmentsAllRead and AppointmentsRead for the OAuth scope.
47    pub async fn list_bookings(
48        &self,
49        params: &ListBookingsParameters,
50    ) -> Result<ListBookingsResponse, SquareApiError> {
51        let url = format!("{}{}", &self.url(), params.to_query_string());
52        let response = self.http_client.get(&url).await?;
53
54        response.deserialize().await
55    }
56
57    /// Creates a booking.
58    ///
59    /// The required input must include the following:
60    ///
61    /// Booking.location_id
62    /// Booking.start_at
63    /// Booking.team_member_id
64    /// Booking.AppointmentSegment.service_variation_id
65    /// Booking.AppointmentSegment.service_variation_version
66    ///
67    /// To call this endpoint with buyer-level permissions, set AppointmentsWrite for the OAuth
68    /// scope. To call this endpoint with seller-level permissions, set AppointmentsAllWrite
69    /// and AppointmentsWrite for the OAuth scope.
70    ///
71    /// For calls to this endpoint with seller-level permissions to succeed, the seller must have
72    /// subscribed to Appointments Plus or Appointments Premium.
73    pub async fn create_booking(
74        &self,
75        body: &CreateBookingRequest,
76    ) -> Result<CreateBookingResponse, SquareApiError> {
77        let url = &self.url();
78        let response = self.http_client.post(url, body).await?;
79
80        response.deserialize().await
81    }
82
83    /// Searches for availabilities for booking.
84    ///
85    /// To call this endpoint with buyer-level permissions, set AppointmentsRead for the OAuth
86    /// scope. To call this endpoint with seller-level permissions, set AppointmentsAllRead
87    /// and AppointmentsRead for the OAuth scope.
88    /// Permissions: AppointmentsRead
89    pub async fn search_availability(
90        &self,
91        body: &SearchAvailabilityRequest,
92    ) -> Result<SearchAvailabilityResponse, SquareApiError> {
93        let url = format!("{}/availability/search", &self.url());
94        let response = self.http_client.post(&url, body).await?;
95
96        response.deserialize().await
97    }
98
99    /// Bulk-Retrieves a list of bookings by booking IDs.
100    ///
101    /// To call this endpoint with buyer-level permissions, set AppointmentsRead for the OAuth
102    /// scope. To call this endpoint with seller-level permissions, set AppointmentsAllRead and
103    /// AppointmentsRead for the OAuth scope.
104    ///
105    /// Permissions:AppointmentsRead
106    pub async fn bulk_retrieve_bookings(
107        &self,
108        body: &BulkRetrieveBookingsRequest,
109    ) -> Result<BulkRetrieveBookingsResponse, SquareApiError> {
110        let url = format!("{}/bulk-retrieve", &self.url());
111        let response = self.http_client.post(&url, body).await?;
112
113        response.deserialize().await
114    }
115
116    /// Retrieves a seller's booking profile.
117    /// Permissions:AppointmentsBusinessSettingsRead
118    pub async fn retrieve_business_booking_profile(
119        &self,
120    ) -> Result<RetrieveBusinessBookingProfileResponse, SquareApiError> {
121        let url = format!("{}/business-booking-profile", &self.url());
122        let response = self.http_client.get(&url).await?;
123
124        response.deserialize().await
125    }
126
127    /// Lists location booking profiles of a seller.
128    /// Permissions:AppointmentsBusinessSettingsRead
129    pub async fn list_location_booking_profiles(
130        &self,
131        params: &ListLocationBookingProfilesParameters,
132    ) -> Result<ListLocationBookingProfilesResponse, SquareApiError> {
133        let url = format!(
134            "{}/location-booking-profiles{}",
135            &self.url(),
136            params.to_query_string()
137        );
138        let response = self.http_client.get(&url).await?;
139
140        response.deserialize().await
141    }
142
143    /// Retrieves a seller's location booking profile.
144    /// Permissions:AppointmentsBusinessSettingsRead
145    pub async fn retrieve_location_booking_profile(
146        &self,
147        location_id: impl AsRef<str>,
148    ) -> Result<RetrieveLocationBookingProfileResponse, SquareApiError> {
149        let url = format!(
150            "{}/location-booking-profiles/{}",
151            &self.url(),
152            location_id.as_ref()
153        );
154        let response = self.http_client.get(&url).await?;
155
156        response.deserialize().await
157    }
158
159    /// Lists booking profiles for team members.
160    /// Permissions:AppointmentsBusinessSettingsRead
161    pub async fn list_team_member_booking_profiles(
162        &self,
163        params: &ListTeamMemberBookingProfilesParameters,
164    ) -> Result<ListTeamMemberBookingProfilesResponse, SquareApiError> {
165        let url = format!(
166            "{}/team-member-booking-profiles{}",
167            &self.url(),
168            params.to_query_string()
169        );
170        let response = self.http_client.get(&url).await?;
171
172        response.deserialize().await
173    }
174
175    /// Retrieves one or more team members' booking profiles.
176    /// Permissions:AppointmentsBusinessSettingsRead
177    pub async fn bulk_retrieve_team_member_booking_profiles(
178        &self,
179        body: &BulkRetrieveTeamMemberBookingProfilesRequest,
180    ) -> Result<BulkRetrieveTeamMemberBookingProfilesResponse, SquareApiError> {
181        let url = format!("{}/team-member-booking-profiles/bulk-retrieve", &self.url());
182        let response = self.http_client.post(&url, body).await?;
183
184        response.deserialize().await
185    }
186
187    /// Retrieves a team member's booking profile.
188    /// Permissions:AppointmentsBusinessSettingsRead
189    pub async fn retrieve_team_member_booking_profile(
190        &self,
191        team_member_id: impl AsRef<str>,
192    ) -> Result<RetrieveTeamMemberBookingProfileResponse, SquareApiError> {
193        let url = format!(
194            "{}/team-member-booking-profiles/{}",
195            &self.url(),
196            team_member_id.as_ref()
197        );
198        let response = self.http_client.get(&url).await?;
199
200        response.deserialize().await
201    }
202
203    /// Retrieves a booking.
204    /// To call this endpoint with buyer-level permissions, set AppointmentsRead for the OAuth
205    /// scope. To call this endpoint with seller-level permissions, set AppointmentsAllRead and
206    /// AppointmentsRead for the OAuth scope.
207    ///
208    /// Permissions:AppointmentsRead
209    pub async fn retrieve_booking(
210        &self,
211        booking_id: impl AsRef<str>,
212    ) -> Result<RetrieveBookingResponse, SquareApiError> {
213        let url = format!("{}/{}", &self.url(), booking_id.as_ref());
214        let response = self.http_client.get(&url).await?;
215
216        response.deserialize().await
217    }
218
219    /// Updates a booking.
220    /// To call this endpoint with buyer-level permissions, set AppointmentsWrite for the
221    /// OAuth scope. To call this endpoint with seller-level permissions, set
222    /// AppointmentsAllWrite and AppointmentsWrite for the OAuth scope.
223    ///
224    /// For calls to this endpoint with seller-level permissions to succeed, the seller must have
225    /// subscribed to Appointments Plus or Appointments Premium.
226    ///
227    /// Permissions:AppointmentsWrite
228    pub async fn update_booking(
229        &self,
230        booking_id: impl AsRef<str>,
231        body: &UpdateBookingRequest,
232    ) -> Result<UpdateBookingResponse, SquareApiError> {
233        let url = format!("{}/{}", &self.url(), booking_id.as_ref());
234        let response = self.http_client.put(&url, body).await?;
235
236        response.deserialize().await
237    }
238
239    /// Cancels an existing booking.
240    /// To call this endpoint with buyer-level permissions, set AppointmentsWrite for the
241    /// OAuth scope. To call this endpoint with seller-level permissions, set
242    /// AppointmentsAllWrite and AppointmentsWrite for the OAuth scope.
243    ///
244    /// For calls to this endpoint with seller-level permissions to succeed, the seller must have
245    /// subscribed to Appointments Plus or Appointments Premium.
246    ///
247    /// Permissions:AppointmentsWrite
248    pub async fn cancel_booking(
249        &self,
250        booking_id: impl AsRef<str>,
251        body: &CancelBookingRequest,
252    ) -> Result<CancelBookingResponse, SquareApiError> {
253        let url = format!("{}/{}/cancel", &self.url(), booking_id.as_ref());
254        let response = self.http_client.post(&url, body).await?;
255
256        response.deserialize().await
257    }
258
259    /// Constructs the basic entity URL including domain and entity path. Any additional path
260    /// elements (e.g. path parameters) will need to be appended to this URL.
261    fn url(&self) -> String {
262        format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
263    }
264}
squareup/api/bookings_api.rs

squareup/api/
bookings_api.rs
