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

# 创建指令

> Creates a purchase instruction (spending authorization) for the token's customer and returns a short-lived activation link that the user opens to approve it with a Passkey. Requires `portal:write`.

`payment_instrument_id` 决定使用哪种签约模式：

* **指定卡签约**：传 `payment_instrument_id`。指令状态为 `CREATED`，激活链接打开该卡的授权页。
* **绑卡并签约**：省略 `payment_instrument_id`。指令状态为 `PENDING`，激活链接打开绑卡和授权流程，用户在一次 Passkey ceremony 中完成绑卡和授权。

指定卡签约时，从[支付方式列表](https://docs.clinkbill.com/cn/api-reference/agent-portal/list_payment_methods.md)获取 `payment_instrument_id`。绑卡并签约时，不要发送卡号、CVV 或任何其他卡片字段；用户在 Clink 页面输入卡片信息。客户身份始终来自 token；请求体中没有 customer 或 email 字段。

激活链接的签名会话兑换完成后，指定卡指令继续进入 `/authorize/{paymentInstrumentId}?instructionId=...`；绑卡并签约指令继续进入 `/bind-authorize?instructionId=...`，用户在那里完成绑卡和授权（同一次 Passkey ceremony）。

> [!WARNING]
>
> 把激活链接当作凭证处理。不要转发、截图或写入日志；拿到链接的人可以在链接有效期内打开它，并取得该客户的 Clink 浏览器登录态。只把链接发给目标用户。

## 激活指令

创建指令不等于授权。指定已有卡的指令状态为 `CREATED`；需要绑卡的指令状态为 `PENDING`。两者都只有用户在 Clink 签名页完成 Passkey 验证后才变为 `ACTIVE`。链接在有效期内可以重新打开或刷新，但指令只能签署一次。

1. 让用户在浏览器中打开 `activation_url`。
2. `CREATED` 指令由用户确认卡片并完成 Passkey 验证；`PENDING` 指令由用户在同一次 ceremony 中完成绑卡和 Passkey 验证。页面会建立浏览器登录态并继续到授权步骤。
3. 轮询 [`GET /agent/platform/authorizations/{instructionId}`](https://docs.clinkbill.com/cn/api-reference/agent-portal/get_authorization)，直到 `status` 为 `ACTIVE`。

如果用户没有完成该流程，指令保持 `CREATED` 或 `PENDING`，不会授权任何消费。链接只发给目标用户；它是激活链接，不是 portal token。

## 幂等

`request_id` 是幂等键，两种签约模式规则一致。Clink 默认保留幂等记录 24 小时；超过该窗口后，用同一 `request_id` 重试会新建一条指令。窗口内使用完全一致的参数重试会返回同一 `instruction_id`；对尚未签署的指令正常重试会返回新的激活链接。如果重试的 `request_id` 对应已签署或已终态的指令，Clink 返回该指令但不返回新的 `activation_url` 或 `activation_expires_at`（这两个字段会被省略）；请读取 [`GET /agent/platform/authorizations/{instructionId}`](https://docs.clinkbill.com/cn/api-reference/agent-portal/get_authorization) 获取当前状态。相同 `request_id` 携带不同参数返回 `409`，`code` 为 `71211011`（`portal_conflict`）。


## OpenAPI

````yaml POST /agent/platform/authorizations
openapi: 3.1.0
info:
  title: Clink Agent Portal API
  description: >-
    Agent Portal APIs let an Agent platform read and manage one user's Clink
    account with a portal user token: payment methods, orders, refunds, purchase
    instructions, payment credentials, payment results, and settings.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com
    description: Sandbox
security:
  - PortalToken: []
paths:
  /agent/platform/authorizations:
    post:
      summary: Create instruction
      description: >-
        Creates a purchase instruction (spending authorization) for the token's
        customer and returns a short-lived activation link that the user opens
        to approve it with a Passkey. Requires `portal:write`.
      operationId: createInstruction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstructionRequest'
            examples:
              existingCard:
                summary: Sign with an existing card
                value:
                  request_id: platform-ref-001
                  title: Office supplies budget
                  description: Monthly office supplies purchase
                  payment_instrument_id: pi_...
                  is_recurring: false
                  effective_until_time: '2026-12-31 23:59:59'
                  shipping_address:
                    name: Example User
                    line1: 1 Market Street
                    line2: Suite 100
                    line3: null
                    city: San Francisco
                    state: CA
                    zip: '94105'
                    country_code: US
                  mandates:
                    - description: Purchase office supplies
                      amount_limit: '100.00'
                      currency_code: USD
                      recurring_frequency: null
                      merchant_category_code: '5732'
                      preferred_merchant_name: null
                      effective_until_time: null
              bindAndSign:
                summary: Bind a card and sign
                value:
                  request_id: platform-ref-002
                  title: Office supplies budget
                  description: Monthly office supplies purchase
                  is_recurring: false
                  shipping_address:
                    name: Example User
                    line1: 1 Market Street
                    line2: Suite 100
                    line3: null
                    city: San Francisco
                    state: CA
                    zip: '94105'
                    country_code: US
                  mandates:
                    - description: Purchase office supplies
                      amount_limit: '100.00'
                      currency_code: USD
                      recurring_frequency: null
                      merchant_category_code: '5732'
                      preferred_merchant_name: null
                      effective_until_time: null
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: '`200` on success.'
                    example: 200
                  msg:
                    type: string
                    description: Result message.
                    example: Success
                  data:
                    $ref: '#/components/schemas/CreateInstructionResponse'
              examples:
                existingCard:
                  summary: Sign with an existing card
                  value:
                    code: 200
                    msg: Success
                    data:
                      instruction_id: inst_...
                      status: CREATED
                      payment_instrument_id: pi_...
                      activation_url: https://agent.clinkbill.dev/sign/ss_...
                      activation_expires_at: '2026-11-09T10:30:00Z'
                bindAndSign:
                  summary: Bind a card and sign
                  value:
                    code: 200
                    msg: Success
                    data:
                      instruction_id: inst_...
                      status: PENDING
                      activation_url: https://agent.clinkbill.dev/sign/ss_...
                      activation_expires_at: '2026-11-09T10:30:00Z'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, expired, or invalid portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Wrong token audience, missing `portal:write` scope, or a platform
            client token used instead of a portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `request_id` was reused with different parameters
            (`portal_conflict`, `code` `71211011`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateInstructionRequest:
      type: object
      required:
        - request_id
        - title
        - mandates
      properties:
        request_id:
          type: string
          description: Platform-side reference and idempotency key, 8–128 characters.
          minLength: 8
          maxLength: 128
          example: platform-ref-001
        title:
          type: string
          description: Non-empty instruction title.
          minLength: 1
          example: Office supplies budget
        description:
          type: string
          description: Instruction description.
          example: Monthly office supplies purchase
        payment_instrument_id:
          type: string
          description: >-
            Existing usable payment instrument owned by the token's customer.
            Omit it to bind a new card and sign.
          example: pi_...
        is_recurring:
          type: boolean
          description: >-
            Whether the instruction contains recurring mandates. When `true`,
            every mandate must include `recurring_frequency`.
          example: false
        effective_until_time:
          type: string
          description: >-
            Last time the instruction can be used, in UTC `yyyy-MM-dd HH:mm:ss`.
            Ignored in bind-and-sign mode: Clink overrides it (and each
            mandate's `effective_until_time`) with now +
            `pendingActivationWindowMinutes` (7 days by default), so read the
            effective value from the instruction.
          example: '2026-12-31 23:59:59'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
        mandates:
          type: array
          description: One or more mandates.
          items:
            $ref: '#/components/schemas/MandateInput'
          minItems: 1
    CreateInstructionResponse:
      type: object
      properties:
        instruction_id:
          type: string
          description: Created instruction ID.
          example: inst_...
        status:
          type: string
          description: >-
            Instruction status: `CREATED` when signing with an existing card,
            `PENDING` when binding a new card.
          enum:
            - CREATED
            - PENDING
          example: CREATED
        payment_instrument_id:
          type: string
          description: >-
            Payment instrument the instruction uses. Absent or `null` in
            bind-and-sign mode, where no card is bound yet.
          example: pi_...
        activation_url:
          type: string
          description: >-
            Short-lived activation link the user opens to approve the
            instruction. In bind-and-sign mode, the page also collects the card
            before authorization, in the same Passkey ceremony. The link
            contains an opaque signing session ID, not a portal token, and can
            be exchanged for a normal Clink browser login session for that
            customer while it is valid. It supports repeated exchanges (for
            example, when the user refreshes the page) and stops working at
            `activation_expires_at` (30 minutes by default) or once the
            instruction becomes `ACTIVE` or final. Omitted when a retried
            `request_id` refers to an instruction that is already signed or
            final.
          example: https://agent.clinkbill.dev/sign/ss_...
        activation_expires_at:
          type: string
          description: >-
            Time after which the activation link no longer works. Omitted
            together with `activation_url`.
          format: date-time
          example: '2026-11-09T10:30:00Z'
    ErrorResponse:
      type: object
      description: Business errors use the standard envelope without `data`.
      properties:
        code:
          type: integer
          description: >-
            Numeric business error code. Judge an error by the HTTP status
            together with `code`, not by a string error code.
        msg:
          type: string
          description: Human-readable description.
    ShippingAddress:
      type: object
      description: Shipping address.
      properties:
        name:
          type: string
          description: Recipient name.
          example: Example User
        line1:
          type: string
          description: Address line 1.
          example: 1 Market Street
        line2:
          type: string
          description: Address line 2.
          example: Suite 100
        line3:
          type: string
          description: Address line 3.
        city:
          type: string
          description: City.
          example: San Francisco
        state:
          type: string
          description: State or province.
          example: CA
        zip:
          type: string
          description: Postal code.
          example: '94105'
        country_code:
          type: string
          description: Country code.
          example: US
    MandateInput:
      type: object
      required:
        - description
        - amount_limit
        - currency_code
      properties:
        description:
          type: string
          description: Non-empty purpose of the authorized spending.
          minLength: 1
          example: Purchase office supplies
        amount_limit:
          type: string
          description: >-
            Positive decimal string in major currency units, at most 18 integer
            digits and 2 decimal places. `"100.00"` means USD 100.00.
          example: '100.00'
        currency_code:
          type: string
          description: >-
            Three-letter currency code. All mandates in one instruction must use
            the same currency.
          example: USD
        recurring_frequency:
          type: string
          description: Required for every mandate when `is_recurring` is `true`.
          enum:
            - WEEKLY
            - MONTHLY
            - YEARLY
        merchant_category_code:
          type: string
          description: Merchant category restriction, when applicable.
          example: '5732'
        preferred_merchant_name:
          type: string
          description: Preferred merchant name.
        effective_until_time:
          type: string
          description: >-
            Mandate expiry, in UTC `yyyy-MM-dd HH:mm:ss`. In bind-and-sign mode,
            Clink overrides it together with the instruction expiry; read the
            effective value from the instruction.
  securitySchemes:
    PortalToken:
      type: http
      scheme: bearer
      description: >-
        Portal user token from `POST /agent/cwallet/platform/portal/tokens`.
        Reads require `portal:read`; writes require `portal:write`.

````

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