# Pix 密钥 (/zh/docs/conta-digital/pix-keys)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/get_pix_keys" title="列出 Pix 密钥" method="GET" path="/transactions/pix-keys" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/post_pix_key" title="创建 Pix 密钥" method="POST" path="/transactions/pix-keys" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/put_pix_key_default" title="设置默认密钥" method="PUT" path="/transactions/pix-keys/{pixKeyId}/default" />

  <QuickLink href="/docs/conta-digital/endpoints/pix-keys/delete_pix_key" title="删除 Pix 密钥" method="DELETE" path="/transactions/pix-keys/{pixKeyId}" />
</QuickLinks>

默认密钥用于接收收款，并在你发出的转账中标识你的账户。接收转账时，任何 `ACTIVE` 的密钥都可以。列出需要作用域 `PIX_KEY_READ`；创建、删除和更换默认密钥需要 `PIX_KEY_WRITE`。

## 创建 [#创建]

[`POST /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/post_pix_key)。账户可以创建 `EVP`（随机）和 `CNPJ` 密钥。

```json
{ "type": "EVP" }
```

```json
{ "type": "CNPJ", "key": "12345678000195" }
```

`EVP` 的密钥由银行生成：不要发送 `key`。`CNPJ` 必须传 `key`，且必须是账户持有人的 CNPJ。

响应（`201`）返回的密钥已是 `ACTIVE`。账户的第一个密钥创建时即为默认密钥。

```json
{
  "id": "cmu5k2x0a000301s6ab12cd34",
  "key": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03",
  "type": "EVP",
  "status": "ACTIVE",
  "isDefault": true,
  "createdAt": "2026-09-17T14:32:05.123Z",
  "updatedAt": "2026-09-17T14:32:05.123Z"
}
```

保存 `id`：删除和设置默认密钥的路由使用的是它，而不是密钥的值。

遇到带 `PROVIDER_UNAVAILABLE` 的 `502` 时，密钥可能已经创建。重复同样的请求：它会沿用该密钥，不会另建一个。

## 列出 [#列出]

[`GET /transactions/pix-keys`](/docs/conta-digital/endpoints/pix-keys/get_pix_keys) 返回账户的密钥，默认密钥在前，其余按从旧到新排列。每个密钥的 `status` 为 `ACTIVE`、`PENDING` 或 `REMOVED`。

## 默认密钥 [#默认密钥]

[`PUT /transactions/pix-keys/{pixKeyId}/default`](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default)，无请求体。响应（`200`）返回该密钥，此时为 `isDefault: true`。只有 `ACTIVE` 的密钥可以设为默认。

## 删除 [#删除]

[`DELETE /transactions/pix-keys/{pixKeyId}`](/docs/conta-digital/endpoints/pix-keys/delete_pix_key)。响应为 `204`，无响应体。

* 密钥会从 DICT（Pix 的密钥目录）中移除，向它付款的人将收到错误。再次创建会生成另一个密钥。
* 默认密钥不能删除。请先把另一个密钥设为默认。
* 再次删除已删除的密钥返回 `404`。

## 拒绝 [#拒绝]

| 状态  | `code`                                   | 何时                                                        |
| --- | ---------------------------------------- | --------------------------------------------------------- |
| 400 | `PIX_KEY_REQUIRED`                       | 类型不是 `EVP` 且没有 `key`。                                     |
| 400 | `PIX_KEY_RANDOM_KEY_NOT_ALLOWED`         | `EVP` 带了 `key`。                                           |
| 400 | `PIX_KEY_DOCUMENT_NOT_HOLDER`            | CPF 或 CNPJ 密钥不是账户持有人的证件号。                                 |
| 404 | `PIX_KEY_NOT_FOUND`                      | 密钥不存在、已删除或属于其他账户。                                         |
| 409 | `PIX_KEY_DUPLICATED`                     | 该密钥已在本账户中注册。                                              |
| 422 | `PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER` | 账户不能创建的类型：`CPF`、`EMAIL` 或 `PHONE`。                        |
| 422 | `PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT`     | 密钥不是 `ACTIVE`。                                            |
| 422 | `PIX_KEY_DEFAULT_CANNOT_BE_REMOVED`      | 这是默认密钥。                                                   |
| 422 | `PIX_KEY_DEFAULT_ON_PROVIDER`            | 该密钥是账户的默认密钥，即使列表中还没有显示。被拒绝后，列表会把它显示为默认密钥。删除前请先把另一个密钥设为默认。 |
| 422 | `PIX_KEY_PROVIDER_REFUSED`               | 银行拒绝了该密钥。原因在 `details.reason` 中。                          |

其他路由也会出现的账户和银行相关拒绝，见[错误代码](/docs/conta-digital/error-codes)。各路由的完整列表见[创建 Pix 密钥](/docs/conta-digital/endpoints/pix-keys/post_pix_key)、[设置默认密钥](/docs/conta-digital/endpoints/pix-keys/put_pix_key_default)和[删除 Pix 密钥](/docs/conta-digital/endpoints/pix-keys/delete_pix_key)。