PIX 密钥

列出与 API Key 关联账户中已注册的 PIX 密钥。

端点

GET /api/external/pix/keys

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
X-Key-Case	String	否	设为 camelCase 以使用 camelCase 接收响应字段（默认 snake_case）

示例

curl -X GET https://api.owem.com.br/api/external/pix/keys \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

成功响应 (200)

{
  "worked": true,
  "keys": [
    {
      "key": "12345678901",
      "key_type": "cpf",
      "status": "active",
      "created_at": "2026-02-05T12:00:00Z"
    },
    {
      "key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "key_type": "evp",
      "status": "active",
      "created_at": "2026-02-10T14:30:00Z"
    },
    {
      "key": "contato@empresa.com.br",
      "key_type": "email",
      "status": "active",
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}

字段	类型	描述
worked	Boolean	true 表示操作成功
keys	Array	账户的 PIX 密钥列表,按 inserted_at ASC 排序（从最旧到最新）。注：当 PIX IN 收款（POST /pix/cash-in）不带 pix_key 参数生成时,后端内部使用账户最新（DESC）的 active 密钥 -- 与此端点的顺序不同。
keys[].key	String	PIX 密钥值
keys[].key_type	String	小写的密钥类型（见下表）
keys[].status	String	密钥当前状态（见下表）
keys[].created_at	String	注册日期（UTC 的 ISO 8601）

无分页

此端点在单个响应中返回账户的所有密钥（PF 账户最多 5 个密钥,PJ 账户最多 20 个）。没有 limit、offset、page 或 per_page 参数 -- 发送这些参数会被静默忽略。

密钥类型

类型	格式	示例
cpf	11 位数字	12345678901
cnpj	14 位数字	12345678000190
email	有效电子邮件	contato@empresa.com.br
phone	区号 + 号码（11 位数字）	11999998888
evp	UUID v4（随机密钥）	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

密钥状态

数据库 schema 只接受 status 的两个值：

状态	描述
active	密钥已激活并可操作 -- 可以接收 PIX 并作为 POST /pix/cash-in 中的 pix_key 使用
pending	在 DICT 中处理注册（密钥创建流程已开始但 BACEN 尚未确认）

显示的密钥

端点返回与账户关联的所有密钥（无论状态）。如果您只想要可操作的密钥,请在客户端按 status === "active" 过滤。

携号转移与申诉

携号转移不是密钥状态。携号转移（从其他机构转入密钥）和申诉（质疑所有权）是单独的工作流,仅在 merchant portal 或通过管理面板提供 -- 外部 API 未公开。

错误响应 (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

外部 API 为只读

此端点仅列出现有密钥。注册、携号转移、申诉和删除 PIX 密钥仅通过 merchant portal（merchant.owem.com.br）或管理面板完成 -- 这些操作没有外部端点。

关于限制的信息（由后端管理,API 未公开）：PF 账户最多 5 个密钥,PJ 账户最多 20 个,每账户 1 个 CPF/CNPJ 密钥。