Caliber Technology TaxQuery 镜像文档

1. 镜像概述与主要用途

Caliber Technology TaxQuery 是一个 Web 服务镜像，主要用于根据美国薪资员工的工作地点和居住地址，确定其税务辖区名称。该服务返回的税务名称与 calibertechnology/taxserver 镜像及 taxupdate.com 提供的 TaxControls 组件所使用的税务名称保持一致，确保系统间数据兼容性。

2. 核心功能与特性

• 税务辖区名称解析：基于员工的工作地点和居住地址，精确计算并返回对应的美国税务辖区名称。
• 兼容性保障：税务名称规范与 calibertechnology/taxserver 镜像及 TaxControls 组件（taxupdate.com）完全对应，支持无缝集成。
• 网络协议支持：默认提供 HTTP（端口 80）和 HTTPS（端口 8443）两种访问方式，满足不同安全需求。

3. 使用场景与适用范围

适用场景

• 美国企业薪资管理系统：集成到薪资计算流程中，自动获取员工税务辖区信息。
• 人力资源（HR）软件：为员工信息管理模块提供税务辖区数据支持。
• 财务系统：辅助完成薪资税务申报、合规性检查等流程。

目标用户

• 薪资软件开发者：需集成税务辖区解析功能的系统开发人员。
• 企业 IT 部门：负责部署和维护薪资相关服务的技术团队。
• 人力资源技术供应商：构建 HR 或 payroll 解决方案的供应商。

4. 使用方法与配置说明

4.1 基本部署示例

4.1.1 默认 HTTPS 部署

通过默认 HTTPS 端口（8443）启动服务：

bash
docker run -p 8443:8443 calibertechnology/taxquery

服务启动后，访问 https://localhost:8443 可查看 API 描述文档。注意：服务默认使用自签名 TLS 证书，浏览器会提示加密安全警告，需手动信任证书后访问。

4.1.2 仅 HTTP 部署

若无需 HTTPS，可通过默认 HTTP 端口（80）启动：

bash
docker run -p 80:80 calibertechnology/taxquery

4.2 自定义端口配置

通过环境变量 HTTP_PORT 和 HTTPS_PORT 可修改默认端口，适用于端口冲突或特定网络策略场景。

4.2.1 自定义 HTTPS 端口

例如，将 HTTPS 端口修改为 443：

bash
export HTTPS_PORT="443"
docker run --env HTTPS_PORT -p 443:443 calibertechnology/taxquery

4.2.2 自定义 HTTP 端口

例如，将 HTTP 端口修改为 8080：

bash
export HTTP_PORT="8080"
docker run --env HTTP_PORT -p 8080:8080 calibertechnology/taxquery

4.3 配置参数说明

5. 注意事项

• 自签名证书：HTTPS 模式下使用自签名证书，生产环境建议替换为可信 CA 颁发的证书。
• 地址数据格式：服务依赖标准的美国地址格式（含街道、城市、州、邮编），需确保输入地址信息完整准确。
• 兼容性：仅支持美国税务辖区解析，非美国地址可能无法返回有效结果。