Criação de Ativo — CTE

Endpoint para inserir um ativo do tipo CTE (Conhecimento de Transporte Eletrônico) em um lote de cessão. O CTE é um documento fiscal eletrônico que comprova a prestação de serviço de transporte, utilizado como direito creditório na operação de cessão.

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 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": "cte",
    "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": "legal_person",
        "borrower": {
            "name": "Transportadora Exemplo Ltda",
            "document_number": "46.282.154/0001-14",
            "person_type": "legal_person",
            "email": "contato@transportadora.com.br",
            "address": {
                "street": "Avenida Paulista",
                "number": "1000",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "postal_code": "01310-100",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "936360268"
            },
            "legal_person": {
                "activity_code": "49.30-2-01"
            }
        },
        "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": "35231146282154000114570000000001189236199547",
            "total_value": 1231.21,
            "serie": "001",
            "number": "958431587",
            "issue_date": "2023-10-10"
        }
    }
}

Atributos do body

Campo	Tipo	Obrigatoriedade	Descrição
asset_type	string	obrigatório	Tipo do ativo. Para CTE, informar cte.
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.
invoice	object	obrigatório	Dados do CT-e. Veja Atributos de invoice.
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. Veja Atributos de delay.

Atributos de invoice

Campo	Tipo	Obrigatoriedade	Descrição
access_key	string	obrigatório	Chave de acesso do CT-e. 44 caracteres. Os caracteres de posição 20 a 22 devem corresponder ao modelo do documento (57 ou 67).
total_value	number	opcional	Valor total do CT-e. Até 2 casas decimais.
serie	string	obrigatório	Número de série do CT-e. Máximo de 3 caracteres.
number	string	obrigatório	Número do CT-e. Máximo de 9 caracteres.
issue_date	string	obrigatório	Data de emissão no formato YYYY-MM-DD.

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 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 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. Veja Atributos de pre_fixed.

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 pre_fixed

Campo	Tipo	Obrigatoriedade	Descrição
daily_rate	number	condicional	Taxa diária. Informar quando method for pre_fixed. Para 1%, informar 0.01. Até 8 casas decimais.
calendar_base	string	obrigatório	Base de cálculo utilizada.

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.

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.

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

{
  "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: cte",
  "translation": "Esse lote não pode receber esse tipo de ativo: cte",
  "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

Chave de acesso do CT-e ausente

O campo access_key dentro de invoice é obrigatório para ativos do tipo cte. Inclua a chave de acesso do CT-e no request body.

{
  "title": "Access Key Required",
  "description": "Access key is required for cte asset type",
  "translation": "Chave de acesso é obrigatória para o tipo de ativo cte",
  "code": "TRC000134"
}

STATUS

400

Chave de acesso do CT-e inválida

A access_key informada não corresponde a um CT-e válido. Os caracteres de posição 20 a 22 da chave de acesso devem ser 57 ou 67, que identificam o modelo do documento fiscal CT-e.

{
  "title": "Invalid CTE Access Key",
  "description": "Access key is not valid for a CTE document",
  "translation": "Chave de acesso não é válida para um documento CT-e",
  "code": "TRC000133"
}

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.