Guest Access Control

Last Updated on : 2021-09-29 13:54:53download

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.