Guest Access Control

Last Updated on : 2022-02-17 06:50:02download

Feature overview

TuyaCommunityVisitorService provides the API methods to manage guest access control. For example, create guest passes, check whether a guest drives a car, query pass information, get a list of visit reasons and visit records, and delete invitations.

Query the list of visit reasons

Returns a list of visit reasons that are provided by guests in real time when they submit guest information to generate guest passes.

API description

- (void)getVisitorReasonListWithCommunityId:(NSString *)communityId
                                    success:(void(^)(NSArray<TuyaCommunityVisitorReasonModel *> *list))success
                                    failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Description
communityId	The community ID. You can call `TuyaCommunityHouseModel` to get the value.

Return parameter

Parameter	Description
success	The success callback. A list of visit reasons is returned by `NSArray<TuyaCommunityVisitorReasonModel > list`.
failure	The failure callback. An error message is returned.

Example

     TuyaCommunityHouseModel *houseModel = <#A house returned by the house list query API method#>;
    [self.service getVisitorReasonListWithCommunityId:houseModel.communityId success:^(NSArray<TuyaCommunityVisitorReasonModel *> * _Nonnull list) {
            // success handler
    } failure:^(NSError * _Nonnull error) {
            // failure handler
    }];

Query whether a community allows guest vehicle access

Indicates whether a guest drives a car. This information is provided by guests when they submit guest information to generate guest passes. This API method can be called to check whether a community allows guest vehicle access.

In the response, a Boolean value is returned. True indicates that guest vehicle access is allowed. False indicates that guest vehicle access is not allowed.

API description

 - (void)getCarConfigWithCommunityId:(NSString *)communityId
                            success:(void(^)(BOOL hasCar))success
                            failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Description
communityId	The community ID.

Return parameter

Parameter	Description
success(BOOL hasCar)	Indicates whether guest vehicle access is allowed in the community. Valid values: `true`: yes `false`: no
failure	The failure callback. An error message is returned.

Example

    TuyaCommunityHouseModel *houseModel = <#A house returned by the house list query API method#>;
    [self.service getCarConfigWithCommunityId:houseModel.communityId success:^(BOOL hasCar) {
         // success handler
    } failure:^(NSError * _Nonnull error) {
          // failure handler
    }];

Generate a guest pass

Generates a guest pass after guests submit the name, gender, mobile phone number, visit reason, and other required information.

This API method can be used to query a list of visit reasons and whether guests drive to the community.

API description

- (void)createPassWithCommunityId:(NSString *)communityId
                      visitorName:(NSString *)visitorName
                     visitorPhone:(NSString *)visitorPhone
                              sex:(NSInteger)sex
                    visitorReason:(NSString *)visitorReason
                        startTime:(long long)startTime
                          endTime:(long long)endTime
                 visitorAddressId:(NSString *)visitorAddressId
                         driveCar:(NSInteger)driveCar
                           carNum:(NSString * _Nullable)carNum
                      visitorFrom:(TuyaCommunityVisitorFromEnum)visitorForm
                          success:(void(^)(NSString *visitorId))success
                          failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Required	Type	Description
communityId	Yes	NSString	The community ID. You can call `TuyaCommunityHouseModel` to get the value of `communityId`.
visitorName	Yes	NSString	The name of the guest.
visitorPhone	Yes	NSString	The mobile phone number of the guest.
sex	Yes	int	The gender of the guest. Valid values: `0`: male `1`: female
visitorReasonId	Yes	NSString	The ID of the visit reason.
startTime	Yes	long	The time when the guest arrives at the community.
endTime	Yes	long	The time when the guest leaves the community.
roomId	Yes	NSString	The house ID.
driveCar	No	int	Specifies whether the guest drives to the community. Valid values: `1`: yes `2`: no You must call the API method that indicates whether guest vehicle access is allowed and the return value is `true`. Then, this parameter can be set. Otherwise, the setting of this parameter is invalid.
carNum	No	NSString	The license plate number. This parameter is required for a driving visit.
visitorFrom	Yes	enum(TuyaCommunityVisitorFromEnum)	The source of the guest. Valid values: `1`: registered by the property management staff `2`: invited by an owner

Example

 TuyaCommunityHouseModel *houseModel = <#A house returned by the house list query API method#>;
[self.service createPassWithCommunityId:houseModel.communityId visitorName:nameStr visitorPhone:phoneNumberStr sex:1 visitorReason:visitorReason startTime:startTime endTime:endTime visitorAddressId:houseModel.roomId driveCar:0 carNum:@"xxxx" visitorFrom:2 success:^(NSString * _Nonnull visitorId) {
    // success handler
} failure:^(NSError * _Nonnull error) {
    // failure handler
}];

Cancel an invitation

Cancels a visit prior to the start time of the guest’s visit. Then, the guest is not allowed to visit the community. The guest can be invited to visit again.

API description

- (void)deletePassWithCommunityId:(NSString *)communityId
                        visitorId:(NSString *)visitorId
                          success:(void(^)(BOOL rs))success
                          failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Type	Description
communityId	NSString	The community ID.
visitorId	NSString	The guest ID. The value is included in the list of passes.

Return parameter

Parameter	Description
success	The success callback. Valid values: `true`: canceled successfully. `false`: failed to cancel the invitation.
failure	The failure callback.

