Securitas Direct New API集成常见问题排查指南

Securitas Direct New API集成常见问题排查指南

问题背景

在使用Securitas Direct New API（原Verisure）与Home Assistant集成时，用户常会遇到登录失败问题。本文针对Docker环境下的Home Assistant集成场景，深入分析典型错误原因并提供专业解决方案。

核心问题分析

1. 国家代码配置错误

• 典型表现：API返回"unknown error"
• 技术要点：Securitas Direct API要求严格的国家代码格式（ISO 3166-1 alpha-2标准）
• 葡萄牙用户注意：必须使用"PT"作为国家代码，而非全称或其他缩写

2. 账户验证机制

• 双重认证影响：即使密码正确，2FA可能触发账户临时锁定
• 服务商限制：Securitas Direct存在主动账户保护机制，连续失败尝试会导致账户冻结

解决方案

分步排查流程

1. 基础验证：

   • 确认使用官方APP可正常登录（建议先注销再重新登录）
   • 检查国家代码是否符合ISO标准（如法国"FR"，西班牙"ES"）

2. 密码重置方案：

   • 通过Securitas Direct官网执行密码重置流程
   • 新密码建议包含大小写字母+数字+特殊字符组合

3. Docker环境检查：

   # 检查Home Assistant容器日志
   docker logs homeassistant | grep securitas
   

   • 关注SSL证书错误或网络连接超时提示

高级技巧

• 日志分析：Home Assistant的configuration.yaml中建议启用debug日志：

  logger:
    default: info
    logs:
      custom_components.securitas_direct_new_api: debug
  

• API限制：Securitas Direct服务端可能有请求频率限制，建议两次尝试间隔至少5分钟

预防措施

1. 首次集成前先在移动端完成账户验证
2. 使用密码管理器保存复杂凭证
3. 定期检查集成组件更新（API接口可能变更）

通过系统化排查，大多数登录问题都可有效解决。如遇持续故障，建议收集完整错误日志提交至社区分析。