数据校验

数据校验适用于通过账户创建（POST /v1/accounts）和更新（PATCH /v1/accounts/:account_id）端点的请求。如果通过这些端点提交的用户信息不符合我们的校验标准，将返回 422 错误。（在某些流程中，可能改为返回带有代码 40010001 的 400。）与 Broker API 集成（包括 KYC 和代理行流程）的合作方应确保其系统符合以下所有标准。

---

校验标准

校验标准包括以下内容：

姓名和地址罗马化

• given_name、middle_name、family_name、street_address、unit、city、state、postal_code、email_address 和 tax_id 都必须以拉丁字符提供。这些字段接受的输入将限于 ASCII 字符范围 32–126。
• 我们引入了以下字段，以便在需要时继续接受原始文字的姓名和地址信息：local_given_name、local_middle_name、local_family_name、local_street_address、local_unit、local_city 和 local_state。

名字

• 现在所有用户都需要 given_name（identity.given_name）。

税务 ID 号校验

• 证券账户需要 tax_id（identity.tax_id）。
• 如果税务 ID 类型为 USA_SSN 或 USA_ITIN，则必须满足以下条件：
  • 区域号（前三位数字）不得为 000 或 666。
  • 组号（中间两位数字）不得为 00。
  • 序列号（后四位数字）不得为 0000。
  • 不得所有位数均为同一数字，例如 000-00-0000、111-11-1111、333-33-3333、666-66-6666、999-99-9999，也不得所有字符递增或递减（例如 123-45-6789 或 987-65-4321）。
  • 去除破折号后，值的长度必须正好为 9 个字符。
• 所有税务 ID 类型都将经过以下校验：
  • 长度必须大于 1 个字符（例如不允许提交 0 作为税务 ID）。
  • 不得所有位数均为同一数字，也不得所有字符递增或递减（如上所述）。
  • 最大长度为 40 个字符。
  • 仅允许字母、数字、破折号（ASCII 字符 45）、句点和加号（+）。
  • 值必须包含数字（例如不允许提交 TIN_NOT_ISSUED 或 xxx-xxx-xxxx）。
• 作为对在未发放税务 ID 号的地区为用户开户的合作方的一般提醒，仍需为这些用户提交唯一标识符。该标识符应为国民身份证号、护照号、永久居民号、驾驶证号等。我们引入了以下 tax_id_type 值以支持这些分类：NATIONAL_ID、PASSPORT、PERMANENT_RESIDENT、DRIVER_LICENSE、OTHER_GOV_ID。

street_address 校验

• 不得仅由数字组成。
• 长度必须大于 1 个字符。
• 已为 street_address（contact.street_address）字段引入校验，防止为住宅地址提交美国邮政信箱（PO Box）。此校验不区分大小写，会检测指示 PO Box 的关键词，包括：PO Box、Post Office Box、P.O. Box 和 Box #。如果检测到禁止的值，请求将被阻止，返回 422 错误，并带有特定消息："street_address cannot be a P.O. Box"。此校验适用于通过 POST /v1/accounts 和 PATCH /v1/accounts/:account_id 端点的请求，合作方应确保其系统准备好处理此校验错误。

邮编校验

• 总体最大长度： postal_code（contact.postal_code）和 local_postal_code（contact.local_postal_code）为 12 个字符。
• 如果税务居住国 = USA：
  • 账户创建时将需要 postal_code 属性。
  • 不得少于 5 个字符，且前 5 个字符必须仅包含数字。
  • 不得超过 10 位数字。
• 英国：postal_code 必须匹配英国邮编格式（例如 SW4 6EH）。格式无效将返回错误。
• 加拿大：postal_code 必须匹配加拿大邮编格式（例如 A1A 1A1）。格式无效将返回错误。

date_of_birth 校验

• 长度不得大于或小于 10 个字符。date_of_birth（identity.date_of_birth）的值必须为 YYYY-MM-DD 格式。

电子邮件地址

• 移除别名后，电子邮件地址（contact.email_address）的长度限制为最多 60 个字符。Alpaca 将别名定义为 + 号之后、@ 号之前的所有字符。存储值还受 100 个字符 数据库限制约束。

州校验

• 对于所有国家：
  • state（contact.state）的最大长度不应大于 50 个字符。
  • state 不能仅由数字组成。它可以包含字母和数字。
• 如果税务居住国 = USA：
  • state 将限于州的 2 字母缩写代码或我们文档中定义的州完整名称。

城市

• city（contact.city）属性不能仅由数字组成。它可以包含字母和数字。长度必须介于 2 到 50 个字符之间（个人），或 2 到 100 个字符之间（法律实体）。

空白字符校验

