Criação de Ativo — CCB

Endpoint para inserir um ativo do tipo CCB (Cédula de Crédito Bancário) em um lote de cessão. Cada ativo representa uma operação de crédito que será cedida ao fundo. O mesmo contrato vale para structured_cci.

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).

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 da operação de crédito 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": "ccb",
    "total_purchase_value": 1351.66,
    "premiums": [
      {
        "premium_type": "spread",
        "total_value": 13.38
      }
    ],
    "credit_operation": {
      "contract": {
        "number": "0008309052/NBF",
        "disbursement_date": "2023-07-06",
        "issue_date": "2023-07-06",
        "signature_date": "2023-07-06",
        "issue_value": 1338.28
      },
      "amortization_type": "sac",
      "borrower": {
        "name": "Empresa Exemplo Ltda",
        "document_number": "11.222.333/0001-81",
        "person_type": "legal_person",
        "email": "financeiro@empresaexemplo.com.br",
        "address": {
          "street": "Pátio de Teixeira",
          "number": "1",
          "neighborhood": "Estrela do Oriente",
          "city": "Rondônia",
          "postal_code": "01012-030",
          "uf": "RO",
          "country": "BRA"
        },
        "phone": {
          "area_code": "11",
          "number": "936360268"
        },
        "legal_person": {
          "activity_code": "11.11-1-11"
        }
      },
      "delay": {
        "fine": {
          "fine_type": "percentage",
          "percentage_value": 0.0
        },
        "interest": {
          "method": "compound",
          "pre_fixed": {
            "monthly_rate": 0.0,
            "calendar_base": "calendar_360"
          }
        }
      },
      "principal_value": 1338.28,
      "interest_rate_type": "pre_fixed",
      "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
      "originator_document_number": "22.333.444/0001-81",
      "pre_fixed": {
        "calendar_base": "calendar_365",
        "monthly_rate": 0.018
      },
      "installments": [
        {
          "maturity_date": "2023-10-01",
          "installment_number": 1,
          "face_value": 689.33
        },
        {
          "maturity_date": "2024-10-01",
          "installment_number": 2,
          "face_value": 482.53
        },
        {
          "maturity_date": "2025-10-01",
          "installment_number": 3,
          "face_value": 300.36
        },
        {
          "maturity_date": "2026-10-01",
          "installment_number": 4,
          "face_value": 162.77
        },
        {
          "maturity_date": "2027-10-01",
          "installment_number": 5,
          "face_value": 81.39
        },
        {
          "maturity_date": "2028-10-01",
          "installment_number": 6,
          "face_value": 40.69
        }
      ],
      "modality_code": "0202",
      "consignee": {
        "consignee_type": "inss",
        "name": "Consignee name",
        "document_number": "33.444.555/0001-81"
      },
      "collaterals": [
        {
          "collateral_type": "social_security",
          "benefit_number": "0000000000",
          "benefit_type": "benefit_type",
          "status": "reserved"
        }
      ]
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
asset_type	string	obrigatório	Tipo do ativo. Para CCB, informar ccb.
total_purchase_value	number	obrigatório	Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais.
premiums	array	opcional	Lista de ágios envolvidos na venda. Veja Atributos de premiums.
deductions	array	opcional	Lista de deságios envolvidos na venda. Veja Atributos de deductions.
credit_operation	object	obrigatório	Dados da operação de crédito. Veja Atributos de credit_operation.

Ágios e deságios entram na conferência de valor

Na inserção, a QI Tech calcula o valor presente das parcelas e o compara com o valor de compra do ativo: total_purchase_value − soma de premiums + soma de deductions. Diferenças pequenas são registradas automaticamente como ajuste (math_adjustment); acima disso, a inserção devolve TRC100014.

Atributos de premiums

Campo	Tipo	Obrigatoriedade	Descrição
premium_type	string	obrigatório	Tipo do ágio: spread, math_adjustment, banker_fee, transaction_fee ou originator_fee.
total_value	number	obrigatório	Valor total do ágio. Mínimo 0.01. Até 2 casas decimais.

Atributos de deductions

Campo	Tipo	Obrigatoriedade	Descrição
deduction_type	string	obrigatório	Tipo do deságio: bad_debt_discount ou math_adjustment.
total_value	number	obrigatório	Valor total do deságio. Mínimo 0.01. Até 2 casas decimais.

Atributos de credit_operation

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.
principal_value	number	obrigatório	Principal total em aberto da operação. Até 8 casas decimais.
contract	object	obrigatório	Dados do contrato. Veja Atributos de contract.
borrower	object	obrigatório	Dados do sacado/devedor. Veja Atributos de borrower.
amortization_type	string	obrigatório	Tipo de amortização utilizado no cálculo.
interest_rate_type	string	obrigatório	Tipo de juros da operação.
pre_fixed	object	condicional	Dados do cálculo da parte pré-fixada. Obrigatório quando interest_rate_type for pre_fixed. Veja Atributos de pre_fixed.
post_fixed	object	condicional	Dados do cálculo da parte pós-fixada. Obrigatório quando interest_rate_type for post_fixed. Veja Atributos de post_fixed.
installments	array	obrigatório	Lista de parcelas da operação. Veja Atributos de installments.
delay	object	obrigatório	Dados de multa e juros por atraso. Veja Atributos de delay.
modality_code	string	opcional	Código de 4 dígitos que especifica a categoria ou tipo de operação financeira associada ao ativo. Quando omitido, vale o da configuração de cessão.
b3_code	string	opcional	Código do ativo na B3. Até 50 caracteres. Só é aceito quando a configuração de cessão usa registro registry_transfer, deferred_registry ou external_registry; nas demais, devolve TRC000188.
b3_self_code	string	opcional	Código próprio do ativo na B3. Até 50 caracteres. Mesma regra de b3_code.
consignee	object	opcional	Dados do ente consignante. Veja Atributos de consignee.
collaterals	array	opcional	Lista de garantias associadas à operação. Veja Atributos de collaterals.

Enumeradores de amortization_type:

Valor	Descrição
sac	Amortização do tipo SAC.
price	Amortização do tipo Price.
price_days	Amortização do tipo Price com juros calculados por dias corridos.

Enumeradores de interest_rate_type:

Valor	Descrição
pre_fixed	Para operações pré-fixadas. Informe o objeto pre_fixed.
post_fixed	Para operações pós-fixadas. Informe o objeto post_fixed.

Atributos de contract

Campo	Tipo	Obrigatoriedade	Descrição
number	string	obrigatório	Número do contrato. Máximo de 50 caracteres.
disbursement_date	string	obrigatório	Data de desembolso no formato YYYY-MM-DD.
issue_date	string	obrigatório	Data de emissão no formato YYYY-MM-DD.
signature_date	string	opcional	Data de assinatura do contrato no formato YYYY-MM-DD.
issue_value	number	obrigatório	Valor de emissão do contrato. Até 2 casas decimais.

Atributos de borrower

Campo	Tipo	Obrigatoriedade	Descrição
name	string	obrigatório	Nome do sacado. Máximo de 255 caracteres.
document_number	string	obrigatório	CPF ou CNPJ do sacado.
person_type	string	obrigatório	Tipo de pessoa.
email	string	opcional	E-mail do sacado. Máximo de 255 caracteres.
address	object	opcional	Endereço do sacado. Veja Atributos de address.
phone	object	opcional	Telefone do sacado. Veja Atributos de phone.

Enumeradores de person_type:

Valor	Descrição
natural_person	Pessoa Física. O CPF em document_number tem o dígito verificador conferido. Quando informado, incluir o objeto natural_person dentro de borrower. Veja Atributos de natural_person.
legal_person	Pessoa Jurídica. Quando informado, incluir o objeto legal_person dentro de borrower. Veja Atributos de legal_person.

Atributos de address

Campo	Tipo	Obrigatoriedade	Descrição
street	string	opcional	Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres.
number	string	opcional	Número do endereço. Máximo de 40 caracteres.
neighborhood	string	opcional	Bairro. Máximo de 255 caracteres.
city	string	opcional	Cidade. Máximo de 255 caracteres.
uf	string	opcional	Sigla do estado, em maiúsculas (ex.: SP).
complement	string	opcional	Complemento. Máximo de 255 caracteres.
postal_code	string	obrigatório	CEP no formato 00000-000. Obrigatório sempre que o objeto address for informado.
country	string	opcional	País no formato ISO 3166-1 alpha-3. 3 caracteres.

Atributos de phone

Campo	Tipo	Obrigatoriedade	Descrição
area_code	string	obrigatório	Código de área (DDD). 2 dígitos.
number	string	obrigatório	Número de telefone. 8 ou 9 dígitos.
international_dial_code	string	opcional	Código internacional (DDI). Até 3 caracteres.

Atributos de natural_person

Campo	Tipo	Obrigatoriedade	Descrição
birthdate	string	opcional	Data de nascimento no formato YYYY-MM-DD.
gender	string	opcional	Gênero.
mother_name	string	opcional	Nome da mãe. Máximo de 255 caracteres.

Enumeradores de gender:

Valor	Descrição
male	Masculino.
female	Feminino.

Atributos de legal_person

Campo	Tipo	Obrigatoriedade	Descrição
foundation_date	string	opcional	Data de fundação no formato YYYY-MM-DD.
activity_code	string	opcional	Código de atividade (CNAE) no formato 11.11-1-11.
annual_revenues	integer	opcional	Receita anual em centavos.
representatives	array	opcional	Lista de representantes legais. Veja Atributos de representatives.

Atributos de representatives

Campo	Tipo	Obrigatoriedade	Descrição
name	string	obrigatório	Nome do representante. Máximo de 255 caracteres.
document_number	string	obrigatório	CPF ou CNPJ do representante.
email	string	obrigatório	E-mail do representante. Máximo de 255 caracteres.
phone	object	obrigatório	Telefone. Mesma estrutura de Atributos de phone.
address	object	obrigatório	Endereço. Mesma estrutura de Atributos de address.
person_type	string	opcional	Tipo de pessoa (natural_person ou legal_person).
representative_type	string	opcional	Tipo do representante. Máximo de 50 caracteres.

Atributos de pre_fixed

Campo	Tipo	Obrigatoriedade	Descrição
calendar_base	string	obrigatório	Base de cálculo utilizada.
monthly_rate	number	obrigatório	Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1%, informar 0.01. Até 8 casas decimais.
nominal_monthly_rate	number	opcional	Taxa mensal nominal do contrato, no mesmo formato de monthly_rate.

Enumeradores de calendar_base:

Valor	Descrição
workdays	Base de cálculo em dias úteis (252).
calendar_365	Base de cálculo em 365 dias.
calendar_360	Base de cálculo em 360 dias.

Atributos de post_fixed

Campo	Tipo	Obrigatoriedade	Descrição
calendar_base	string	obrigatório	Base de contagem de dias da correção. Mesmos enumeradores de calendar_base.
indexer	string	obrigatório	Índice que corrige a operação: di, selic ou ipca.
rate	number	obrigatório	Taxa aplicada sobre o indexador. Para 100% do DI, informar 1.
lag	object	obrigatório	Defasagem do índice: reference (daily ou monthly) e amount (quantidade). Para usar o índice de dois meses antes, informar {"reference": "monthly", "amount": 2}.

Atributos de installments

Campo	Tipo	Obrigatoriedade	Descrição
maturity_date	string	obrigatório	Data de vencimento da parcela no formato YYYY-MM-DD.
installment_number	integer	obrigatório	Número da parcela.
face_value	number	obrigatório	Valor de face da parcela. Até 8 casas decimais.
principal_value	number	opcional	Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais.
external_id	string	opcional	Identificador da parcela no seu sistema.

Atributos de delay

Campo	Tipo	Obrigatoriedade	Descrição
fine	object	obrigatório	Dados da multa por atraso. Veja Atributos de fine. Sem multa, envie fine_type percentage com percentage_value 0.
interest	object	obrigatório	Dados do juros de mora. Veja Atributos de interest. Sem juros de mora, envie monthly_rate 0.

Atributos de fine

Campo	Tipo	Obrigatoriedade	Descrição
fine_type	string	obrigatório	Tipo da multa.
percentage_value	number	condicional	Valor da multa quando fine_type for percentage. De 0 a 1, representando 0% a 100%. Até 2 casas decimais.
amount	number	condicional	Valor fixo da multa quando fine_type for fixed. Até 2 casas decimais.

Enumeradores de fine_type:

Valor	Descrição
percentage	Multa percentual sobre o valor da parcela.
fixed	Valor fixo de multa.

Atributos de interest

Campo	Tipo	Obrigatoriedade	Descrição
method	string	obrigatório	Método do juros de mora.
pre_fixed	object	obrigatório	Taxa do juros de mora: calendar_base e monthly_rate ou daily_rate. Não aceita nominal_monthly_rate. Veja Atributos de pre_fixed do juros de mora.

Enumeradores de method:

Valor	Descrição
compound	Juros de mora composto.
simple	Juros de mora simples.
pre_fixed	Juros de mora pré-fixado.

Atributos de consignee

Campo	Tipo	Obrigatoriedade	Descrição
name	string	opcional	Nome do ente consignante. Máximo de 255 caracteres.
document_number	string	obrigatório	CPF ou CNPJ do ente consignante.
consignee_type	string	obrigatório	Tipo de consignado.

Enumeradores de consignee_type:

Valor	Descrição
public	Consignado público.
private	Consignado privado.
inss	Consignado INSS.

Atributos de collaterals

Campo	Tipo	Obrigatoriedade	Descrição
collateral_type	string	obrigatório	Tipo de garantia.

Como montar collaterals

collaterals é uma lista e cada item representa uma garantia. O collateral_type determina quais campos aquele item aceita — os campos de um tipo não são aceitos em outro. Qualquer propriedade fora do conjunto do tipo informado é recusada com QIT000001.

Enumeradores de collateral_type:

Valor	Descrição
fgts	Garantia de FGTS. Incluir os campos de Atributos de garantia FGTS.
social_security	Garantia de INSS. Incluir os campos de Atributos de garantia INSS.
home_equity	Garantia de imóveis. Incluir os campos de Atributos de garantia imóvel.
vehicle	Garantia de veículo. Incluir os campos de Atributos de garantia veículo.

Atributos de garantia FGTS

Campo	Tipo	Obrigatoriedade	Descrição
protocol_number	string	obrigatório	Número do protocolo.
status	string	obrigatório	Status da garantia.

Atributos de garantia INSS

Campo	Tipo	Obrigatoriedade	Descrição
benefit_number	string	obrigatório	Número do benefício.
benefit_type	string	obrigatório	Tipo do benefício.
status	string	obrigatório	Status da garantia.

Atributos de garantia imóvel

Campo	Tipo	Obrigatoriedade	Descrição
enterprise_name	string	obrigatório	Nome do empreendimento.
registration_number	string	obrigatório	Número do registro do imóvel.
enterprise_document_number	string	opcional	CPF ou CNPJ associado ao empreendimento.
collateral_properties	array	obrigatório	Lista de propriedades do imóvel. Veja Atributos de collateral_properties.

Atributos de collateral_properties

Campo	Tipo	Obrigatoriedade	Descrição
address	object	obrigatório	Endereço do imóvel. Mesma estrutura de Atributos de address.
total_collateral_value	number	obrigatório	Valor do imóvel. Até 8 casas decimais.

Atributos de garantia veículo

Campo	Tipo	Obrigatoriedade	Descrição
vehicle_loan_value	number	opcional	Valor financiado do veículo. Não pode ser negativo.
vehicle_total_market_value	number	opcional	Valor de mercado total do veículo. Não pode ser negativo.
vehicle_identification	object	obrigatório	Identificação do veículo. Veja Atributos de vehicle_identification.

Exemplo de garantia de veículo

{
  "collateral_type": "vehicle",
  "vehicle_loan_value": 30000.00,
  "vehicle_total_market_value": 55000.00,
  "vehicle_identification": {
    "brand": "Toyota",
    "model": "Corolla XEi 2.0",
    "manufacturing_year": 2022,
    "chassis_number": "9BRBLWHEXK0123456",
    "license_plate": "ABC1D23",
    "renavam": "12345678901"
  }
}

Atributos de vehicle_identification

Campo	Tipo	Obrigatoriedade	Descrição
brand	string	opcional	Marca do veículo.
model	string	obrigatório	Modelo do veículo.
manufacturing_year	integer	obrigatório	Ano de fabricação do veículo. Mínimo 1900.
chassis_number	string	obrigatório	Número do chassi do veículo.
license_plate	string	opcional	Placa do veículo.
renavam	string	opcional	Código RENAVAM do veículo.

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 da credit_operation.
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.
404	TRC000015	O asset_type não existe.
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	TRC000188	b3_code ou b3_self_code enviados numa configuração cujo tipo de registro não os aceita.
409	TRC000054	Já existe um ativo com esse external_id neste lote.
400	TRC100014	O valor presente do fluxo de parcelas não bate com o valor de compra (total_purchase_value, ágios e deságios).
400	TRC100004 / TRC100005	Parcelas sem numeração sequencial ou fora de ordem crescente de vencimento.
400	TRC100009	issue_value menor que o principal da operação.
409	TRC100017	O fundo não pode comprar ativos vencidos.

Os códigos TRC1000xx vêm da validação financeira do ativo, feita na inserção. 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:

1. Envio dos documentos — envie a documentação exigida para cada ativo aprovado na elegibilidade.
2. Encerramento da inserção — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.