Contratos estruturados
Os contratos estruturados levam ao fundo operações em que o fundo é parte do contrato: ele financia o cedente, ou recebe do sacado uma confissão da dívida. Cada operação tem documentos próprios, que as partes assinam, e passa por duas validações antes de entrar na carteira: a do lastro de cada contrato e a análise do lote inteiro.
Para recebíveis padronizados que o cedente já tem (duplicatas, CT-e, cheques, CCB, contratos parcelados com os clientes dele), use a cessão de direitos creditórios. A comparação completa entre os dois caminhos está em Qual ativo enviar.
Tipos de contrato
| Tipo | asset_type | O que é | Pagamento ao cedente |
|---|---|---|---|
| Contrato de financiamento | financing_contract | O fundo financia o cedente, que recebe o valor numa conta dele, e o devedor paga as parcelas ao fundo. É o formato do fomento mercantil e do financiamento de pedidos de compra: além do contrato, a operação pode trazer o pedido de compra que ela financia. | Obrigatório: o desembolso é informado na criação do lote. |
| Confissão de dívida | debt_acknowledgment | O sacado reconhece por escrito uma dívida que já tem com o fundo, vinda de ativos cedidos antes (duplicatas, CCB, contratos), e assume um novo cronograma de parcelas. Os ativos antigos são liquidados por substituição e a confissão entra no lugar deles. É o instrumento usual para renegociar atrasos; assinada pelo devedor e por duas testemunhas, é título executivo extrajudicial (CPC, art. 784, III). | Não há: a operação troca ativos que o fundo já tem. |
| Contrato | contract | Outro contrato parcelado em que o fundo é parte. | Opcional: só quando o lote informa um desembolso. |
O tipo vem da configuração de contrato: cada configuração tem um tipo, e o lote só aceita contratos desse tipo. As configurações do fundo estão em Configurações e consultas. Para criar uma, fale com o time de integração.
Disponível em
| Perfil | Host | O que pode fazer |
|---|---|---|
| Gestora | manager-api | Tudo, inclusive aprovar o lote, abrir pendências e validar documentos. Leitura exige a permissão de Leitura; o resto, a de Escrita. |
| Consultoria | consultant-api | Operar os lotes das configurações vinculadas a ela: permissões Ler contratos e Operar contratos no fundo. |
| Cedente | assignor-api | Operar os próprios lotes. Leitura exige a permissão de Leitura; o resto, a de Escrita. |
Todos os endpoints começam em /trade_contract/fund_class/{fund_class_key}. URL base de cada host: Ambientes (Hosts).
assignment_keyDiferente da cessão de recebíveis, aqui as chamadas do lote usam a assignment_key, o UUID devolvido na criação, e não o seu external_id. Guarde a assignment_key assim que criar o lote.
Fluxo
Configuração, cedente e, no contrato de financiamento, o desembolso.
/trade_contract/fund_class/{fund_class_key}/assignmentUm contrato por chamada, com as parcelas. Cada um é precificado na hora.
.../assignment/{assignment_key}/contract.../assignment/{assignment_key}A QI Tech gera os documentos dos modelos da configuração; você envia os que são seus.
.../assignment/{assignment_key}/documentCada documento enviado é conferido. Um documento recusado recusa o lote.
Ver documentação →Aprova, recusa ou abre pendências para você responder.
.../assignment/{assignment_key}/approvalLastro recusado, lote reprovado, assinatura recusada ou CNAB divergente.
Você dispara; todas as partes assinam, inclusive a administradora pelo fundo.
.../assignment/{assignment_key}/signatureQuando a configuração exige, a QI Tech confere o CNAB. Com desembolso, paga o cedente.
Os contratos entram na carteira do fundo. Na confissão, os ativos substituídos são liquidados.
Passo a passo
- Crie o lote na configuração de contrato, informando o cedente e, no contrato de financiamento, o desembolso.
- Insira os contratos, um por chamada. Cada contrato é precificado na inserção: se o preço não fecha, a chamada é recusada na hora.
- Encerre a inserção. A QI Tech calcula a taxa e o prazo médio do lote.
- Envie os documentos: peça a geração dos documentos que vêm dos modelos da configuração e envie os seus (o contrato assinado, o pedido de compra).
- Envie o lote para análise quando todo o lastro estiver validado. Se você não enviar, a QI Tech envia sozinha assim que o lastro fica pronto. Responda às pendências, se houver.
- Dispare a assinatura depois da aprovação.
- Acompanhe o lote até
active. O fim do fluxo é automático: confirmação de CNAB (quando a configuração exige), desembolso e inclusão na carteira.
Até o envio dos documentos, o lote pode ser cancelado.
A dupla validação
| 1ª — lastro de cada contrato | 2ª — análise do lote | |
|---|---|---|
| O que se confere | Cada documento enviado por você, contra os dados do contrato | A operação inteira: contratos, preço, documentos e partes |
| Quem decide | A validação de lastro da QI Tech; a gestora também pode validar ou recusar um documento | A administradora; a gestora também pode decidir pela API |
| Status do lote | pending_asset_documents | pending_administrator_analysis e, com pendência aberta, pending_annotation |
| Se recusar | O lote vai para rejected | O lote vai para rejected, ou volta para você com uma pendência |
Os documentos gerados pela QI Tech a partir dos modelos da configuração não passam pela primeira validação: eles já nascem com os dados do contrato.
Status do lote
| Status | Significado | Quem age |
|---|---|---|
pending_assets_insertion | Lote criado, recebendo contratos | Você |
pending_documents | Inserção encerrada, aguardando os documentos | Você |
pending_asset_documents | Documentos chegando e em validação | QI Tech, ou você, se faltar documento |
pending_administrator_analysis | Lastro pronto, lote em análise | Administradora ou gestora |
pending_annotation | Pendência aberta na análise | Você responde |
pending_signature | Aprovado, aguardando a assinatura | Você dispara; as partes assinam |
pending_cnab_confirmation | Assinado, aguardando a conferência do CNAB (só quando a configuração exige) | QI Tech |
pending_disbursement | Aguardando o pagamento ao cedente | QI Tech |
pending_wallet_inclusion | Contratos entrando na carteira | QI Tech |
active | Contratos na carteira do fundo | — |
rejected | Recusado; o motivo está em status_events | — |
canceled | Cancelado por você | — |
Os contratos têm status próprio: pending_wallet_inclusion, sending_to_wallet, active ou failed. Um contrato recusado pela carteira recusa o lote.
Os contratos estruturados ainda não enviam webhooks. Acompanhe o lote pela consulta do lote, que traz o status atual, o histórico em status_events e o que falta em expected_documents. Consulte em intervalos de minutos, não de segundos.
Erros
Os erros seguem o formato de Erros da API, com title, description, translation e code. Os códigos TRC desta seção são próprios dos contratos estruturados: o mesmo número pode ter outro significado na cessão de recebíveis. Cada página lista os códigos dela.
Não use dados reais de pessoas físicas ou jurídicas em sandbox.