Criação de Ativo — Duplicata
Endpoint para inserir um ativo do tipo Duplicata em um lote de cessão. Existem dois subtipos aceitos: Duplicata Mercantil (duplicata_mercantil) — vinculada a uma nota fiscal de venda de mercadorias — e Duplicata de Serviços (duplicata_servicos) — vinculada a uma nota fiscal de prestação de serviços.
Ambos os tipos utilizam a mesma estrutura de request body. A principal diferença é que a duplicata mercantil não exige envio de documentos após a elegibilidade, enquanto a duplicata de serviços exige. Consulte a página de Inserção de Documentos para mais detalhes.
Este é o 2º passo do fluxo de cessão. Antes, você deve ter criado o lote. Após inserir os ativos, envie os documentos exigidos e encerre a inserção.
O campo external_id do direito creditório deve ser único para cada ativo e não deve ser confundido com o external_id do lote.
Request
{
"asset_type": "duplicata_mercantil",
"total_purchase_value": 1231.21,
"discounted_credit_right": {
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"originator_document_number": "46.282.154/0001-14",
"maturity_date": "2023-12-10",
"order_number": "18923619954796912",
"face_value": 1023.01,
"person_type": "natural_person",
"borrower": {
"name": "Natália Nascimento",
"document_number": "805.359.140-08",
"person_type": "natural_person",
"email": "natália.nascimento@yopmail.com",
"address": {
"street": "Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"postal_code": "05425-020",
"uf": "SP",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "36360268"
},
"natural_person": {
"mother_name": "Lívia Santos",
"birthdate": "2001-01-05"
}
},
"participant_control_number": "ICX841HWCPUGU4U101XPLDW8D",
"bankslip": {
"our_number": {
"number": 2,
"digit": "P"
}
},
"delay": {
"fine": {
"fine_type": "percentage",
"percentage_value": 0.0
},
"interest": {
"method": "pre_fixed",
"pre_fixed": {
"daily_rate": 0.0,
"calendar_base": "calendar_360"
}
}
},
"invoice": {
"access_key": "69037229347091328617032722238810300308237163",
"total_value": 1231.21,
"serie": "123",
"number": "958431587",
"issue_date": "2023-10-10"
}
}
}
Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
asset_type | string | obrigatório | Tipo do ativo. Valores aceitos: duplicata_mercantil ou duplicata_servicos. |
total_purchase_value | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
discounted_credit_right | object | obrigatório | Dados do direito creditório. Veja Atributos de discounted_credit_right. |
Atributos de discounted_credit_right
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
external_id | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
originator_document_number | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. |
maturity_date | string | obrigatório | Data de vencimento no formato YYYY-MM-DD. |
order_number | string | obrigatório | Número do pedido. Máximo de 45 caracteres. |
face_value | number | obrigatório | Valor de face. Até 8 casas decimais. |
person_type | string | opcional | Tipo de pessoa do sacado (natural_person ou legal_person). |
borrower | object | obrigatório | Dados do sacado. Consulte os Atributos de borrower na página de Criação de Ativo — CCB. |
participant_control_number | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 50 caracteres alfanuméricos. |
bankslip | object | opcional | Dados do boleto. Veja Atributos de bankslip. |
delay | object | opcional | Dados de multa e juros por atraso. Consulte os Atributos de delay na página de Criação de Ativo — CCB. |
invoice | object | obrigatório | Dados da nota fiscal. Veja Atributos de invoice. |
Atributos de bankslip
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
our_number | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja Atributos de our_number. |
Atributos de our_number
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
number | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. |
digit | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. |
Atributos de invoice
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
access_key | string | obrigatório | Chave de acesso da nota fiscal. 44 caracteres. |
total_value | number | opcional | Valor total da nota fiscal. Até 2 casas decimais. |
serie | string | obrigatório | Número de série da nota fiscal. Máximo de 3 caracteres. |
number | string | obrigatório | Número da nota fiscal. Máximo de 50 caracteres. |
issue_date | string | obrigatório | Data de emissão no formato YYYY-MM-DD. |
Response
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"status": "pending_eligibility"
}
Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
asset_key | string | Identificador único do ativo gerado pela QI Tech (UUID). |
external_id | string | A mesma chave externa fornecida no campo external_id do discounted_credit_right. |
status | string | Status inicial do ativo. Sempre retorna pending_eligibility, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
Possíveis erros
Lote não encontrado
O assignment_external_id informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.
{
"title": "Assignment not found",
"description": "Assignment not found",
"translation": "Lote não encontrado",
"code": "TRC000018"
}
Tipo de ativo não existe
O valor informado no campo asset_type não é um tipo válido. Verifique se o tipo está correto (ex: duplicata_mercantil, duplicata_servicos).
{
"title": "Asset type does not exist",
"description": "Asset type 'invalid_asset_type' does not exist",
"translation": "Tipo do ativo 'invalid_asset_type' nao existe",
"code": "TRC000015"
}
Tipo de ativo incompatível com o lote
O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.
{
"title": "Invalid asset type configuration",
"description": "This assignment can not receive this asset type: duplicata_mercantil",
"translation": "Esse lote não pode receber esse tipo de ativo: duplicata_mercantil",
"code": "TRC000025"
}
Lote fechado para inserção
O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, reabra o lote antes de inserir novos ativos.
{
"title": "Assignment is closed",
"description": "Assignment is closed to insert new assets",
"translation": "Lote esta fechado para inserir novos ativos",
"code": "TRC000022"
}
External ID duplicado
Já existe um ativo cadastrado com o external_id informado. Cada ativo deve ter um identificador único. Gere um novo external_id e tente novamente.
{
"title": "Already Exist This External Id",
"description": "Already exist an asset with this External Id",
"translation": "Ja existe um ativo com esse External Id",
"code": "TRC000054"
}
Próximos passos
Após inserir o ativo, o fluxo continua com:
- Envio dos documentos — envie a documentação exigida para cada ativo aprovado na elegibilidade.
- Encerramento da inserção — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.