创建钱包

重要

要登记 bolePix，账户中必须存在一个有效的随机 PIX 密钥，票据将在该账户中登记。

票据钱包具有唯一识别码（requester_profile_code）以及票据支付、核销、抗议等特定默认配置。同一账户可拥有多个票据钱包，允许用户创建具有不同默认配置的多个钱包。这种机制简化了票据的生成，使不同配置的票据可以更快速、自动地生成。

信息

所有账户在创建时都会自动生成一个带有客户默认配置的票据钱包。该默认配置可通过联系我们的支持团队（suporte.baas@qitech.com.br）进行更改。账户创建后，也可以使用费率配置端点修改账户费率。

注意！

钱包创建是异步流程。在 CIP/Núclea 批准或拒绝钱包创建后，申请人将通过 webhook 收到相关结果通知。

Request

ENDPOINT

/account/ACCOUNT_KEY/requester_profile

MÉTODO

POST

Path parameters

字段	类型	描述	字符数
`account_key`	uuidv4	账户唯一标识键，uuid v4 格式	36

Request Body

{
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}

Request Body Params

字段	类型	描述	字符数
`request_control_key` *	uuidv4	客户使用的请求唯一标识键，uuid v4 格式	36
`configuration_data` *	object	钱包默认配置	Objeto configuration_data

Objeto configuration_data

字段	类型	描述	字符数
`max_payment_days` *	integer	票据到期后可供付款的最大日历天数（最多 365 天）	-
`write_off_settings`	object	默认核销配置	Objeto write_off_settings
`protest_settings`	object	默认抗议配置	Objeto protest_settings
`bankruptcy_protest_settings`	object	默认破产抗议配置	Objeto bankruptcy_protest_settings
`fine_settings`	object	默认罚款配置	Objeto fine_setings
`interest_settings`	object	默认利息配置	Objeto interest_settings
`qr_code_settings`	object	PIX QR Code 默认配置（用于 bolePix）	Objeto qr_code_settings
`cnab_settings`	object	CNAB 文件默认配置	Objeto cnab_settings

Objeto write_off_settings

字段	类型	描述	字符数
`days_to_write_off` *	integer	到期后自动核销票据的天数	-

Objeto protest_settings

字段	类型	描述	字符数
`days_to_protest` *	integer	到期后自动抗议票据的天数	-

Objeto bankruptcy_protest_settings

字段	类型	描述	字符数
`days_to_bankruptcy_protest` *	integer	到期后自动启动破产抗议流程的天数	-

Objeto fine_settings

选项 1：绝对值罚款（fine_type=absolute）

字段	类型	描述	字符数
`fine_type` *	string	罚款类型	Enumeradores fine_type
`fine_amount` *	float	罚款绝对值	-
`days_to_fine` *	integer	到期后开始收取罚款的天数	-

选项 2：百分比罚款（fine_type=percentage）

字段	类型	描述	字符数
`fine_type` *	string	罚款类型	Enumeradores fine_type
`fine_percentage` *	integer	罚款百分比值，1 到 100	-
`days_to_fine` *	integer	到期后开始收取罚款的天数	-

Enumeradores fine_type

枚举值	描述
absolute	绝对值
percentage	百分比值

Objeto interest_settings

选项 1：使用绝对值利息（interest_type=calendar_days_daily_amount 或 interest_type=workdays_daily_amount）

字段	类型	描述	字符数
`interest_type` *	string	利息类型	Enumeradores interest_type
`interest_amount` *	float	按指定时间单位（工作日或日历日）收取的金额	-
`days_to_interest` *	integer	到期后开始收取利息的天数	-

选项 2：使用百分比利息（interest_type=calendar_days_monthly_percentage）

字段	类型	描述	字符数
`interest_type` *	string	利息类型	Enumeradores interest_type
`interest_percentage` *	integer	按指定时间单位（工作日或日历日）收取的百分比	-
`days_to_interest` *	integer	到期后开始收取利息的天数	-