• 以下校验将应用于 Accounts API 上的 given_name、middle_name、family_name、street_address、unit、city、state、postal_code、email_address、tax_id_type 和 tax_id 字段（即 identity.given_name、identity.middle_name、identity.family_name、contact.street_address、contact.unit、contact.city、contact.state、contact.postal_code、contact.email_address、identity.tax_id_type、identity.tax_id）：
  • 空格字符（ASCII 字符 32）将是我们唯一接受的空白字符。
  • 字符串中存在前导和尾随空格将返回 422 错误。
• 此外，我们可能会清理系统中包含无效空白字符的现有账户。我们将直接与受影响的合作方跟进，并分享我们将要更新的完整账户和数据点列表。

---

字段长度限制（附加约束）

除上述标准外，还强制执行以下 最大字符长度。超出限制将返回错误（例如 "\<field> must not be longer than \<N>" 或 "unit/apt # too long, must be less than 20 characters"）。

字段使用 object.field 表示法：contact（地址、电子邮件、电话）、identity（姓名、税务、国籍、签证）、disclosures（就业、关联）。referral_source 位于账户/所有者级别。

---

unit 和 local_unit（公寓 / 套房）

• contact.unit 和 contact.local_unit 是可选的，但一旦提供，长度限制为 20 个字符。这些字段仅用于公寓、套房或单元标识（例如 "Ste 100"、"Apt 4B"）。请 不要 将完整街道行放入 unit（例如 "2424 S 90th St Ste 100"）；将完整街道地址放入 contact.street_address，仅将单元标识放入 contact.unit。超出限制将返回错误，例如 "unit must not be longer than 20" 或 "unit/apt # too long, must be less than 20 characters"。

---

附加校验（签证、国家、法律实体、受益人）

签证（非美国公民 / 居民）

• 当 identity.visa_type 为 B1 或 B2 时，identity.country_of_tax_residence 必须为 USA。
• identity.visa_type 必须是文档中允许值之一（例如 E1、E2、E3、F1、H1B、TN1、O1、J1、L1、B1、B2、DACA、G4、OTHER）。
• 当提供了 identity.visa_type 且不为空时，identity.visa_expiration_date 可能是必需的，且必须为 YYYY-MM-DD 格式。

国家与国家代码

• contact.country、identity.country_of_tax_residence、identity.country_of_citizenship、identity.country_of_incorporation 以及类似的国家字段必须为 ISO 3166-1 alpha-3（正好 3 个字符，例如 USA、GBR、CAN）。

法律实体

• identity.legal_name（或 entity_name）为必填。identity.country_of_incorporation 为必填；如果为 USA，identity.state_of_incorporation 可能为必填。identity.date_of_incorporation 为必填（YYYY-MM-DD）。identity.entity_type 或 identity.legal_entity_type 为必填；如果为 other，identity.legal_entity_type_other_free_text 可能为必填。identity.funding_source 为必填；如果包含 other，identity.funding_source_other_free_text 可能为必填。identity.type_of_business 为必填；如果为 other，identity.type_of_business_other_free_text 可能为必填。法律实体账户需要 contact.country。

披露（股票账户）

• 对于股票账户，个人（非法律实体）需要 disclosures。disclosures.employment_status 必须是允许值之一（例如 EMPLOYED、UNEMPLOYED、RETIRED、STUDENT）。disclosures.employment_sector（提供时）会结合 employment_status 进行校验。其他披露字段（例如 is_control_person、is_politically_exposed、is_affiliated_exchange_or_finra、immediate_family_exposed）可能会根据账户类型和产品要求提供或校验。

受益人（例如 IRA）

• 受益人最大数量：所有受益人的 share_pct 之和必须等于 100；每个值必须是 ≤ 100 的正数；精度通常有限制（例如最多 2 位小数）。每个受益人可能需要 given_name、family_name、date_of_birth（YYYY-MM-DD）、tax_id，适用时还需要 tax_id_type；tax_id 受相同的税务 ID 规则约束（例如 USA_SSN/USA_ITIN 的 SSN/ITIN）。

错误响应

• 校验失败通常会返回 422 Unprocessable Entity 或 400 Bad Request，并附带错误代码（例如 40010001）和描述失败规则的消息。合作方应基于这些响应实现健壮的错误处理和面向用户的消息。

---

汇总表（快速参考）

---

本文档反映了适用于 Broker API 的账户创建（POST /v1/accounts）和账户/所有者更新（PATCH /v1/accounts/:account_id 及相关所有者详情修补）的校验，包括 KYC 和代理行流程。Alpaca 可能随时间更新这些规则；合作方应妥善处理校验错误，并参考最新的 API 文档和错误消息。