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.