From df5fe254bc0bb2ad126218fc69749bdf7c628339 Mon Sep 17 00:00:00 2001 From: autobot Date: Wed, 18 Dec 2024 13:28:08 +0000 Subject: [PATCH] Release 2024-12-18 --- doc/api/payments.md | 10 +- doc/api/team.md | 205 ++++++++++++++++- doc/client.md | 6 +- .../bulk-create-team-members-request.md | 2 +- doc/models/bulk-create-vendors-response.md | 67 ++---- doc/models/bulk-retrieve-vendors-response.md | 43 ++-- .../bulk-update-team-members-request.md | 2 +- doc/models/bulk-update-vendors-response.md | 192 ++++++---------- doc/models/checkout-options-payment-type.md | 3 +- doc/models/create-job-request.md | 31 +++ doc/models/create-job-response.md | 40 ++++ doc/models/create-payment-request.md | 1 + doc/models/create-team-member-request.md | 22 ++ doc/models/create-team-member-response.md | 34 ++- doc/models/job-assignment.md | 9 +- doc/models/job.md | 34 +++ doc/models/list-jobs-request.md | 23 ++ doc/models/list-jobs-response.md | 52 +++++ doc/models/list-payments-request.md | 5 +- doc/models/payment-sort-field.md | 15 ++ doc/models/retrieve-job-response.md | 46 ++++ doc/models/retrieve-team-member-response.md | 34 ++- doc/models/retrieve-wage-setting-response.md | 5 +- doc/models/search-team-members-response.md | 108 ++++++++- doc/models/team-member.md | 7 +- doc/models/update-job-request.md | 29 +++ doc/models/update-job-response.md | 52 +++++ doc/models/update-team-member-request.md | 24 +- doc/models/update-team-member-response.md | 34 ++- doc/models/update-vendor-response.md | 23 +- doc/models/update-wage-setting-request.md | 10 +- doc/models/update-wage-setting-response.md | 10 +- doc/models/wage-setting.md | 22 +- pyproject.toml | 4 +- requirements.txt | 2 +- square/api/base_api.py | 2 +- square/api/payments_api.py | 27 ++- square/api/team_api.py | 214 +++++++++++++++++- square/client.py | 6 +- square/configuration.py | 2 +- 40 files changed, 1180 insertions(+), 277 deletions(-) create mode 100644 doc/models/create-job-request.md create mode 100644 doc/models/create-job-response.md create mode 100644 doc/models/job.md create mode 100644 doc/models/list-jobs-request.md create mode 100644 doc/models/list-jobs-response.md create mode 100644 doc/models/payment-sort-field.md create mode 100644 doc/models/retrieve-job-response.md create mode 100644 doc/models/update-job-request.md create mode 100644 doc/models/update-job-response.md diff --git a/doc/api/payments.md b/doc/api/payments.md index b3fa2732..817cd71d 100644 --- a/doc/api/payments.md +++ b/doc/api/payments.md @@ -41,7 +41,10 @@ def list_payments(self, limit=None, is_offline_payment=False, offline_begin_time=None, - offline_end_time=None) + offline_end_time=None, + updated_at_begin_time=None, + updated_at_end_time=None, + sort_field=None) ``` ## Parameters @@ -50,7 +53,7 @@ def list_payments(self, | --- | --- | --- | --- | | `begin_time` | `str` | Query, Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format.
The range is determined using the `created_at` field for each Payment.
Inclusive. Default: The current time minus one year. | | `end_time` | `str` | Query, Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `created_at` field for each Payment.

Default: The current time. | -| `sort_order` | `str` | Query, Optional | The order in which results are listed by `Payment.created_at`:

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | +| `sort_order` | `str` | Query, Optional | The order in which results are listed by `ListPaymentsRequest.sort_field`:

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | | `cursor` | `str` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.

For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `location_id` | `str` | Query, Optional | Limit results to the location supplied. By default, results are returned
for the default (main) location associated with the seller. | | `total` | `long\|int` | Query, Optional | The exact amount in the `total_money` for a payment. | @@ -60,6 +63,9 @@ def list_payments(self, | `is_offline_payment` | `bool` | Query, Optional | Whether the payment was taken offline or not.
**Default**: `False` | | `offline_begin_time` | `str` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | | `offline_end_time` | `str` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | +| `updated_at_begin_time` | `str` | Query, Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `updated_at` field for each Payment. | +| `updated_at_end_time` | `str` | Query, Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `updated_at` field for each Payment. | +| `sort_field` | [`str (Payment Sort Field)`](../../doc/models/payment-sort-field.md) | Query, Optional | The field used to sort results by. The default is `CREATED_AT`. | ## Response Type diff --git a/doc/api/team.md b/doc/api/team.md index 5bc40ca1..8b599661 100644 --- a/doc/api/team.md +++ b/doc/api/team.md @@ -13,6 +13,10 @@ team_api = client.team * [Create Team Member](../../doc/api/team.md#create-team-member) * [Bulk Create Team Members](../../doc/api/team.md#bulk-create-team-members) * [Bulk Update Team Members](../../doc/api/team.md#bulk-update-team-members) +* [List Jobs](../../doc/api/team.md#list-jobs) +* [Create Job](../../doc/api/team.md#create-job) +* [Retrieve Job](../../doc/api/team.md#retrieve-job) +* [Update Job](../../doc/api/team.md#update-job) * [Search Team Members](../../doc/api/team.md#search-team-members) * [Retrieve Team Member](../../doc/api/team.md#retrieve-team-member) * [Update Team Member](../../doc/api/team.md#update-team-member) @@ -63,6 +67,28 @@ body = { 'YSGH2WBKG94QZ', 'GA2Y9HSJ8KRYT' ] + }, + 'wage_setting': { + 'job_assignments': [ + { + 'pay_type': 'SALARY', + 'annual_rate': { + 'amount': 3000000, + 'currency': 'USD' + }, + 'weekly_hours': 40, + 'job_id': 'FjS8x95cqHiMenw4f1NAUH4P' + }, + { + 'pay_type': 'HOURLY', + 'hourly_rate': { + 'amount': 2000, + 'currency': 'USD' + }, + 'job_id': 'VDNpRv8da51NU8qZFC5zDWpF' + } + ], + 'is_overtime_exempt': True } } } @@ -215,13 +241,162 @@ elif result.is_error(): ``` +# List Jobs + +Lists jobs in a seller account. Results are sorted by title in ascending order. + +```python +def list_jobs(self, + cursor=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `str` | Query, Optional | The pagination cursor returned by the previous call to this endpoint. Provide this
cursor to retrieve the next page of results for your original request. For more information,
see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`List Jobs Response`](../../doc/models/list-jobs-response.md). + +## Example Usage + +```python +result = team_api.list_jobs() + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Create Job + +Creates a job in a seller account. A job defines a title and tip eligibility. Note that +compensation is defined in a [job assignment](../../doc/models/job-assignment.md) in a team member's wage setting. + +```python +def create_job(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Job Request`](../../doc/models/create-job-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Create Job Response`](../../doc/models/create-job-response.md). + +## Example Usage + +```python +body = { + 'job': { + 'title': 'Cashier', + 'is_tip_eligible': True + }, + 'idempotency_key': 'idempotency-key-0' +} + +result = team_api.create_job(body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Retrieve Job + +Retrieves a specified job. + +```python +def retrieve_job(self, + job_id) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `job_id` | `str` | Template, Required | The ID of the job to retrieve. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Retrieve Job Response`](../../doc/models/retrieve-job-response.md). + +## Example Usage + +```python +job_id = 'job_id2' + +result = team_api.retrieve_job(job_id) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Update Job + +Updates the title or tip eligibility of a job. Changes to the title propagate to all +`JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference the job ID. Changes to +tip eligibility propagate to all `TeamMemberWage` objects that reference the job ID. + +```python +def update_job(self, + job_id, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `job_id` | `str` | Template, Required | The ID of the job to update. | +| `body` | [`Update Job Request`](../../doc/models/update-job-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Update Job Response`](../../doc/models/update-job-response.md). + +## Example Usage + +```python +job_id = 'job_id2' + +body = { + 'job': { + 'title': 'Cashier 1', + 'is_tip_eligible': True + } +} + +result = team_api.update_job( + job_id, + body +) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Search Team Members Returns a paginated list of `TeamMember` objects for a business. -The list can be filtered by the following: - -- location IDs -- `status` +The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` status, or whether +the team member is the Square account owner. ```python def search_team_members(self, @@ -356,8 +531,11 @@ elif result.is_error(): # Retrieve Wage Setting Retrieves a `WageSetting` object for a team member specified -by `TeamMember.id`. -Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting). +by `TeamMember.id`. For more information, see +[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting). + +Square recommends using [RetrieveTeamMember](../../doc/api/team.md#retrieve-team-member) or [SearchTeamMembers](../../doc/api/team.md#search-team-members) +to get this information directly from the `TeamMember.wage_setting` field. ```python def retrieve_wage_setting(self, @@ -391,10 +569,13 @@ elif result.is_error(): # Update Wage Setting Creates or updates a `WageSetting` object. The object is created if a -`WageSetting` with the specified `team_member_id` does not exist. Otherwise, +`WageSetting` with the specified `team_member_id` doesn't exist. Otherwise, it fully replaces the `WageSetting` object for the team member. -The `WageSetting` is returned on a successful update. -Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting). +The `WageSetting` is returned on a successful update. For more information, see +[Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting). + +Square recommends using [CreateTeamMember](../../doc/api/team.md#create-team-member) or [UpdateTeamMember](../../doc/api/team.md#update-team-member) +to manage the `TeamMember.wage_setting` field directly. ```python def update_wage_setting(self, @@ -422,8 +603,8 @@ body = { 'wage_setting': { 'job_assignments': [ { - 'job_title': 'Manager', 'pay_type': 'SALARY', + 'job_title': 'Manager', 'annual_rate': { 'amount': 3000000, 'currency': 'USD' @@ -431,10 +612,10 @@ body = { 'weekly_hours': 40 }, { - 'job_title': 'Cashier', 'pay_type': 'HOURLY', + 'job_title': 'Cashier', 'hourly_rate': { - 'amount': 1200, + 'amount': 2000, 'currency': 'USD' } } diff --git a/doc/client.md b/doc/client.md index 0cee012c..fb073681 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `square_version` | `str` | Square Connect API versions
*Default*: `'2024-11-20'` | +| `square_version` | `str` | Square Connect API versions
*Default*: `'2024-12-18'` | | `custom_url` | `str` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests | @@ -24,7 +24,7 @@ The API client can be initialized as follows: ```python client = Client( - square_version='2024-11-20', + square_version='2024-12-18', bearer_auth_credentials=BearerAuthCredentials( access_token='AccessToken' ), @@ -53,7 +53,7 @@ from square.http.auth.o_auth_2 import BearerAuthCredentials from square.client import Client client = Client( - square_version='2024-11-20', + square_version='2024-12-18', bearer_auth_credentials=BearerAuthCredentials( access_token='AccessToken' ), diff --git a/doc/models/bulk-create-team-members-request.md b/doc/models/bulk-create-team-members-request.md index 4011a427..8a5ffd9d 100644 --- a/doc/models/bulk-create-team-members-request.md +++ b/doc/models/bulk-create-team-members-request.md @@ -11,7 +11,7 @@ Represents a bulk create request for `TeamMember` objects. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `team_members` | [`Dict Str Create Team Member Request`](../../doc/models/create-team-member-request.md) | Required | The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`. The maximum number of create objects is 25. | +| `team_members` | [`Dict Str Create Team Member Request`](../../doc/models/create-team-member-request.md) | Required | The data used to create the `TeamMember` objects. Each key is the `idempotency_key` that maps to the `CreateTeamMemberRequest`.
The maximum number of create objects is 25.

