创建钱包（Wallet）

创建钱包（wallet）允许为个人或法人注册新的信用钱包。

什么是 Wallet

wallet 代表客户的账单，作为管理所有关联支付手段的集中器。重要须知：

一个 wallet = 一张账单：每个钱包对应一个特定客户（由 CPF/CNPJ 标识）的账单
多种支付手段：同一个 wallet 可以有不同的支付工具（卡片、PIX 等）
独立的工具：创建 wallet 后，需要分别创建支付工具（信用卡、额度等）
集中管理：wallet 集中管理与该客户相关的所有操作和配置

Request

ENDPOINT

/wallet

MÉTODO

POST

Request Body

{
  "owner": {
    "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
    "person_type": "natural",
    "name": "João Silva",
    "document_number": "12345678901",
    "birthdate": "1990-01-01",
    "email": "joao.silva@email.com",
    "phone": {
      "number": "99999999",
      "area_code": "11",
      "country_code": "55"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  },
  "invoice_configuration": {
    "closing_date_configuration": {
      "type": "fixed",
      "fixed_day": 15
    },
    "due_date_configuration": {
      "type": "fixed",
      "fixed_day": 20,
      "offset_months": 0
    },
    "invoice_payment_type": "bank_slip",
    "interest_base": "calendar_days",
    "monthly_interest_percentage": 2.0,
    "fine_percentage": 2.0
  },
  "limits": {
    "postpaid_credit_limit": 5000.00
  }
}

请求体参数

字段	类型	描述	字符数
`request_control_key`	uuidv4	客户使用的请求唯一识别密钥	36
`owner`	object	钱包所有者数据（个人或法人）	owner 对象
`person_key`	string	UUID v4 格式的人员唯一识别密钥	36
`invoice_configuration` *	object	账单结账和到期配置	invoice_configuration 对象
`limits` *	object	钱包信用额度	limits 对象

条件字段

owner：未发送 person_key 时为必填项
person_key：未发送 owner 时为必填项
两个字段互斥

owner 对象

个人（`person_type: "natural"`）

字段	类型	描述	字符数
`person_type` *	string	人员类型（必须为 "natural"）	-
`name` *	string	姓名	100
`document_number` *	string	CPF（仅数字）	11
`birthdate` *	string	出生日期（YYYY-MM-DD 格式）	10
`email` *	string	联系邮箱	254
`phone` *	object	联系电话	phone 对象
`address` *	object	完整地址	address 对象

法人（`person_type: "legal"`）

字段	类型	描述	字符数
`person_type` *	string	人员类型（必须为 "legal"）	-
`name` *	string	公司法定名称	100
`trading_name` *	string	公司商业名称	100
`document_number` *	string	CNPJ（仅数字）	14
`foundation_date` *	string	成立日期（YYYY-MM-DD 格式）	10
`email` *	string	联系邮箱	254
`phone` *	object	联系电话	phone 对象
`address` *	object	完整地址	address 对象
`legal_representatives` *	array	法定代表人列表（个人）	-

phone 对象

字段	类型	描述	字符数
`country_code` *	string	国家代码（DDI）	2-3
`area_code` *	string	地区代码（DDD）	2
`number` *	string	电话号码	8-9

address 对象

字段	类型	描述	字符数
`street` *	string	街道/路名	500
`number` *	string	门牌号	10
`neighborhood` *	string	街区/社区	100
`postal_code` *	string	邮政编码（仅数字）	8
`city` *	string	城市	100
`state` *	string	州（UF）	state 枚举值
`complement`	string	地址补充信息	500

state 枚举值

枚举值	描述
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	例外

invoice_configuration 对象

字段	类型	描述	字符数
`closing_date_configuration` *	object	账单结账日配置	closing_date_configuration 对象
`due_date_configuration` *	object	账单到期日配置	due_date_configuration 对象
`invoice_payment_type` *	string	账单支付类型	invoice_payment_type 枚举值
`interest_base` *	string	利息计算基础	interest_base 枚举值
`monthly_interest_percentage` *	float	逾期月利率（0-100）	-
`fine_percentage` *	float	逾期罚款比例（0-100）	-

closing_date_configuration 对象

固定配置（`type: "fixed"`）

字段	类型	描述	字符数
`type` *	string	配置类型（必须为 "fixed"）	-
`fixed_day` *	integer	每月固定结账日（1-27）	-

基于规则的配置（`type: "rule_based"`）

字段	类型	描述	字符数
`type` *	string	配置类型（必须为 "rule_based"）	-
`rule` *	object	日期计算规则	rule 对象（closing_date_configuration）

rule 对象（closing_date_configuration）

字段	类型	描述	字符数
`day_of_week` *	string	星期几	day_of_week 枚举值
`occurrence` *	string	当月第几次出现	occurrence 枚举值
`fallback_strategy` *	string	非工作日策略	fallback_strategy 枚举值

due_date_configuration 对象

固定配置（`type: "fixed"`）

字段	类型	描述	字符数
`type` *	string	配置类型（必须为 "fixed"）	-
`offset_months` *	integer	从结账日起的月份偏移量	-
`fixed_day` *	integer	每月固定到期日（2-27）	-

基于规则的配置（`type: "rule_based"`）

字段	类型	描述	字符数
`type` *	string	配置类型（必须为 "rule_based"）	-
`offset_months` *	integer	从结账日起的月份偏移量	-
`rule` *	object	日期计算规则	rule 对象（closing_date_configuration）

rule 对象（due_date_configuration）

字段	类型	描述	字符数
`day_of_week` *	string	星期几	day_of_week 枚举值
`occurrence` *	string	当月第几次出现	occurrence 枚举值
`fallback_strategy` *	string	非工作日策略	fallback_strategy 枚举值

日期验证

到期日必须至少在结账日后 2 天
对于基于规则的配置，结账和到期的星期几之间必须至少相差一天（例如：周一结账，周三到期）

day_of_week 枚举值

枚举值	描述
monday	星期一
tuesday	星期二
wednesday	星期三
thursday	星期四
friday	星期五
saturday	星期六
sunday	星期日

occurrence 枚举值

枚举值	描述
first	第一次出现
second	第二次出现
third	第三次出现
fourth	第四次出现
last	最后一次出现

fallback_strategy 枚举值

枚举值	描述
next_business_day	下一个工作日
previous_business_day	上一个工作日
same_day	当天

invoice_payment_type 枚举值

枚举值	描述
bank_slip	银行票据（Boleto bancário）

interest_base 枚举值

枚举值	描述
calendar_days	自然日

limits 对象

字段	类型	描述	字符数
`postpaid_credit_limit` *	float	后付费信用额度	-

Response

成功 - 钱包已创建，等待分析

STATUS

202

Response Body：等待分析的钱包

{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": null,
  "wallet_status": "pending_analysis"
}

说明

若返回 HTTP Status 202 且 wallet_status 字段值为 pending_analysis，则创建将异步处理。之后将发送 webhook 通知钱包是否通过 KYC 分析审批或被拒绝。有关 webhook 的更多详情，请参阅 webhook 文档

说明

对于需要 KYC 分析的情况，owner_person_key 字段在初始响应中将返回为 null。钱包的持有人仅在 KYC 流程结束且获得批准后才会在系统中创建。此时，人员密钥将通过审批 webhook 发送，请参阅 webhook 文档

成功 - 钱包已创建并激活

STATUS

201

Response Body：已激活的钱包

{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "wallet_status": "active"
}

响应体参数

字段	类型	描述	字符数
`wallet_key` *	uuidv4	uuid v4 格式的钱包唯一识别密钥	36
`owner_person_key` *	string	钱包所有者的识别密钥	36
`wallet_status` *	string	钱包状态	-

wallet_status 枚举值

枚举值	描述
pending_analysis	等待 KYC 分析的钱包
active	已激活且可使用的钱包
rejected	已拒绝的钱包

钱包状态

pending_analysis：当钱包以完整所有者数据创建时返回，将进行 KYC 分析。
active：当钱包以现有人员密钥创建时返回，可立即使用。

错误响应

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP 代码 `status`	QI 代码 `code`	标题 `title`	描述（英文） `description`	描述（葡文） `translation`
400	QIT000001	Bad Request	Schema Error	Schema Inválido
404	CIN000020	Requester not Found	No requester configuration found for requester key: 8e1e6b46-beb3-467b-965c-6c545707d467	Solicitante não encontrado para requester key: 8e1e6b46-beb3-467b-965c-6c545707d467
404	CIN000062	Not Found	Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff	Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff
409	CIN000043	Conflict	Active wallet found	Carteira ativa já existe
400	CIN000063	Bad Request	Expiration date too close to closing date	Data de vencimento muito próxima da data de fechamento
400	CIN000064	Bad Request	Invalid offset months for rule-based configuration	Meses de offset inválidos para configuração baseada em regras
400	CIN000065	Bad Request	Weekdays too close for rule-based configuration	Dias da semana muito próximos para configuração baseada em regras
400	CIN000002	Bad Request	Invalid signer document number	Número do documento do signatário inválido
400	CIN000066	Bad Request	Error while creating wallet in card service	Erro ao criar carteira no serviço de cartão
409	CIN000099	Conflict	Request control key already exists.	Request control key já existe.

Request​

请求体参数​

owner 对象​

个人（person_type: "natural"）​

法人（person_type: "legal"）​

phone 对象​

address 对象​

state 枚举值​

invoice_configuration 对象​

closing_date_configuration 对象​

固定配置（type: "fixed"）​

基于规则的配置（type: "rule_based"）​

rule 对象（closing_date_configuration）​

due_date_configuration 对象​

固定配置（type: "fixed"）​

基于规则的配置（type: "rule_based"）​

rule 对象（due_date_configuration）​

day_of_week 枚举值​

occurrence 枚举值​

fallback_strategy 枚举值​

invoice_payment_type 枚举值​

interest_base 枚举值​

limits 对象​

Response​

成功 - 钱包已创建，等待分析​

成功 - 钱包已创建并激活​

响应体参数​

wallet_status 枚举值​

错误响应​

Request

请求体参数

owner 对象

个人（`person_type: "natural"`）

法人（`person_type: "legal"`）

phone 对象

address 对象

state 枚举值

invoice_configuration 对象

closing_date_configuration 对象

固定配置（`type: "fixed"`）

基于规则的配置（`type: "rule_based"`）

rule 对象（closing_date_configuration）

due_date_configuration 对象

固定配置（`type: "fixed"`）

基于规则的配置（`type: "rule_based"`）

rule 对象（due_date_configuration）

day_of_week 枚举值

occurrence 枚举值

fallback_strategy 枚举值

invoice_payment_type 枚举值

interest_base 枚举值

limits 对象

Response

成功 - 钱包已创建，等待分析

成功 - 钱包已创建并激活

响应体参数

wallet_status 枚举值

错误响应