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.

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 deve ser único para cada ativo 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": "QI CTVM",
        "document_number": "19.845.976/0001-93",
        "person_type": "legal_person",
        "email": "qidtvm@qitech.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": "75.723.105/0001-78",
      "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": "11.620.231/3105-71"
      },
      "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. Informação apenas para visualização posterior — não é utilizada em cálculos.
credit_operation	object	obrigatório	Dados da operação de crédito. Veja Atributos de credit_operation.

Atributos de premiums

Campo	Tipo	Obrigatoriedade	Descrição
premium_type	string	obrigatório	Tipo do ágio.
total_value	number	obrigatório	Valor total do ágio. Até 2 casas decimais.

Enumeradores de premium_type:

Valor	Descrição
spread	Spread vinculado à originação e emissão do crédito.

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 do originador/consultor que viabilizou a operação.
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	obrigatório	Dados do cálculo da parte pré-fixada. Veja Atributos de pre_fixed.
installments	array	obrigatório	Lista de parcelas da operação. Veja Atributos de installments.
delay	object	opcional	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.
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.

Enumeradores de interest_rate_type:

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

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	obrigatório	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. 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	obrigatório	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. 2 caracteres.
complement	string	opcional	Complemento. Máximo de 255 caracteres.
postal_code	string	obrigatório	CEP. 9 caracteres (com hífen).
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. Até 9 dígitos.

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	obrigatório	Código de atividade 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	opcional	E-mail do representante. Máximo de 255 caracteres.
phone	object	opcional	Telefone. Mesma estrutura de Atributos de phone.
address	object	opcional	Endereço. Mesma estrutura de Atributos de address.
person_type	string	obrigatório	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. Para 1%, informar 0.01. Até 8 casas decimais.

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

Atributos de delay

Campo	Tipo	Obrigatoriedade	Descrição
fine	object	opcional	Dados da multa por atraso. Veja Atributos de fine.
interest	object	opcional	Dados do juros de mora. Veja Atributos de interest.

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	Dados da taxa pré-fixada. Mesma estrutura de Atributos de pre_fixed.

Enumeradores de method:

Valor	Descrição
compound	Juros de mora composto.
simple	Juros de mora simples.

Atributos de consignee

Campo	Tipo	Obrigatoriedade	Descrição
name	string	obrigatório	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.

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.

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.

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.

Possíveis erros

STATUS

404

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

STATUS

404

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: ccb, duplicata_mercantil, discounted_contract).

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

STATUS

400

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: ccb",
  "translation": "Esse lote não pode receber esse tipo de ativo: ccb",
  "code": "TRC000025"
}

STATUS

400

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

STATUS

400

Número de documento inválido

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos document_number, originator_document_number e demais campos de documento no request body.

{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}

STATUS

400

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:

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.