Example

[self.service deletePassWithCommunityId:communityId
                         visitorId:visitorId
                           success:(void(^)(BOOL rs)) {
    // success handler
} failure:^(NSError * _Nonnull error) {
    // failure handler
}];

Query guest pass information

Returns details of a guest pass, including the name, gender, visit start time, visit end time, destination, and whether the guest arrives.

API description

- (void)getVisitorPassInfoWithCommunityId:(NSString *)communityId
                                visitorId:(NSString *)visitorId
                                  success:(void(^)(TuyaCommunityVisitorInfoModel *result))success
                                  failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Type	Description
communityId	NSString	The community ID.
visitorId	NSString	The guest ID. The value is included in the list of passes and the generated pass.

Return parameter

Parameter	Description
success(TuyaCommunityVisitorInfoModel *model)	The details of the pass.
failure	The failure callback.

Example

TuyaCommunityHouseModel *houseModel = <#A house returned by the house list query API method#>;
[self.service getVisitorPassInfoWithCommunityId:houseModel.communityId visitorId:visitorId success:^(TuyaCommunityVisitorInfoModel * _Nonnull result) {

	// success handler
} failure:^(NSError * _Nonnull error) {
	// failure handler
}];

Query a list of passes

Returns a list of passes for a user. Passes in the following states are included: not visit, delayed and not visit, canceled, and visited.

Entries can be returned on pages.

API description

 - (void)getVisitorRecordListWithCommunityId:(NSString *)communityId
                                      roomId:(NSString *)roomId
                                      pageNo:(NSInteger)pageNo
                                    pageSize:(NSInteger)pageSize
                                     success:(void(^)(TuyaCommunityVisitorRecordListModel *result))success
                                     failure:(void(^)(NSError *error))failure;

Request parameter

Parameter	Description
communityId	The community ID. You can call `TuyaCommunityHouseModel` to get the value.
roomId	The room ID. You can call `TuyaCommunityHouseModel` to get the value.
pageNo	The number of the current page.
pageSize	The number of entries per page.

Return parameter

Parameter	Description
success(TuyaCommunityVisitorRecordListModel *result	The list of returned passes.
failure	The failure callback.

Example

TuyaCommunityHouseModel *houseModel = <#A house returned by the house list query API method#>;
[self.service getVisitorRecordListWithCommunityId:houseModel.communityId roomId:houseModel.roomId pageNo:pageNo pageSize:pageSize success:^(TuyaCommunityVisitorRecordListModel * _Nonnull result) {
	// success handler
} failure:^(NSError * _Nonnull error) {
	// failure handler
}];

Object description

TuyaCommunityVisitorReasonModel

Data model of visit reasons

Property	Type	Description
visitorReasonId	NSString	The ID of a visit reason.
visitorReason	NSString	The visit reason.
remark	NSString	The remarks.
timeLimitType	int	The type of time limit. Valid values: 1: hour 2: day 3: no limit
timeLimitValue	int	The value of a time limit.

TuyaCommunityVisitorInfoModel

Guest pass information

Property	Type	Description
visitorId	NSString	The ID of the guest.
visitorName	NSString	The name of the guest.
visitorPhone	NSString	The mobile phone number of the guest.
sex	NSString	The gender of the guest. Valid values: `0`: male `1`: female
visitorReason	NSString	The visit reason.
visitorAddressId	NSString	The ID of the destination address. The value is the same as `roomId` for a house ID.
visitorAddress	NSString	The destination address.
visitorTime	long	The visit time.
visitorStatus	int	The visit state. Valid values: `0`: not visit `1`: visited `2`: delayed and not visit
visitorFrom	int	The source of the guest. Valid values: `1`: registered by the property management staff `2`: invited by an owner
hasCar	int	Specifies whether the guest drives a car. Valid values: `1`: yes `2`: no
carNum	NSString	The license plate number.
visitorFace	NSString	The biometric identity.
startTime	long long	The start time of a visit.
endTime	long long	The end time of a visit.
intervieweeName	NSString	The name of the host.
intervieweePhone	NSString	The mobile phone number of the host.
visitorCapabilityList	NSArray<NSNumber >	The type of access control method: Valid values: `1`: QR code `2`: biometric identity

TuyaCommunityVisitorRecordListModel

List of guest passes

Property	Type	Description
visitorId	NSString	The ID of the guest.
visitorName	NSString	The name of the guest.
phone	NSString	The mobile phone number of the guest.
sex	NSString	The gender of the guest. Valid values: `0`: male `1`: female
visitorReason	NSString	The visit reason.
visitorAddress	NSString	The destination address.
intervieweeName	NSString	The name of the host.
intervieweePhone	NSString	The mobile phone number of the host.
visitorTime	long long	The visit time.
visitorStatus	int	The visit state. Valid values: `0`: not visit `1`: visited `2`: delayed and not visit
visitorStatusStr	NSString	The string of the visit state.
visitorFrom	int	The source of the guest. Valid values: `1`: registered by the property management staff `2`: invited by an owner
applyTime	long long	The time when the guest information is submitted.
startTime	long long	The start time of a visit.
endTime	long long	The end time of a visit.
carNum	NSString	The license plate number.

Prev DocSmart Access Control

Next DocCloud-Based Video Talk