Criar carteira

Importante

Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.

As carteiras de boleto possuem um código de identificação único (requester_profile_code) e configurações padrão específicas de pagamento, baixa, protesto etc. do boleto. Uma mesma conta pode ter várias carteiras de boleto, o que permite ao usuário criar várias carteiras com configurações padrão diferente. Tal dinâmica facilita a geração de boletos, com diferentes configurações, de maneira mais ágil e automática.

Informação

Para todas as contas, é criada uma carteira de boletos com as configurações padrão do cliente. Esse padrão de configurações pode ser alterado entrando em contato com nosso suporte (suporte.baas@qitech.com.br). Após a criação da conta, é possível alterar também as tarifas da conta utilizando o endpoint de configuração de tarifas.

Atenção!

A criação de carteiras de boletos é um fluxo assíncrono. Após a aprovação/rejeição da criação da carteira pela CIP/Nuclea, o solicitante será notificado via webhook sobre o resultado de tal solicitação.

Request

ENDPOINT

/account/ACCOUNT_KEY/requester_profile

MÉTODO

POST

Path parameters

Campo	Tipo	Descrição	Caracteres
`account_key`	uuidv4	Chave única de identificação da conta, no formato 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
    }
  }
}

Request Body Params

Campo	Tipo	Descrição	Caracteres
`request_control_key` *	uuidv4	Chave única de identificação da request utilizada pelo cliente no formato uuid v4	36
`configuration_data` *	object	Configurações padrão da carteira	Objeto configuration_data

Objeto configuration_data

Campo	Tipo	Descrição	Caracteres
`max_payment_days` *	integer	Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365)	-
`write_off_settings`	object	Configuração padrão de baixa	Objeto write_off_settings
`protest_settings`	object	Configuração padrão de protesto	Objeto protest_settings
`bankruptcy_protest_settings`	object	Configuração padrão de protesto falimentar	Objeto bankruptcy_protest_settings
`fine_settings`	object	Configuração padrão de multa	Objeto fine_setings
`interest_settings`	object	Configuração padrão de juros	Objeto interest_settings
`qr_code_settings`	object	Configuração padrão de QR Code PIX (para bolePix)	Objeto qr_code_settings

Objeto write_off_settings

Campo	Tipo	Descrição	Caracteres
`days_to_write_off` *	integer	Dias, após o vencimento, para que o boleto seja baixado automaticamente	-

Objeto protest_settings

Campo	Tipo	Descrição	Caracteres
`days_to_protest` *	integer	Dias, após o vencimento, para que o boleto seja protestado automaticamente	-

Objeto bankruptcy_protest_settings

Campo	Tipo	Descrição	Caracteres
`days_to_bankruptcy_protest` *	integer	Dias, após o vencimento, para que seja iniciado um processo de protesto falimentar automaticamente	-

Objeto fine_settings

Opção 1: multa em valor absoluto (fine_type=absolute)

Campo	Tipo	Descrição	Caracteres
`fine_type` *	string	Tipo da multa	Enumeradores fine_type
`fine_amount` *	float	Valor absoluto da multa	-
`days_to_fine` *	integer	Dias, após o vencimento, para que a multa seja cobrada	-

Opção 2: multa em valor percentual (fine_type=percentage)

Campo	Tipo	Descrição	Caracteres
`fine_type` *	string	Tipo da multa	Enumeradores fine_type
`fine_percentage` *	integer	Valor percentual da multa, de 1 a 100	-
`days_to_fine` *	integer	Dias, após o vencimento, para que a multa seja cobrada	-

Enumeradores fine_type

Enumerador	Descrição
absolute	valor absoluto
percentage	valor percentual

Objeto interest_settings

Opção 1: juros utilizando valores absolutos (interest_type=calendar_days_daily_amount ou interest_type=workdays_daily_amount)

Campo	Tipo	Descrição	Caracteres
`interest_type` *	string	Tipo de juros	Enumeradores interest_type
`interest_amount` *	float	Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos)	-
`days_to_interest` *	integer	Dias, após o vencimento, para que comece a cobrar os juros	-

Opção 2: juros utilizando valores percentuais (interest_type=calendar_days_monthly_percentage)

Campo	Tipo	Descrição	Caracteres
`interest_type` *	string	Tipo de juros	Enumeradores interest_type
`interest_percentage` *	integer	Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)	-
`days_to_interest` *	integer	Dias, após o vencimento, para que comece a cobrar os juros	-

Enumeradores interest_type

Enumerador	Descrição
calendar_days_daily_amount	Valor diário sobre dias corridos
workdays_daily_amount	Valor diário sobre dias úteis
calendar_days_monthly_percentage	Porcentagem de juros cobrados mensalmente, com base em dias corridos

Objeto qr_code_settings

Campo	Tipo	Descrição	Caracteres
`pix_key` *	uuidv4	Chave Pix do tipo aleatória	36
`qr_code_on_discharge_enabled` *	boolean	Determina se as informações do QR Code constarão no arquivo retorno (CNAB)	-

Informação

O PIX copia e cola será retornado no arquivo CNAB na posição 029 a 105.

Atenção!

Caso o objeto qr_code_settings seja enviado na request, essa carteira terá como configuração padrão a geração de bolePix. BolePix são boletos cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento dos boletos tanto utilizando as linhas digitáveis dos mesmos, quanto através da leitura dos QR Codes Pix vinculados. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente. Já em relação às notificações, são enviados dois webhooks: um no ato da transferência PIX (aviso de pagamento, boleto vai para o status payment_notice); e outro alguns segundos ou minutos depois, após a confirmação da baixa na CIP/Nuclea (pago, boleto vai para o status paid).

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
    }
  }
}

Response Body Params

Campo	Tipo	Descrição	Caracteres
`requester_profile_key` *	uuidv4	Chave única de identificação da carteira no formato uuid v4	36
`requester_profile_code` *	string	Código único de identificação da carteira	19
`request_control_key` *	uuidv4	Chave única de identificação da request utilizada pelo cliente no formato uuid v4	36
`account_key` *	uuidv4	Chave única de identificação da conta no formato uuid v4	36
`requester_profile_status` *	string	Status da carteira	Enumeradores requester_profile_status
`configuration_data` *	object	Configurações padrão da carteira	Objeto configuration_data

Enumeradores profile_status

Enumerador	Descrição
pending	Carteira aceita e pendente de confirmação

Error Response

STATUS

4xx

Response Body: Error

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

Código HTTP `status`	Código QI `code`	Título `title`	Descrição (eng) `description`	Descrição (pt-br) `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.

Criar carteira

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​

Response​

Response Body Params​

Enumeradores profile_status​

Error Response​