Enumeradores interest_type

枚举值	描述
calendar_days_daily_amount	基于日历日的每日金额
workdays_daily_amount	基于工作日的每日金额
calendar_days_monthly_percentage	基于日历日按月收取的利息百分比

Objeto qr_code_settings

字段	类型	描述	字符数
`pix_key` *	uuidv4	随机类型的 PIX 密钥	36
`qr_code_on_discharge_enabled` *	boolean	确定 QR Code 信息是否包含在退款文件（CNAB）中	-

信息

PIX 复制粘贴将在 CNAB 文件的第 029 至 105 位置返回。

注意！

若在请求中发送 qr_code_settings 对象，该钱包将以生成 bolePix 作为默认配置。bolePix 是一种支付与 PIX QR Code 绑定的票据。因此，付款人可以通过票据的可输入行或扫描绑定的 PIX QR Code 进行支付。若通过 QR Code 支付，财务清算将即时完成。关于通知，将发送两个 webhook：一个在 PIX 转账时（支付通知，票据转为 payment_notice 状态）；另一个在 CIP/Núclea 确认核销后几秒或几分钟后（已支付，票据转为 paid 状态）。

Objeto cnab_settings

字段	类型	描述	字符数
`default_bank`	string	处理 CNAB 文件的默认银行布局	Enumeradores default_bank
`preferred_layout`	string	CNAB 文件首选布局	Enumeradores preferred_layout

Enumeradores default_bank

枚举值	描述
santander	Banco Santander
itau	Banco Itaú
bradesco	Banco Bradesco
qi_scd	QI SCD

Enumeradores preferred_layout

枚举值	描述
400	CNAB 400 布局
240	CNAB 240 布局

Response

STATUS

202

Response Body

{
  "requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
  "requester_profile_code": "329-04-2338-2625918",
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
  "requester_profile_status": "pending",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}

Response Body Params

字段	类型	描述	字符数
`requester_profile_key` *	uuidv4	钱包唯一标识键，uuid v4 格式	36
`requester_profile_code` *	string	钱包唯一识别码	19
`request_control_key` *	uuidv4	客户使用的请求唯一标识键，uuid v4 格式	36
`account_key` *	uuidv4	账户唯一标识键，uuid v4 格式	36
`requester_profile_status` *	string	钱包状态	Enumeradores requester_profile_status
`configuration_data` *	object	钱包默认配置	Objeto configuration_data

Enumeradores profile_status

枚举值	描述
pending	钱包已接受，等待确认

Error Response

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	BKS000001	Not Found	Person not found with key: person_key`	Pessoa não encontrada com a chave: person_key`
404	BKS000004	Not Found	Pix key not found: `{pix_key}`	Chave pix não encontrada: `{pix_key}`
403	BKS000005	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BKS000006	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BKS000007	Bad Request	It was not possible to consult the source account at this time. Please try again in a few minutes.	Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400	BKS000008	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BKS000009	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
403	BKS000010	Forbidden	The pix key owner does not match the account owner.	O proprietário da chave pix não corresponde ao proprietário da conta.
409	BKS000014	Conflict	Request control key already sent or duplicated sent: `{request_control_key}`	Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`
400	BKS000047	Bad Request	It was not possible to consult the sent pix key at this time. Please try again in a few minutes.	Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.

Request​

Path parameters​

Request Body Params​

Objeto configuration_data​

Objeto write_off_settings​

Objeto protest_settings​

Objeto bankruptcy_protest_settings​

Objeto fine_settings​

Enumeradores fine_type​

Objeto interest_settings​

Enumeradores interest_type​

Objeto qr_code_settings​

Objeto cnab_settings​

Enumeradores default_bank​

Enumeradores preferred_layout​

Response​

Response Body Params​

Enumeradores profile_status​

Error Response​