Documentos do lote de contratos
Cada configuração de contrato define os documentos da operação. Alguns a QI Tech gera a partir de modelos, com os dados do lote e dos contratos; outros você envia, e eles passam pela validação de lastro, a primeira das duas validações. O lote só segue para a análise quando todos os documentos exigidos estão prontos.
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Escrita (leitura no download) |
| Consultoria | consultant-api | Operar contratos (Ler contratos no download) |
| Cedente | assignor-api | Escrita (leitura no download) |
URL base de cada host: Ambientes (Hosts).
Este é o 4º passo, depois do encerramento da inserção. Em seguida, envie o lote para análise.
O que a configuração exige
A consulta do lote traz em expected_documents a lista do que a configuração exige, e em documents o que já existe:
source | validation_type | Quem produz | O que acontece |
|---|---|---|---|
generated | internal | QI Tech | Gerado já validado. |
generated | internal_signature | QI Tech | Gerado e assinado pelas partes na assinatura. |
upload | external_signature | Você | Validado contra os dados do contrato e assinado pelas partes. |
upload | external_upload | Você | Validado contra os dados do contrato. |
upload | received_signed | Você | Recebido já assinado; não passa por validação. |
Quando per_contract é true, o documento é exigido para cada contrato do lote.
Tipos de documento (document_type):
| Valor | Documento |
|---|---|
financing_contract | Contrato de financiamento |
debt_acknowledgment_contract | Instrumento de confissão de dívida |
contract | Contrato |
purchase_order | Pedido de compra |
assignment_term | Termo de cessão |
Gerar os documentos
Gera, de uma vez, todos os documentos dos modelos da configuração. O lote precisa estar em pending_documents e passa a pending_asset_documents.
Sem body.
{
"assignment_key": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"documents_created": 2,
"status": "pending_asset_documents"
}
A geração é assíncrona: os documentos aparecem na consulta do lote com status generated e passam a validated (ou ficam prontos para assinatura) quando o arquivo fica pronto.
Enviar um documento
Envia um documento de lastro. Aceito com o lote em pending_documents ou pending_asset_documents; o primeiro envio também leva o lote a pending_asset_documents.
{
"document_type": "purchase_order",
"document_b64": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI+PgpzdHJlYW0K...",
"contract_external_id": "FIN-2026-000147-01"
}
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
document_type | string | obrigatório | Um dos tipos da tabela acima. Tipos gerados pela QI Tech são recusados (TRC000042). |
document_b64 | string | obrigatório | Arquivo em Base64. |
contract_external_id | string | condicional | external_id do contrato a que o documento pertence, até 50 caracteres. Obrigatório nos documentos validados contra o contrato (external_signature e external_upload) (TRC000057). |
{
"document_key": "3c2b1a09-8f7e-4d6c-b5a4-938271605f4e",
"status": "pending_validation",
"asset_documents_key": "b8a7c6d5-e4f3-4a2b-9c1d-0e8f7a6b5c4d"
}
status | Significado |
|---|---|
pending_validation | Em validação de lastro. O resultado aparece na consulta do lote: validated ou rejected. |
uploaded | Recebido; não passa por validação. |
signed | Recebido já assinado (received_signed). |
Se a validação recusar um documento, o lote vai para rejected com o motivo asset_documents. Confira o documento antes de enviar: um contrato com valores diferentes dos informados na inserção é o motivo mais comum.
Enviar um documento adicional
Anexa ao lote um documento que a configuração não exige, como uma procuração ou um comprovante. Não passa por validação nem muda o status do lote. Aceito em qualquer status, exceto canceled e rejected.
{
"document_b64": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI+PgpzdHJlYW0K...",
"contract_external_id": "FIN-2026-000147-01"
}
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
document_b64 | string | obrigatório | Arquivo em Base64. |
contract_external_id | string | opcional | Contrato a que o documento se refere, até 50 caracteres. |
{
"document_key": "6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2918",
"status": "uploaded"
}
Baixar um documento gerado
Devolve um link temporário para o arquivo de um documento gerado pela QI Tech: a minuta, o termo, o contrato assinado. Os documentos que você enviou não são baixados por aqui (TRC000065).
{
"document_key": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"document_type": "financing_contract",
"validation_type": "internal_signature",
"status": "signed",
"contract_key": "e7d6c5b4-a3f2-4e1d-9c0b-8a7f6e5d4c3b",
"file_url": "https://...",
"expires_in": 900
}
O file_url vale por expires_in segundos (15 minutos). Peça um novo quando expirar.
Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | QIT000001 | O body não segue o formato. |
| 404 | TRC000011 | Não existe lote com essa assignment_key neste fundo. |
| 409 | TRC000012 | O lote não está num status que aceita a operação. |
| 400 | TRC000019 | A configuração não tem modelos ativos para gerar. Fale com o time de integração. |
| 400 | TRC000038 | Falta um dado exigido pelo modelo do documento. A description diz qual. |
| 400 | TRC000018 | Contrato de financiamento com purchase_order_value maior que total_value. |
| 400 | TRC000042 | O tipo de documento é gerado pela QI Tech e não pode ser enviado. |
| 400 | TRC000057 | Documento validado contra o contrato sem contract_external_id. |
| 400 | TRC000056 | A configuração não tem validação de lastro para documentos enviados. Fale com o time de integração. |
| 404 | TRC000015 | Não existe documento com essa document_key no lote. |
| 404 | TRC000064 | O arquivo ainda não está pronto. Tente de novo em alguns instantes. |
| 409 | TRC000065 | O documento foi enviado por você; o arquivo não é baixado por esta rota. |
| 403 | QIT000004 / QIT000005 / QIT000008 | A integração não tem acesso a este lote. |