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.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Lotes
Cedente	`assignor-api`	Escrita

URL base de cada host: Ambientes (Hosts).

Diferença entre os tipos

Ambos os tipos utilizam a mesma estrutura de request body. As diferenças: na duplicata mercantil, a chave de acesso da NF-e é obrigatória e, após a elegibilidade, o documento da duplicata é gerado pela QI Tech a partir desses dados; na duplicata de serviços, a chave é opcional e os documentos exigidos são os definidos na configuração de cessão. Consulte a página de Inserção de Documentos para mais detalhes.

Onde estou no fluxo?

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.

Atenção

O campo external_id do direito creditório identifica o ativo dentro do lote e não deve ser confundido com o external_id do lote.

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset

MÉTODO

POST

Request Body
{
    "asset_type": "duplicata_mercantil",
    "total_purchase_value": 1231.21,
    "discounted_credit_right": {
        "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
        "originator_document_number": "22.333.444/0001-81",
        "maturity_date": "2023-12-10",
        "order_number": "18923619954796912",
        "face_value": 1023.01,
        "person_type": "natural_person",
        "borrower": {
            "name": "Natália Nascimento",
            "document_number": "969.698.790-03",
            "person_type": "natural_person",
            "email": "natalia.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": "35231011222333000181551239584315871861703272",
            "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 (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`.
`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. Sem ele, a inserção devolve `TRC000078`.
`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 25 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 — CTE.
`invoice`	object	obrigatório	Dados da nota fiscal. Veja Atributos de `invoice`. Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `contract` neste tipo de ativo (`TRC000076`).

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	condicional	Chave de acesso da NF-e, 44 caracteres. Obrigatória para `duplicata_mercantil` (`TRC000134`), e as posições 21 e 22 da chave precisam ser o modelo `55` (NF-e); outro modelo devolve `TRC000135`. Opcional para `duplicata_servicos`.
`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 9 caracteres.
`issue_date`	string	obrigatório	Data de emissão no formato `YYYY-MM-DD`.

Response

STATUS

201

Response Body
{
    "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.

Erros

Status	Código	Quando acontece
400	`QIT000001`	O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo.
404	`TRC000018`	Não existe lote com esse `assignment_external_id` nesta configuração de cessão.
400	`TRC000025`	O `asset_type` é diferente do tipo de ativo da configuração de cessão.
400	`TRC000022`	O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, reabra o lote.
400	`TRC000009`	CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física.
404	`TRC000019`	Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (Originator bond not found), o erro não se refere ao vínculo com a configuração.
400	`TRC000078`	`order_number` ausente.
400	`TRC000075`	Objeto `invoice` ausente.
400	`TRC000076`	Objeto `contract` enviado numa duplicata.
400	`TRC000134`	`invoice.access_key` ausente numa `duplicata_mercantil`.
400	`TRC000135`	`invoice.access_key` não é de uma NF-e (modelo `55` nas posições 21 e 22).
409	`TRC000054`	Já existe um ativo com esse `external_id` neste lote.
409	`TRC100026`	Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo.
400	`TRC1000xx`	A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos.

O corpo de erro segue o formato abaixo:

{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
  "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
  "code": "TRC000054"
}

Em caso de erro, reenvie a requisição. Duplicidade (TRC000054) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de consulta de ativo. Mais em Reenvio e duplicidade.

Erros de autenticação, permissão e host: veja Erros da API.

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.

Request​

Atributos do body​

Atributos de discounted_credit_right​

Atributos de bankslip​

Atributos de our_number​

Atributos de invoice​

Response​

Atributos da resposta​

Erros​

Próximos passos​