If you include a team member's `wage_setting`, you must provide `job_id` for each job assignment. To get job IDs,
call [ListJobs](api-endpoint:Team-ListJobs). | ## Example (as JSON) diff --git a/doc/models/bulk-create-vendors-response.md b/doc/models/bulk-create-vendors-response.md index 096fbcbf..f6842a7b 100644 --- a/doc/models/bulk-create-vendors-response.md +++ b/doc/models/bulk-create-vendors-response.md @@ -18,55 +18,26 @@ Represents an output from a call to [BulkCreateVendors](../../doc/api/vendors.md ```json { - "47bb76a8-c9fb-4f33-9df8-25ce02ca4505": { - "vendor": { - "contacts": [ - { - "email_address": "annie@annieshotsauce.com", - "id": "INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4", - "name": "Annie Thomas", - "phone_number": "1-212-555-4250" - } - ], - "created_at": "2022-03-16T10:21:54.859Z", - "id": "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A", - "name": "Annie’s Hot Sauce", - "status": "ACTIVE", - "updated_at": "2022-03-16T10:21:54.859Z", - "version": 1 - } - }, - "errors": [], - "vendors": { - "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe": { - "vendor": { - "account_number": "4025391", - "address": { - "address_line_1": "505 Electric Ave", - "address_line_2": "Suite 600", - "administrative_district_level_1": "NY", - "country": "US", - "locality": "New York", - "postal_code": "10003" - }, - "contacts": [ - { - "email_address": "joe@joesfreshseafood.com", - "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", - "name": "Joe Burrow", - "phone_number": "1-212-555-4250" - } - ], - "created_at": "2022-03-16T10:21:54.859Z", - "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", - "name": "Joe's Fresh Seafood", - "note": "a vendor", - "status": "ACTIVE", - "updated_at": "2022-03-16T10:21:54.859Z", - "version": 0 - } + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" } - }, + ], "responses": { "key0": { "errors": [ diff --git a/doc/models/bulk-retrieve-vendors-response.md b/doc/models/bulk-retrieve-vendors-response.md index a83ab586..096fd4c3 100644 --- a/doc/models/bulk-retrieve-vendors-response.md +++ b/doc/models/bulk-retrieve-vendors-response.md @@ -18,37 +18,20 @@ Represents an output from a call to [BulkRetrieveVendors](../../doc/api/vendors. ```json { - "errors": [], - "vendors": { - "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { - "vendor": { - "account_number": "4025391", - "address": { - "address_line_1": "505 Electric Ave", - "address_line_2": "Suite 600", - "administrative_district_level_1": "NY", - "country": "US", - "locality": "New York", - "postal_code": "10003" - }, - "contacts": [ - { - "email_address": "joe@joesfreshseafood.com", - "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", - "name": "Joe Burrow", - "phone_number": "1-212-555-4250" - } - ], - "created_at": "2022-03-16T10:21:54.859Z", - "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", - "name": "Joe's Fresh Seafood", - "note": "a vendor", - "status": "ACTIVE", - "updated_at": "2022-03-16T10:21:54.859Z", - "version": 1 - } + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" } - }, + ], "responses": { "key0": { "errors": [ diff --git a/doc/models/bulk-update-team-members-request.md b/doc/models/bulk-update-team-members-request.md index 435e655a..b5e594e2 100644 --- a/doc/models/bulk-update-team-members-request.md +++ b/doc/models/bulk-update-team-members-request.md @@ -11,7 +11,7 @@ Represents a bulk update request for `TeamMember` objects. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `team_members` | [`Dict Str Update Team Member Request`](../../doc/models/update-team-member-request.md) | Required | The data used to update the `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`. The maximum number of update objects is 25. | +| `team_members` | [`Dict Str Update Team Member Request`](../../doc/models/update-team-member-request.md) | Required | The data used to update the `TeamMember` objects. Each key is the `team_member_id` that maps to the `UpdateTeamMemberRequest`.
The maximum number of update objects is 25.

