> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新最终受益所有人信息

更改有效关联的持股比例和/或控制角色。

* 请求体为空时返回 400 VALIDATION\_ERROR。
* personId、validFrom 和 validTo 无法更改；请结束该关联并创建新的关联。

错误使用 `application/problem+json` 格式，并附带固定的 `code`。完整目录：[实体状态和错误代码](https://docs.localpayment.com/zh/reference/entity-statuses-and-error-codes.md)。


## OpenAPI

````yaml openapi/zh/localpayment.json PATCH /api/entity/v1/entities/{companyId}/ubos/{uboId}
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/entity/v1/entities/{companyId}/ubos/{uboId}:
    patch:
      summary: 更新 UBO
      operationId: update-ubo
      parameters:
        - name: Authorization
          in: header
          description: >-
            用于身份验证的 Bearer
            访问令牌。该令牌可从[获取访问令牌](/zh/reference/get-token)或[刷新访问令牌](/zh/reference/refresh-token)endpoint
            获取。系统将据此识别您的商户账户和执行操作的用户。
          required: true
          schema:
            type: string
            examples:
              - Bearer <your_access_token>
        - name: X-Correlation-ID
          in: header
          description: 跟踪标识符（UUID）。会在响应中原样返回；如未提供，则由 Localpayment 生成。
          required: false
          schema:
            type: string
            examples:
              - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
        - name: companyId
          in: path
          description: COMPANY 的 internalId。
          required: true
          schema:
            type: string
            examples:
              - 7c9e6679-7425-40de-944b-e07fc1f90ae7
            format: uuid
        - name: uboId
          in: path
          description: UBO 链接 ID。
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - 4584b476-ccc6-4e98-be40-0c5082748e35
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ownershipPercentage:
                  type: number
                  description: 0 到 100，最多保留两位小数。
                  examples:
                    - 55.5
                controlRole:
                  type: string
                  description: >-
                    新角色，为链接 UBO（Link a UBO）中的代码之一。空字符串会返回 422
                    INVALID_CONTROL_ROLE；角色不能被清空。
                  examples:
                    - PARTNER
                  enum:
                    - CEO
                    - CFO
                    - COO
                    - CTO
                    - PRESIDENT
                    - VICE_PRESIDENT
                    - DIRECTOR
                    - MANAGING_DIRECTOR
                    - MANAGING_PARTNER
                    - GENERAL_PARTNER
                    - PARTNER
                    - SECRETARY
                    - TREASURER
                    - CHAIRMAN
                    - BOARD_MEMBER
                    - AUTHORIZED_SIGNATORY
                    - GENERAL_COUNSEL
                    - OWNER
                    - FOUNDER
                    - MANAGER
                    - MEMBER
                    - COMPTROLLER
                    - CHIEF_COMPLIANCE_OFFICER
                    - LEGAL_REPRESENTATIVE
            examples:
              Example 1:
                value:
                  ownershipPercentage: 55.5
                  controlRole: ''
      responses:
        '200':
          description: OK。
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    examples:
                      - 4584b476-ccc6-4e98-be40-0c5082748e35
                    description: UBO 链接标识符（uboId）。
                  companyId:
                    type: string
                    examples:
                      - 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    format: uuid
                    description: 公司实体。
                  personId:
                    type: string
                    examples:
                      - c1e384f5-ae1c-475e-9e64-a0abe533a96f
                    format: uuid
                    description: INDIVIDUAL 实体。此处不会返回该人员的任何个人数据。
                  ownershipPercentage:
                    type:
                      - number
                      - 'null'
                    examples:
                      - 55.5
                    description: 0 到 100，最多保留两位小数。
                  controlRole:
                    type:
                      - string
                      - 'null'
                    description: >-
                      职位名称使用大写字母，例如
                      CEO、PARTNER、DIRECTOR、LEGAL_REPRESENTATIVE。如果未告知，则为 null。
                  validFrom:
                    type: string
                    examples:
                      - '2024-01-15'
                    format: date
                    description: 链接的有效性。当链接处于活动状态时，validTo 为空。
                  validTo:
                    type:
                      - string
                      - 'null'
                    format: date
                    description: 链接的有效性。当链接处于活动状态时，validTo 为空。
                  createdAt:
                    type: string
                    examples:
                      - '2024-01-15T17:20:47Z'
                    format: date-time
                    description: 创建时间。
              examples:
                Example 1:
                  value:
                    id: 4584b476-ccc6-4e98-be40-0c5082748e35
                    companyId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    personId: c1e384f5-ae1c-475e-9e64-a0abe533a96f
                    ownershipPercentage: 55.5
                    controlRole: null
                    validFrom: '2024-01-15'
                    validTo: null
                    createdAt: '2024-01-15T17:20:47Z'
        '400':
          description: 错误请求。验证错误：缺少字段、标头、路径或查询参数，或者参数未知或无效。details[] 列出了字段和问题。
          content:
            application/problem+json:
              schema:
                type: object
                description: RFC 9457 问题详情（application/problem+json）。
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: 问题简述。
                  status:
                    type: integer
                    description: HTTP状态码。
                  detail:
                    type: string
                    description: 易于理解的解释。
                  instance:
                    type: string
                    description: 请求路径。
                  code:
                    type: string
                    description: 稳定的机器可读错误代码。根据此值进行分支。
                  correlationId:
                    type: string
                    format: uuid
                    description: 请求标识符。联系客服时请提供此标识符。
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: 出错字段（如适用）。
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - VALIDATION_ERROR:
                  value:
                    type: about:blank
                    title: Validation error
                    status: 400
                    detail: >-
                      A field, header, path or query parameter is missing,
                      unknown or invalid. details[] lists field and issue.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: VALIDATION_ERROR
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details:
                      - field: externalId
                        issue: REQUIRED
        '401':
          description: 未授权。UNAUTHORIZED：缺少或无效的访问令牌。
          content:
            application/problem+json:
              schema:
                type: object
                description: RFC 9457 问题详情（application/problem+json）。
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: 问题简述。
                  status:
                    type: integer
                    description: HTTP状态码。
                  detail:
                    type: string
                    description: 易于理解的解释。
                  instance:
                    type: string
                    description: 请求路径。
                  code:
                    type: string
                    description: 稳定的机器可读错误代码。根据此值进行分支。
                  correlationId:
                    type: string
                    format: uuid
                    description: 请求标识符。联系客服时请提供此标识符。
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: 出错字段（如适用）。
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - UNAUTHORIZED:
                  value:
                    type: about:blank
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid access token.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: UNAUTHORIZED
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '404':
          description: >-
            未找到。ENTITY_NOT_FOUND：该实体不存在或属于其他商户。UBO_NOT_FOUND：UBO
            链接不存在、已失效或属于其他商户。
          content:
            application/problem+json:
              schema:
                type: object
                description: RFC 9457 问题详情（application/problem+json）。
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: 问题简述。
                  status:
                    type: integer
                    description: HTTP状态码。
                  detail:
                    type: string
                    description: 易于理解的解释。
                  instance:
                    type: string
                    description: 请求路径。
                  code:
                    type: string
                    description: 稳定的机器可读错误代码。根据此值进行分支。
                  correlationId:
                    type: string
                    format: uuid
                    description: 请求标识符。联系客服时请提供此标识符。
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: 出错字段（如适用）。
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - ENTITY_NOT_FOUND:
                  value:
                    type: about:blank
                    title: Not found
                    status: 404
                    detail: The entity does not exist or belongs to another merchant.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: ENTITY_NOT_FOUND
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 2 - UBO_NOT_FOUND:
                  value:
                    type: about:blank
                    title: Not found
                    status: 404
                    detail: >-
                      The UBO link does not exist, has already ended, or belongs
                      to another merchant.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: UBO_NOT_FOUND
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '409':
          description: >-
            冲突。ENTITY_IN_REVIEW：该实体处于 IN_REVIEW 状态：在 Localpayment
            合规团队处理完毕之前，其数据、文档、文件和 UBO 关联将被冻结。
          content:
            application/problem+json:
              schema:
                type: object
                description: RFC 9457 问题详情（application/problem+json）。
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: 问题简述。
                  status:
                    type: integer
                    description: HTTP状态码。
                  detail:
                    type: string
                    description: 易于理解的解释。
                  instance:
                    type: string
                    description: 请求路径。
                  code:
                    type: string
                    description: 稳定的机器可读错误代码。根据此值进行分支。
                  correlationId:
                    type: string
                    format: uuid
                    description: 请求标识符。联系客服时请提供此标识符。
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: 出错字段（如适用）。
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - ENTITY_IN_REVIEW:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: >-
                      The entity is IN_REVIEW: its data, documents, files and
                      UBO links are frozen until Localpayment Compliance
                      resolves it.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/37325b16-514f-40f5-afca-a2acd201f629
                    code: ENTITY_IN_REVIEW
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
        '422':
          description: >-
            无法处理的实体。INVALID_PERCENTAGE：ownershipPercentage 不在 0 到 100
            的范围内，或小数位数超过两位。INVALID_CONTROL_ROLE：controlRole 不是 Link a UBO
            中列出的角色代码之一。代码区分大小写：director 会返回此错误。
          content:
            application/problem+json:
              schema:
                type: object
                description: RFC 9457 问题详情（application/problem+json）。
                properties:
                  type:
                    type: string
                    examples:
                      - about:blank
                  title:
                    type: string
                    description: 问题简述。
                  status:
                    type: integer
                    description: HTTP状态码。
                  detail:
                    type: string
                    description: 易于理解的解释。
                  instance:
                    type: string
                    description: 请求路径。
                  code:
                    type: string
                    description: 稳定的机器可读错误代码。根据此值进行分支。
                  correlationId:
                    type: string
                    format: uuid
                    description: 请求标识符。联系客服时请提供此标识符。
                    examples:
                      - 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                  details:
                    type: array
                    description: 出错字段（如适用）。
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          examples:
                            - numberOfEmployees
                        issue:
                          type: string
                          examples:
                            - NOT_IN_OPTIONS
              examples:
                Example 1 - INVALID_PERCENTAGE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: >-
                      ownershipPercentage is outside 0 to 100 or has more than
                      two decimals.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: INVALID_PERCENTAGE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
                Example 2 - INVALID_CONTROL_ROLE:
                  value:
                    type: about:blank
                    title: Unprocessable entity
                    status: 422
                    detail: >-
                      controlRole is not one of the role codes listed in Link a
                      UBO. Codes are case-sensitive: director returns this
                      error.
                    instance: >-
                      /api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos/4584b476-ccc6-4e98-be40-0c5082748e35
                    code: INVALID_CONTROL_ROLE
                    correlationId: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10
                    details: []
      security:
        - token: []
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.