For each team member, include the fields to add, change, or clear. Fields can be cleared using a null value.
To update `wage_setting.job_assignments`, you must provide the complete list of job assignments. If needed,
call [ListJobs](api-endpoint:Team-ListJobs) to get the required `job_id` values. | ## Example (as JSON) diff --git a/doc/models/bulk-update-vendors-response.md b/doc/models/bulk-update-vendors-response.md index 7ba40048..111afa81 100644 --- a/doc/models/bulk-update-vendors-response.md +++ b/doc/models/bulk-update-vendors-response.md @@ -18,110 +18,35 @@ Represents an output from a call to [BulkUpdateVendors](../../doc/api/vendors.md ```json { - "vendors": { - "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A": { - "address": { - "address_line_1": "202 Mill St", - "administrative_district_level_1": "NJ", - "country": "US", - "locality": "Moorestown", - "postal_code": "08057" - }, - "contacts": [ - { - "email_address": "annie@annieshotsauce.com", - "id": "INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4", - "name": "Annie Thomas", - "ordinal": 0, - "phone_number": "1-212-555-4250" - } - ], - "created_at": "2022-03-16T10:21:54.859Z", - "id": "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A", - "name": "Annie’s Hot Sauce", - "status": "ACTIVE", - "updated_at": "2022-03-16T20:21:54.859Z", - "version": 11 - }, - "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { - "account_number": "4025391", - "address": { - "address_line_1": "505 Electric Ave", - "address_line_2": "Suite 600", - "administrative_district_level_1": "NY", - "country": "US", - "locality": "New York", - "postal_code": "10003" - }, - "contacts": [ - { - "email_address": "joe@joesfreshseafood.com", - "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", - "name": "Joe Burrow", - "ordinal": 0, - "phone_number": "1-212-555-4250" - } - ], - "created_at": "2022-03-16T10:10:54.859Z", - "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", - "name": "Joe's Fresh Seafood", - "note": "favorite vendor", - "status": "ACTIVE", - "updated_at": "2022-03-16T20:21:54.859Z", - "version": 31 - } - }, - "errors": [ - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_EXPIRATION", - "detail": "detail6", - "field": "field4" - }, - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_EXPIRATION", - "detail": "detail6", - "field": "field4" - } - ], "responses": { - "key0": { - "errors": [ - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_EXPIRATION", - "detail": "detail6", - "field": "field4" - }, - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_EXPIRATION", - "detail": "detail6", - "field": "field4" - }, - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_EXPIRATION", - "detail": "detail6", - "field": "field4" - } - ], + "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A": { "vendor": { - "id": "id6", - "created_at": "created_at4", - "updated_at": "updated_at2", - "name": "name6", "address": { - "address_line_1": "address_line_16", + "address_line_1": "202 Mill St", + "administrative_district_level_1": "NJ", + "country": "US", + "locality": "Moorestown", + "postal_code": "08057", "address_line_2": "address_line_26", "address_line_3": "address_line_32", - "locality": "locality6", "sublocality": "sublocality6" - } - } - }, - "key1": { + }, + "contacts": [ + { + "email_address": "annie@annieshotsauce.com", + "id": "INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4", + "name": "Annie Thomas", + "ordinal": 0, + "phone_number": "1-212-555-4250" + } + ], + "created_at": "2022-03-16T10:21:54.859Z", + "id": "INV_V_FMCYHBWT1TPL8MFH52PBMEN92A", + "name": "Annie’s Hot Sauce", + "status": "ACTIVE", + "updated_at": "2022-03-16T20:21:54.859Z", + "version": 11 + }, "errors": [ { "category": "MERCHANT_SUBSCRIPTION_ERROR", @@ -141,22 +66,38 @@ Represents an output from a call to [BulkUpdateVendors](../../doc/api/vendors.md "detail": "detail6", "field": "field4" } - ], + ] + }, + "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": { "vendor": { - "id": "id6", - "created_at": "created_at4", - "updated_at": "updated_at2", - "name": "name6", + "account_number": "4025391", "address": { - "address_line_1": "address_line_16", - "address_line_2": "address_line_26", + "address_line_1": "505 Electric Ave", + "address_line_2": "Suite 600", + "administrative_district_level_1": "NY", + "country": "US", + "locality": "New York", + "postal_code": "10003", "address_line_3": "address_line_32", - "locality": "locality6", "sublocality": "sublocality6" - } - } - }, - "key2": { + }, + "contacts": [ + { + "email_address": "joe@joesfreshseafood.com", + "id": "INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A", + "name": "Joe Burrow", + "ordinal": 0, + "phone_number": "1-212-555-4250" + } + ], + "created_at": "2022-03-16T10:10:54.859Z", + "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4", + "name": "Joe's Fresh Seafood", + "note": "favorite vendor", + "status": "ACTIVE", + "updated_at": "2022-03-16T20:21:54.859Z", + "version": 31 + }, "errors": [ { "category": "MERCHANT_SUBSCRIPTION_ERROR", @@ -176,22 +117,23 @@ Represents an output from a call to [BulkUpdateVendors](../../doc/api/vendors.md "detail": "detail6", "field": "field4" } - ], - "vendor": { - "id": "id6", - "created_at": "created_at4", - "updated_at": "updated_at2", - "name": "name6", - "address": { - "address_line_1": "address_line_16", - "address_line_2": "address_line_26", - "address_line_3": "address_line_32", - "locality": "locality6", - "sublocality": "sublocality6" - } - } + ] + } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" } - } + ] } ``` diff --git a/doc/models/checkout-options-payment-type.md b/doc/models/checkout-options-payment-type.md index a2de825a..a19e00a9 100644 --- a/doc/models/checkout-options-payment-type.md +++ b/doc/models/checkout-options-payment-type.md @@ -15,5 +15,6 @@ | `FELICA_QUICPAY` | Launches the QUICPay checkout screen for the buyer to complete. | | `FELICA_TRANSPORTATION_GROUP` | Launches the Transportation Group checkout screen for the buyer to complete. | | `FELICA_ALL` | Launches a checkout screen for the buyer on the Square Terminal that
allows them to select a specific FeliCa brand or select the check balance screen. | -| `PAYPAY` | Launches the PayPay checkout screen for the buyer to complete. | +| `PAYPAY` | Replaced by `QR_CODE`. | +| `QR_CODE` | Launches Square's QR Code checkout screen for the buyer to complete.
Displays a single code that supports all digital wallets connected to the target
Seller location (e.g. PayPay) | diff --git a/doc/models/create-job-request.md b/doc/models/create-job-request.md new file mode 100644 index 00000000..719bafae --- /dev/null +++ b/doc/models/create-job-request.md @@ -0,0 +1,31 @@ + +# Create Job Request + +Represents a [CreateJob](../../doc/api/team.md#create-job) request. + +## Structure + +`Create Job Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `job` | [`Job`](../../doc/models/job.md) | Required | Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the
job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md)
in a team member's wage setting. | +| `idempotency_key` | `str` | Required | A unique identifier for the `CreateJob` request. Keys can be any valid string,
but must be unique for each request. For more information, see
[Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `45` | + +## Example (as JSON) + +```json +{ + "idempotency_key": "idempotency-key-0", + "job": { + "is_tip_eligible": true, + "title": "Cashier", + "id": "id6", + "created_at": "created_at4", + "updated_at": "updated_at8" + } +} +``` + diff --git a/doc/models/create-job-response.md b/doc/models/create-job-response.md new file mode 100644 index 00000000..96251265 --- /dev/null +++ b/doc/models/create-job-response.md @@ -0,0 +1,40 @@ + +# Create Job Response + +Represents a [CreateJob](../../doc/api/team.md#create-job) response. Either `job` or `errors` +is present in the response. + +## Structure + +`Create Job Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `job` | [`Job`](../../doc/models/job.md) | Optional | Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the
job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md)
in a team member's wage setting. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "job": { + "created_at": "2021-06-11T22:55:45Z", + "id": "1yJlHapkseYnNPETIU1B", + "is_tip_eligible": true, + "title": "Cashier", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index d71000a1..ea131165 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -28,6 +28,7 @@ Describes a request to create a payment using | `verification_token` | `str` | Optional | An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity.

For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview). | | `accept_partial_authorization` | `bool` | Optional | If set to `true` and charging a Square Gift Card, a payment might be returned with
`amount_money` equal to less than what was requested. For example, a request for $20 when charging
a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
payment. This field cannot be `true` when `autocomplete = true`.

For more information, see
[Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | | `buyer_email_address` | `str` | Optional | The buyer's email address.
**Constraints**: *Maximum Length*: `255` | +| `buyer_phone_number` | `str` | Optional | The buyer's phone number.
Must follow the following format:

1. A leading + symbol (followed by a country code)
2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`.
Alphabetical characters aren't allowed.
3. The phone number must contain between 9 and 16 digits. | | `billing_address` | [`Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | | `shipping_address` | [`Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | | `note` | `str` | Optional | An optional note to be entered by the developer when creating a payment.
**Constraints**: *Maximum Length*: `500` | diff --git a/doc/models/create-team-member-request.md b/doc/models/create-team-member-request.md index c33a5c16..19f9ec97 100644 --- a/doc/models/create-team-member-request.md +++ b/doc/models/create-team-member-request.md @@ -33,6 +33,28 @@ Represents a create request for a `TeamMember` object. "phone_number": "+14159283333", "reference_id": "reference_id_1", "status": "ACTIVE", + "wage_setting": { + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "pay_type": "HOURLY" + } + ] + }, "id": "id6", "is_owner": false } diff --git a/doc/models/create-team-member-response.md b/doc/models/create-team-member-response.md index 36d6d8f9..ea0469b8 100644 --- a/doc/models/create-team-member-response.md +++ b/doc/models/create-team-member-response.md @@ -35,7 +35,39 @@ Represents a response from a create request containing the created `TeamMember` "phone_number": "+14159283333", "reference_id": "reference_id_1", "status": "ACTIVE", - "updated_at": "2021-06-11T22:55:45Z" + "updated_at": "2021-06-11T22:55:45Z", + "wage_setting": { + "created_at": "2021-06-11T22:55:45Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "hourly_rate": { + "amount": 1443, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "job_title": "Manager", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "1yJlHapkseYnNPETIU1B", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + } }, "errors": [ { diff --git a/doc/models/job-assignment.md b/doc/models/job-assignment.md index 01c536dd..b627d070 100644 --- a/doc/models/job-assignment.md +++ b/doc/models/job-assignment.md @@ -1,7 +1,8 @@ # Job Assignment -An object describing a job that a team member is assigned to. +Represents a job assigned to a [team member](../../doc/models/team-member.md), including the compensation the team +member earns for the job. Job assignments are listed in the team member's [wage setting](../../doc/models/wage-setting.md). ## Structure @@ -11,11 +12,12 @@ An object describing a job that a team member is assigned to. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `job_title` | `str` | Required | The title of the job.
**Constraints**: *Minimum Length*: `1` | +| `job_title` | `str` | Optional | The title of the job. | | `pay_type` | [`str (Job Assignment Pay Type)`](../../doc/models/job-assignment-pay-type.md) | Required | Enumerates the possible pay types that a job can be assigned. | | `hourly_rate` | [`Money`](../../doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | | `annual_rate` | [`Money`](../../doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | | `weekly_hours` | `int` | Optional | The planned hours per week for the job. Set if the job `PayType` is `SALARY`. | +| `job_id` | `str` | Optional | The ID of the [job](../../doc/models/job.md). | ## Example (as JSON) @@ -31,7 +33,8 @@ An object describing a job that a team member is assigned to. "amount": 232, "currency": "NIO" }, - "weekly_hours": 120 + "weekly_hours": 120, + "job_id": "job_id8" } ``` diff --git a/doc/models/job.md b/doc/models/job.md new file mode 100644 index 00000000..4ab7f37a --- /dev/null +++ b/doc/models/job.md @@ -0,0 +1,34 @@ + +# Job + +Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the +job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md) +in a team member's wage setting. + +## Structure + +`Job` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `str` | Optional | **Read only** The unique Square-assigned ID of the job. If you need a job ID for an API request,
call [ListJobs](api-endpoint:Team-ListJobs) or use the ID returned when you created the job.
You can also get job IDs from a team member's wage setting. | +| `title` | `str` | Optional | The title of the job.
**Constraints**: *Maximum Length*: `150` | +| `is_tip_eligible` | `bool` | Optional | Indicates whether team members can earn tips for the job. | +| `created_at` | `str` | Optional | The timestamp when the job was created, in RFC 3339 format. | +| `updated_at` | `str` | Optional | The timestamp when the job was last updated, in RFC 3339 format. | +| `version` | `int` | Optional | **Read only** The current version of the job. Include this field in `UpdateJob` requests to enable
[optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)
control and avoid overwrites from concurrent requests. Requests fail if the provided version doesn't
match the server version at the time of the request. | + +## Example (as JSON) + +```json +{ + "id": "id6", + "title": "title2", + "is_tip_eligible": false, + "created_at": "created_at4", + "updated_at": "updated_at2" +} +``` + diff --git a/doc/models/list-jobs-request.md b/doc/models/list-jobs-request.md new file mode 100644 index 00000000..62e45688 --- /dev/null +++ b/doc/models/list-jobs-request.md @@ -0,0 +1,23 @@ + +# List Jobs Request + +Represents a [ListJobs](../../doc/api/team.md#list-jobs) request. + +## Structure + +`List Jobs Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `cursor` | `str` | Optional | The pagination cursor returned by the previous call to this endpoint. Provide this
cursor to retrieve the next page of results for your original request. For more information,
see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | + +## Example (as JSON) + +```json +{ + "cursor": "cursor4" +} +``` + diff --git a/doc/models/list-jobs-response.md b/doc/models/list-jobs-response.md new file mode 100644 index 00000000..78c18dd3 --- /dev/null +++ b/doc/models/list-jobs-response.md @@ -0,0 +1,52 @@ + +# List Jobs Response + +Represents a [ListJobs](../../doc/api/team.md#list-jobs) response. Either `jobs` or `errors` +is present in the response. If additional results are available, the `cursor` field is also present. + +## Structure + +`List Jobs Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `jobs` | [`List Job`](../../doc/models/job.md) | Optional | The retrieved jobs. A single paged response contains up to 100 jobs. | +| `cursor` | `str` | Optional | An opaque cursor used to retrieve the next page of results. This field is present only
if the request succeeded and additional results are available. For more information, see
[Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "jobs": [ + { + "created_at": "2021-06-11T22:55:45Z", + "id": "VDNpRv8da51NU8qZFC5zDWpF", + "is_tip_eligible": true, + "title": "Cashier", + "updated_at": "2021-06-11T22:55:45Z", + "version": 2 + }, + { + "created_at": "2021-06-11T22:55:45Z", + "id": "FjS8x95cqHiMenw4f1NAUH4P", + "is_tip_eligible": false, + "title": "Chef", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + } + ], + "cursor": "cursor6", + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/list-payments-request.md b/doc/models/list-payments-request.md index fad1019c..a98c3e3c 100644 --- a/doc/models/list-payments-request.md +++ b/doc/models/list-payments-request.md @@ -16,7 +16,7 @@ The maximum results per page is 100. | --- | --- | --- | --- | | `begin_time` | `str` | Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format.
The range is determined using the `created_at` field for each Payment.
Inclusive. Default: The current time minus one year. | | `end_time` | `str` | Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `created_at` field for each Payment.

Default: The current time. | -| `sort_order` | `str` | Optional | The order in which results are listed by `Payment.created_at`:

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | +| `sort_order` | `str` | Optional | The order in which results are listed by `ListPaymentsRequest.sort_field`:

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | | `cursor` | `str` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.

For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `location_id` | `str` | Optional | Limit results to the location supplied. By default, results are returned
for the default (main) location associated with the seller. | | `total` | `long\|int` | Optional | The exact amount in the `total_money` for a payment. | @@ -26,6 +26,9 @@ The maximum results per page is 100. | `is_offline_payment` | `bool` | Optional | Whether the payment was taken offline or not. | | `offline_begin_time` | `str` | Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | | `offline_end_time` | `str` | Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | +| `updated_at_begin_time` | `str` | Optional | Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `updated_at` field for each Payment. | +| `updated_at_end_time` | `str` | Optional | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The
range is determined using the `updated_at` field for each Payment. | +| `sort_field` | [`str (Payment Sort Field)`](../../doc/models/payment-sort-field.md) | Optional | - | ## Example (as JSON) diff --git a/doc/models/payment-sort-field.md b/doc/models/payment-sort-field.md new file mode 100644 index 00000000..f15d03e5 --- /dev/null +++ b/doc/models/payment-sort-field.md @@ -0,0 +1,15 @@ + +# Payment Sort Field + +## Enumeration + +`Payment Sort Field` + +## Fields + +| Name | +| --- | +| `CREATED_AT` | +| `OFFLINE_CREATED_AT` | +| `UPDATED_AT` | + diff --git a/doc/models/retrieve-job-response.md b/doc/models/retrieve-job-response.md new file mode 100644 index 00000000..44c6e136 --- /dev/null +++ b/doc/models/retrieve-job-response.md @@ -0,0 +1,46 @@ + +# Retrieve Job Response + +Represents a [RetrieveJob](../../doc/api/team.md#retrieve-job) response. Either `job` or `errors` +is present in the response. + +## Structure + +`Retrieve Job Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `job` | [`Job`](../../doc/models/job.md) | Optional | Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the
job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md)
in a team member's wage setting. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "job": { + "created_at": "2021-06-11T22:55:45Z", + "id": "1yJlHapkseYnNPETIU1B", + "is_tip_eligible": true, + "title": "Cashier 1", + "updated_at": "2021-06-11T22:55:45Z", + "version": 2 + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/retrieve-team-member-response.md b/doc/models/retrieve-team-member-response.md index a192127e..d112bf43 100644 --- a/doc/models/retrieve-team-member-response.md +++ b/doc/models/retrieve-team-member-response.md @@ -35,7 +35,39 @@ Represents a response from a retrieve request containing a `TeamMember` object o "phone_number": "+14159283333", "reference_id": "reference_id_1", "status": "ACTIVE", - "updated_at": "2021-06-15T17:38:05Z" + "updated_at": "2021-06-15T17:38:05Z", + "wage_setting": { + "created_at": "2021-06-11T22:55:45Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "hourly_rate": { + "amount": 1443, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "job_title": "Manager", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "1yJlHapkseYnNPETIU1B", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + } }, "errors": [ { diff --git a/doc/models/retrieve-wage-setting-response.md b/doc/models/retrieve-wage-setting-response.md index 70f783da..6493c4cc 100644 --- a/doc/models/retrieve-wage-setting-response.md +++ b/doc/models/retrieve-wage-setting-response.md @@ -11,7 +11,7 @@ Represents a response from a retrieve request containing the specified `WageSett | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Optional | An object representing a team member's wage information. | +| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Optional | Represents information about the overtime exemption status, job assignments, and compensation
for a [team member](../../doc/models/team-member.md). | | `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | ## Example (as JSON) @@ -33,7 +33,8 @@ Represents a response from a retrieve request containing the specified `WageSett }, "job_title": "Manager", "pay_type": "SALARY", - "weekly_hours": 40 + "weekly_hours": 40, + "job_id": "job_id2" } ], "team_member_id": "1yJlHapkseYnNPETIU1B", diff --git a/doc/models/search-team-members-response.md b/doc/models/search-team-members-response.md index f87060de..fc9164fc 100644 --- a/doc/models/search-team-members-response.md +++ b/doc/models/search-team-members-response.md @@ -33,7 +33,39 @@ Represents a response from a search request containing a filtered list of `TeamM "is_owner": false, "reference_id": "12345678", "status": "ACTIVE", - "updated_at": "2020-04-28T21:49:28Z" + "updated_at": "2020-04-28T21:49:28Z", + "wage_setting": { + "created_at": "2021-06-11T22:55:45Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "hourly_rate": { + "amount": 1443, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "job_title": "Manager", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "-3oZQKPKVk6gUXU_V5Qa", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + } }, { "assigned_locations": { @@ -47,7 +79,25 @@ Represents a response from a search request containing a filtered list of `TeamM "phone_number": "+14155552671", "reference_id": "abcded", "status": "ACTIVE", - "updated_at": "2020-06-09T17:38:05Z" + "updated_at": "2020-06-09T17:38:05Z", + "wage_setting": { + "created_at": "2020-03-24T18:14:01Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "hourly_rate": { + "amount": 2400, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "1AVJj0DjkzbmbJw5r4KK", + "updated_at": "2020-06-09T17:38:05Z", + "version": 2 + } }, { "assigned_locations": { @@ -60,6 +110,24 @@ Represents a response from a search request containing a filtered list of `TeamM "is_owner": false, "status": "ACTIVE", "updated_at": "2020-03-24T01:11:25Z", + "wage_setting": { + "created_at": "2020-03-24T01:09:25Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "hourly_rate": { + "amount": 2400, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "2JCmiJol_KKFs9z2Evim", + "updated_at": "2020-03-24T01:09:25Z", + "version": 1 + }, "reference_id": "reference_id4" }, { @@ -100,6 +168,24 @@ Represents a response from a search request containing a filtered list of `TeamM "phone_number": "+14155552671", "status": "ACTIVE", "updated_at": "2020-03-24T18:18:03Z", + "wage_setting": { + "created_at": "2020-03-24T18:14:03Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "5MRPTTp8MMBLVSmzrGha", + "updated_at": "2020-03-24T18:14:03Z", + "version": 1 + }, "reference_id": "reference_id4" }, { @@ -158,6 +244,24 @@ Represents a response from a search request containing a filtered list of `TeamM "phone_number": "+14155552671", "status": "ACTIVE", "updated_at": "2020-03-24T18:18:00Z", + "wage_setting": { + "created_at": "2020-03-24T18:14:00Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "hourly_rate": { + "amount": 2000, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "9UglUjOXQ13-hMFypCft", + "updated_at": "2020-03-24T18:14:03Z", + "version": 1 + }, "reference_id": "reference_id4" } ], diff --git a/doc/models/team-member.md b/doc/models/team-member.md index 1fd42e1b..163cbe4d 100644 --- a/doc/models/team-member.md +++ b/doc/models/team-member.md @@ -17,11 +17,12 @@ A record representing an individual team member for a business. | `status` | [`str (Team Member Status)`](../../doc/models/team-member-status.md) | Optional | Enumerates the possible statuses the team member can have within a business. | | `given_name` | `str` | Optional | The given name (that is, the first name) associated with the team member. | | `family_name` | `str` | Optional | The family name (that is, the last name) associated with the team member. | -| `email_address` | `str` | Optional | The email address associated with the team member. | +| `email_address` | `str` | Optional | The email address associated with the team member. After accepting the invitation
from Square, only the team member can change this value. | | `phone_number` | `str` | Optional | The team member's phone number, in E.164 format. For example:
+14155552671 - the country code is 1 for US
+551155256325 - the country code is 55 for BR | -| `created_at` | `str` | Optional | The timestamp, in RFC 3339 format, describing when the team member was created.
For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z". | -| `updated_at` | `str` | Optional | The timestamp, in RFC 3339 format, describing when the team member was last updated.
For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z". | +| `created_at` | `str` | Optional | The timestamp when the team member was created, in RFC 3339 format. | +| `updated_at` | `str` | Optional | The timestamp when the team member was last updated, in RFC 3339 format. | | `assigned_locations` | [`Team Member Assigned Locations`](../../doc/models/team-member-assigned-locations.md) | Optional | An object that represents a team member's assignment to locations. | +| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Optional | Represents information about the overtime exemption status, job assignments, and compensation
for a [team member](../../doc/models/team-member.md). | ## Example (as JSON) diff --git a/doc/models/update-job-request.md b/doc/models/update-job-request.md new file mode 100644 index 00000000..f95ef73e --- /dev/null +++ b/doc/models/update-job-request.md @@ -0,0 +1,29 @@ + +# Update Job Request + +Represents an [UpdateJob](../../doc/api/team.md#update-job) request. + +## Structure + +`Update Job Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `job` | [`Job`](../../doc/models/job.md) | Required | Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the
job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md)
in a team member's wage setting. | + +## Example (as JSON) + +```json +{ + "job": { + "is_tip_eligible": true, + "title": "Cashier 1", + "id": "id6", + "created_at": "created_at4", + "updated_at": "updated_at8" + } +} +``` + diff --git a/doc/models/update-job-response.md b/doc/models/update-job-response.md new file mode 100644 index 00000000..acb8f2d1 --- /dev/null +++ b/doc/models/update-job-response.md @@ -0,0 +1,52 @@ + +# Update Job Response + +Represents an [UpdateJob](../../doc/api/team.md#update-job) response. Either `job` or `errors` +is present in the response. + +## Structure + +`Update Job Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `job` | [`Job`](../../doc/models/job.md) | Optional | Represents a job that can be assigned to [team members](../../doc/models/team-member.md). This object defines the
job's title and tip eligibility. Compensation is defined in a [job assignment](../../doc/models/job-assignment.md)
in a team member's wage setting. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "job": { + "created_at": "2021-06-11T22:55:45Z", + "id": "1yJlHapkseYnNPETIU1B", + "is_tip_eligible": true, + "title": "Cashier 1", + "updated_at": "2021-06-13T12:55:45Z", + "version": 2 + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/update-team-member-request.md b/doc/models/update-team-member-request.md index f379ce09..2147b587 100644 --- a/doc/models/update-team-member-request.md +++ b/doc/models/update-team-member-request.md @@ -23,7 +23,29 @@ Represents an update request for a `TeamMember` object. "location_ids": [ "YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT" - ] + ], + "wage_setting": { + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 1200, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "pay_type": "HOURLY" + } + ] + } }, "email_address": "joe_doe@gmail.com", "family_name": "Doe", diff --git a/doc/models/update-team-member-response.md b/doc/models/update-team-member-response.md index c79a4045..0af3d72d 100644 --- a/doc/models/update-team-member-response.md +++ b/doc/models/update-team-member-response.md @@ -35,7 +35,39 @@ Represents a response from an update request containing the updated `TeamMember` "phone_number": "+14159283333", "reference_id": "reference_id_1", "status": "ACTIVE", - "updated_at": "2021-06-15T17:38:05Z" + "updated_at": "2021-06-15T17:38:05Z", + "wage_setting": { + "created_at": "2021-06-11T22:55:45Z", + "is_overtime_exempt": true, + "job_assignments": [ + { + "annual_rate": { + "amount": 3000000, + "currency": "USD" + }, + "hourly_rate": { + "amount": 1443, + "currency": "USD" + }, + "job_id": "FjS8x95cqHiMenw4f1NAUH4P", + "job_title": "Manager", + "pay_type": "SALARY", + "weekly_hours": 40 + }, + { + "hourly_rate": { + "amount": 1200, + "currency": "USD" + }, + "job_id": "VDNpRv8da51NU8qZFC5zDWpF", + "job_title": "Cashier", + "pay_type": "HOURLY" + } + ], + "team_member_id": "1yJlHapkseYnNPETIU1B", + "updated_at": "2021-06-11T22:55:45Z", + "version": 1 + } }, "errors": [ { diff --git a/doc/models/update-vendor-response.md b/doc/models/update-vendor-response.md index 1f8f0ba7..4ab33e2a 100644 --- a/doc/models/update-vendor-response.md +++ b/doc/models/update-vendor-response.md @@ -18,7 +18,6 @@ Represents an output from a call to [UpdateVendor](../../doc/api/vendors.md#upda ```json { - "errors": [], "vendor": { "account_number": "4025391", "address": { @@ -46,7 +45,27 @@ Represents an output from a call to [UpdateVendor](../../doc/api/vendors.md#upda "status": "ACTIVE", "updated_at": "2022-03-16T20:21:54.859Z", "version": 2 - } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "INVALID_EXPIRATION", + "detail": "detail6", + "field": "field4" + } + ] } ``` diff --git a/doc/models/update-wage-setting-request.md b/doc/models/update-wage-setting-request.md index 14237ef9..7b12f3dd 100644 --- a/doc/models/update-wage-setting-request.md +++ b/doc/models/update-wage-setting-request.md @@ -11,7 +11,7 @@ Represents an update request for the `WageSetting` object describing a `TeamMemb | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Required | An object representing a team member's wage information. | +| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Required | Represents information about the overtime exemption status, job assignments, and compensation
for a [team member](../../doc/models/team-member.md). | ## Example (as JSON) @@ -31,11 +31,12 @@ Represents an update request for the `WageSetting` object describing a `TeamMemb "hourly_rate": { "amount": 172, "currency": "LAK" - } + }, + "job_id": "job_id2" }, { "hourly_rate": { - "amount": 1200, + "amount": 2000, "currency": "USD" }, "job_title": "Cashier", @@ -44,7 +45,8 @@ Represents an update request for the `WageSetting` object describing a `TeamMemb "amount": 232, "currency": "NIO" }, - "weekly_hours": 98 + "weekly_hours": 98, + "job_id": "job_id2" } ], "team_member_id": "team_member_id8", diff --git a/doc/models/update-wage-setting-response.md b/doc/models/update-wage-setting-response.md index 89af6744..99e4bd98 100644 --- a/doc/models/update-wage-setting-response.md +++ b/doc/models/update-wage-setting-response.md @@ -12,7 +12,7 @@ or error messages. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Optional | An object representing a team member's wage information. | +| `wage_setting` | [`Wage Setting`](../../doc/models/wage-setting.md) | Optional | Represents information about the overtime exemption status, job assignments, and compensation
for a [team member](../../doc/models/team-member.md). | | `errors` | [`List Error`](../../doc/models/error.md) | Optional | The errors that occurred during the request. | ## Example (as JSON) @@ -34,11 +34,12 @@ or error messages. }, "job_title": "Manager", "pay_type": "SALARY", - "weekly_hours": 40 + "weekly_hours": 40, + "job_id": "job_id2" }, { "hourly_rate": { - "amount": 1200, + "amount": 2000, "currency": "USD" }, "job_title": "Cashier", @@ -47,7 +48,8 @@ or error messages. "amount": 232, "currency": "NIO" }, - "weekly_hours": 98 + "weekly_hours": 98, + "job_id": "job_id2" } ], "team_member_id": "-3oZQKPKVk6gUXU_V5Qa", diff --git a/doc/models/wage-setting.md b/doc/models/wage-setting.md index 910f14b7..9767a521 100644 --- a/doc/models/wage-setting.md +++ b/doc/models/wage-setting.md @@ -1,7 +1,8 @@ # Wage Setting -An object representing a team member's wage information. +Represents information about the overtime exemption status, job assignments, and compensation +for a [team member](../../doc/models/team-member.md). ## Structure @@ -11,12 +12,12 @@ An object representing a team member's wage information. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `team_member_id` | `str` | Optional | The unique ID of the `TeamMember` whom this wage setting describes. | -| `job_assignments` | [`List Job Assignment`](../../doc/models/job-assignment.md) | Optional | Required. The ordered list of jobs that the team member is assigned to.
The first job assignment is considered the team member's primary job.

The minimum length is 1 and the maximum length is 12. | +| `team_member_id` | `str` | Optional | The ID of the team member associated with the wage setting. | +| `job_assignments` | [`List Job Assignment`](../../doc/models/job-assignment.md) | Optional | **Required** The ordered list of jobs that the team member is assigned to.
The first job assignment is considered the team member's primary job. | | `is_overtime_exempt` | `bool` | Optional | Whether the team member is exempt from the overtime rules of the seller's country. | -| `version` | `int` | Optional | Used for resolving concurrency issues. The request fails if the version
provided does not match the server version at the time of the request. If not provided,
Square executes a blind write, potentially overwriting data from another write. For more information,
see [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency). | -| `created_at` | `str` | Optional | The timestamp, in RFC 3339 format, describing when the wage setting object was created.
For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z". | -| `updated_at` | `str` | Optional | The timestamp, in RFC 3339 format, describing when the wage setting object was last updated.
For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z". | +| `version` | `int` | Optional | **Read only** Used for resolving concurrency issues. The request fails if the version
provided does not match the server version at the time of the request. If not provided,
Square executes a blind write, potentially overwriting data from another write. For more information,
see [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency). | +| `created_at` | `str` | Optional | The timestamp when the wage setting was created, in RFC 3339 format. | +| `updated_at` | `str` | Optional | The timestamp when the wage setting was last updated, in RFC 3339 format. | ## Example (as JSON) @@ -35,7 +36,8 @@ An object representing a team member's wage information. "amount": 232, "currency": "NIO" }, - "weekly_hours": 98 + "weekly_hours": 98, + "job_id": "job_id2" }, { "job_title": "job_title6", @@ -48,7 +50,8 @@ An object representing a team member's wage information. "amount": 232, "currency": "NIO" }, - "weekly_hours": 98 + "weekly_hours": 98, + "job_id": "job_id2" }, { "job_title": "job_title6", @@ -61,7 +64,8 @@ An object representing a team member's wage information. "amount": 232, "currency": "NIO" }, - "weekly_hours": 98 + "weekly_hours": 98, + "job_id": "job_id2" } ], "is_overtime_exempt": false, diff --git a/pyproject.toml b/pyproject.toml index 527e76cf..f06cb14c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,11 +4,11 @@ requires = ["setuptools>=61.0"] [project] name = "squareup" description = "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management." -version = "39.0.0.20241120" +version = "39.1.0.20241218" readme = "README.md" requires-python = ">=3.7" authors = [{name = "Square Developer Platform", email = "developers@squareup.com"}] -dependencies = ["apimatic-core~=0.2.0, >= 0.2.15", "apimatic-core-interfaces~=0.1.0, >= 0.1.5", "apimatic-requests-client-adapter~=0.1.0, >= 0.1.6", "deprecation~=2.1"] +dependencies = ["apimatic-core~=0.2.0, >= 0.2.17", "apimatic-core-interfaces~=0.1.0, >= 0.1.5", "apimatic-requests-client-adapter~=0.1.0, >= 0.1.6", "deprecation~=2.1"] [project.optional-dependencies] testutils = ["pytest>=7.2.2"] [tool.setuptools.packages.find] diff --git a/requirements.txt b/requirements.txt index 8efeeaca..c6c51b54 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -apimatic-core~=0.2.0, >= 0.2.15 +apimatic-core~=0.2.0, >= 0.2.17 apimatic-core-interfaces~=0.1.0, >= 0.1.5 apimatic-requests-client-adapter~=0.1.0, >= 0.1.6 deprecation~=2.1 diff --git a/square/api/base_api.py b/square/api/base_api.py index 1f9c7f5a..e7e4f8fc 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -22,7 +22,7 @@ class BaseApi(object): @staticmethod def user_agent(): - return 'Square-Python-SDK/39.0.0.20241120 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' + return 'Square-Python-SDK/39.1.0.20241218 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' @staticmethod def user_agent_parameters(): diff --git a/square/api/payments_api.py b/square/api/payments_api.py index 7296722d..67bb06cf 100644 --- a/square/api/payments_api.py +++ b/square/api/payments_api.py @@ -28,7 +28,10 @@ def list_payments(self, limit=None, is_offline_payment=False, offline_begin_time=None, - offline_end_time=None): + offline_end_time=None, + updated_at_begin_time=None, + updated_at_end_time=None, + sort_field=None): """Does a GET request to /v2/payments. Retrieves a list of payments taken by the account making the request. @@ -47,8 +50,8 @@ def list_payments(self, determined using the `created_at` field for each Payment. Default: The current time. sort_order (str, optional): The order in which results are listed - by `Payment.created_at`: - `ASC` - Oldest to newest. - `DESC` - - Newest to oldest (default). + by `ListPaymentsRequest.sort_field`: - `ASC` - Oldest to + newest. - `DESC` - Newest to oldest (default). cursor (str, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more @@ -85,6 +88,15 @@ def list_payments(self, Payment. If set, payments without a value set in `offline_payment_details.client_created_at` will not be returned. Default: The current time. + updated_at_begin_time (str, optional): Indicates the start of the + time range to retrieve payments for, in RFC 3339 format. The + range is determined using the `updated_at` field for each + Payment. + updated_at_end_time (str, optional): Indicates the end of the time + range to retrieve payments for, in RFC 3339 format. The range + is determined using the `updated_at` field for each Payment. + sort_field (PaymentSortField, optional): The field used to sort + results by. The default is `CREATED_AT`. Returns: ApiResponse: An object with the response value as well as other @@ -138,6 +150,15 @@ def list_payments(self, .query_param(Parameter() .key('offline_end_time') .value(offline_end_time)) + .query_param(Parameter() + .key('updated_at_begin_time') + .value(updated_at_begin_time)) + .query_param(Parameter() + .key('updated_at_end_time') + .value(updated_at_end_time)) + .query_param(Parameter() + .key('sort_field') + .value(sort_field)) .header_param(Parameter() .key('accept') .value('application/json')) diff --git a/square/api/team_api.py b/square/api/team_api.py index 391cd6ac..55bc46ce 100644 --- a/square/api/team_api.py +++ b/square/api/team_api.py @@ -173,14 +173,201 @@ def bulk_update_team_members(self, .convertor(ApiResponse.create) ).execute() + def list_jobs(self, + cursor=None): + """Does a GET request to /v2/team-members/jobs. + + Lists jobs in a seller account. Results are sorted by title in + ascending order. + + Args: + cursor (str, optional): The pagination cursor returned by the + previous call to this endpoint. Provide this cursor to + retrieve the next page of results for your original request. + For more information, see + [Pagination](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/team-members/jobs') + .http_method(HttpMethodEnum.GET) + .query_param(Parameter() + .key('cursor') + .value(cursor)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def create_job(self, + body): + """Does a POST request to /v2/team-members/jobs. + + Creates a job in a seller account. A job defines a title and tip + eligibility. Note that + compensation is defined in a [job assignment]($m/JobAssignment) in a + team member's wage setting. + + Args: + body (CreateJobRequest): An object containing the fields to POST + for the request. See the corresponding object definition for + field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/team-members/jobs') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def retrieve_job(self, + job_id): + """Does a GET request to /v2/team-members/jobs/{job_id}. + + Retrieves a specified job. + + Args: + job_id (str): The ID of the job to retrieve. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/team-members/jobs/{job_id}') + .http_method(HttpMethodEnum.GET) + .template_param(Parameter() + .key('job_id') + .value(job_id) + .should_encode(True)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def update_job(self, + job_id, + body): + """Does a PUT request to /v2/team-members/jobs/{job_id}. + + Updates the title or tip eligibility of a job. Changes to the title + propagate to all + `JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference + the job ID. Changes to + tip eligibility propagate to all `TeamMemberWage` objects that + reference the job ID. + + Args: + job_id (str): The ID of the job to update. + body (UpdateJobRequest): An object containing the fields to POST + for the request. See the corresponding object definition for + field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/team-members/jobs/{job_id}') + .http_method(HttpMethodEnum.PUT) + .template_param(Parameter() + .key('job_id') + .value(job_id) + .should_encode(True)) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + def search_team_members(self, body): """Does a POST request to /v2/team-members/search. - Returns a paginated list of `TeamMember` objects for a business. - The list can be filtered by the following: - - location IDs - - `status` + Returns a paginated list of `TeamMember` objects for a business. + The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` + status, or whether + the team member is the Square account owner. Args: body (SearchTeamMembersRequest): An object containing the fields @@ -322,10 +509,15 @@ def retrieve_wage_setting(self, """Does a GET request to /v2/team-members/{team_member_id}/wage-setting. Retrieves a `WageSetting` object for a team member specified - by `TeamMember.id`. - Learn about [Troubleshooting the Team + by `TeamMember.id`. For more information, see + [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievew agesetting). + Square recommends using + [RetrieveTeamMember]($e/Team/RetrieveTeamMember) or + [SearchTeamMembers]($e/Team/SearchTeamMembers) + to get this information directly from the `TeamMember.wage_setting` + field. Args: team_member_id (str): The ID of the team member for which to @@ -368,13 +560,17 @@ def update_wage_setting(self, """Does a PUT request to /v2/team-members/{team_member_id}/wage-setting. Creates or updates a `WageSetting` object. The object is created if a - `WageSetting` with the specified `team_member_id` does not exist. + `WageSetting` with the specified `team_member_id` doesn't exist. Otherwise, it fully replaces the `WageSetting` object for the team member. - The `WageSetting` is returned on a successful update. - Learn about [Troubleshooting the Team + The `WageSetting` is returned on a successful update. For more + information, see + [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or -update-a-wage-setting). + Square recommends using [CreateTeamMember]($e/Team/CreateTeamMember) + or [UpdateTeamMember]($e/Team/UpdateTeamMember) + to manage the `TeamMember.wage_setting` field directly. Args: team_member_id (str): The ID of the team member for which to diff --git a/square/client.py b/square/client.py index 32318e68..d364e049 100644 --- a/square/client.py +++ b/square/client.py @@ -55,11 +55,11 @@ class Client(object): @staticmethod def sdk_version(): - return '39.0.0.20241120' + return '39.1.0.20241218' @staticmethod def square_version(): - return '2024-11-20' + return '2024-12-18' def user_agent_detail(self): return self.config.user_agent_detail @@ -238,7 +238,7 @@ def __init__(self, http_client_instance=None, retry_statuses=None, retry_methods=None, environment='production', custom_url='https://connect.squareup.com', access_token=None, - bearer_auth_credentials=None, square_version='2024-11-20', + bearer_auth_credentials=None, square_version='2024-12-18', additional_headers={}, user_agent_detail='', config=None): self.config = config or Configuration( http_client_instance=http_client_instance, diff --git a/square/configuration.py b/square/configuration.py index 7c458051..2ec3f3c9 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -45,7 +45,7 @@ def __init__(self, http_client_instance=None, retry_statuses=None, retry_methods=None, environment='production', custom_url='https://connect.squareup.com', access_token=None, - bearer_auth_credentials=None, square_version='2024-11-20', + bearer_auth_credentials=None, square_version='2024-12-18', additional_headers={}, user_agent_detail=''): if retry_methods is None: retry_methods = ['GET', 'PUT']