Criação do contrato

Cria um contrato de despesa entre o fundo e um fornecedor. O contrato começa em pending_submission. Depois, envie o documento e envie o contrato para análise.

Criar contrato

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Criar Contratos de Despesa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract

MÉTODO

POST

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`fund_class_key`	string	Chave da classe de fundo (UUID).

Corpo da requisição
{
    "name": "Contrato de auditoria 2027",
    "vendor_key": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
    "signature_method": "certifiqi",
    "expense_types": [
        {
            "expense_type": "audit_tax"
        }
    ],
    "recurrences": [
        {
            "expense_type": "audit_tax",
            "description": "Auditoria anual - parcela mensal",
            "amount": 2500.00,
            "start_date": "2027-01-01",
            "end_date": "2027-12-31"
        }
    ],
    "expiration_date": "2027-12-31"
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do contrato, de 1 a 255 caracteres.
`vendor_key`	string	Sim	Chave do fornecedor, 36 caracteres.
`signature_method`	string	Sim	`certifiqi` ou `qi_sign`: assinatura eletrônica pela QI Tech. `external`: o documento enviado já está assinado. Ver Assinatura do contrato.
`expense_types`	array	Sim	Tipos de despesa do contrato, sem repetição. Cada item tem só `expense_type`. Ver tipos aceitos.
`expense_types[].expense_type`	string	Sim	Tipo de despesa.
`recurrences`	array	Não	Despesas mensais automáticas, consultadas em Despesas recorrentes. Se enviado, precisa ter exatamente um item para cada tipo de `expense_types`.
`recurrences[].expense_type`	string	Sim	Tipo de despesa da recorrência.
`recurrences[].description`	string	Sim	Descrição das despesas geradas, de 1 a 200 caracteres.
`recurrences[].amount`	number	Sim	Valor mensal, maior que zero.
`recurrences[].start_date`	string	Sim	Início, `YYYY-MM-DD`.
`recurrences[].end_date`	string	Sim	Fim, `YYYY-MM-DD`, ou `null` para recorrência sem fim. Não pode ser anterior a `start_date`.
`expiration_date`	string	Não	Vencimento do contrato, `YYYY-MM-DD`, ou `null`. Se não for informado, a leitura automática preenche com a data encontrada no documento.

Campos fora desta tabela são recusados com QIT000001.

Resposta

STATUS

201

Corpo da resposta
{
    "contract_key": "3f2b8c1e-7d4a-4e9b-9a61-0c5d2e8f4b17",
    "name": "Contrato de auditoria 2027",
    "status": "pending_submission",
    "fund_class_key": "9a7c3d52-1b8e-4f0a-8c2d-6e4b1f9a0d33",
    "fund_class": {
        "fund_class_key": "9a7c3d52-1b8e-4f0a-8c2d-6e4b1f9a0d33",
        "name": "FIDC EXEMPLO",
        "document_number": "33.444.555/0001-81",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c"
    },
    "vendor": {
        "vendor_key": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "44.555.666/0001-81",
        "status": "registered",
        "agent_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c"
    },
    "consultant_key": null,
    "signature_method": "certifiqi",
    "expiration_date": "2027-12-31",
    "ai_analysis": null,
    "reproval_reason": null,
    "reproval_details": null,
    "amended_contract_key": null,
    "root_contract_key": null,
    "created_at": "2026-11-09T14:03:22.512345",
    "expense_types": [
        {
            "expense_type": "audit_tax",
            "sub_class_key": null
        }
    ],
    "parametrizations": [
        {
            "parametrization_key": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
            "expense_type": "audit_tax",
            "sub_class_key": null,
            "status": "pending",
            "target": "recurring_expense",
            "external_configuration_key": null,
            "configuration_data": {
                "expense_type": "audit_tax",
                "description": "Auditoria anual - parcela mensal",
                "amount": 2500.0,
                "start_date": "2027-01-01",
                "end_date": "2027-12-31"
            }
        }
    ],
    "attachments": [],
    "terminations": []
}

Atributos do contrato

Campo	Tipo	Descrição
`contract_key`	string	Chave do contrato (UUID).
`name`	string	Nome do contrato.
`status`	string	Status. Ver status do contrato.
`fund_class_key`	string	Chave da classe de fundo.
`fund_class`	object	`fund_class_key`, `name`, `document_number`, `manager_key`.
`vendor`	object	`vendor_key`, `name`, `document_number`, `status` e `agent_key` (dono do fornecedor). `status` é `created`, `pending_analysis`, `registered` (fornecedor aprovado), `inactive` ou `expired`.
`consultant_key`	string	Consultoria que lançou o contrato, ou `null`.
`signature_method`	string	`certifiqi`, `qi_sign` ou `external`. `null` nos contratos criados pela QI Tech na estruturação do fundo.
`expiration_date`	string	Vencimento, `YYYY-MM-DD`, ou `null`.
`ai_analysis`	object	Última leitura automática do documento: `ai_analysis_key`, `status` (`sent`, `valid`, `inconclusive` ou `failed`) e `analysis_result` (dados lidos do documento, ou `null`). É `null` antes do envio para análise.
`reproval_reason`	string	Motivo da reprovação, ou `null`. Ver motivos.
`reproval_details`	string	Detalhe da reprovação, até 1000 caracteres, ou `null`.
`amended_contract_key`	string	Se o contrato é um aditivo, o contrato que ele substitui. Senão, `null`.
`root_contract_key`	string	Contrato original da cadeia de aditivos, ou `null`.
`created_at`	string	Criação, ISO 8601 sem fuso.
`expense_types`	array	`expense_type` e `sub_class_key` (sempre `null` em contratos criados pela API).
`parametrizations`	array	Recorrências do contrato: `parametrization_key`, `expense_type`, `sub_class_key`, `status`, `target`, `external_configuration_key` e `configuration_data` (a recorrência enviada). Ver os valores de `status` e `target` abaixo.
`attachments`	array	Anexos: `attachment_key`, `status`, `created_at`. Ver Anexos.
`terminations`	array	Pedidos de distrato: `termination_key`, `status`, `termination_details`, `reproval_details`, `created_at`. Ver Distrato.

parametrizations[].status:

pending: o contrato ainda não entrou em vigor.
active: o contrato está em vigor.
inactive: o contrato foi cancelado, reprovado, substituído ou venceu.
canceled: a recorrência foi removida na edição.

parametrizations[].target é recurring_expense. Contratos da estruturação do fundo trazem também quota_fee, performance_fee e expense_control.

Erros

Status	`code`	Quando acontece
400	`QIT000001`	Corpo inválido: campo obrigatório ausente, tipo repetido em `expense_types`, valor fora da lista ou campo não previsto.
400	`ECT000040`	`expiration_date` não é uma data válida, como `2027-02-30`.
400	`ECT000012`	O tipo de despesa é contratado na estruturação do fundo: `administration_tax`, `management_tax`, `performance_fee` ou `credit_rights_registration_fee`.
400	`ECT000010`	O tipo de despesa não existe ou não usa contrato. Ver tipos aceitos.
400	`ECT000061`	Uma recorrência tem `end_date` anterior a `start_date`.
400	`ECT000045`	`recurrences` não tem exatamente uma recorrência para cada tipo declarado.
404	`ECT000005`	A classe de fundo não existe ou você não tem acesso a ela.
404	`ECT000008`	O fornecedor não existe, ou não é da gestora nem de uma consultoria com a permissão Criar Contratos de Despesa no fundo.
409	`ECT000015`	O fornecedor está `inactive`.
409	`ECT000059`	O cadastro do fornecedor venceu (`expired`).
409	`ECT000014`	O tipo de despesa já está em outro contrato em andamento, `active` ou `expired` deste fundo com este fornecedor. A mensagem cita `sub class None`, porque contratos criados pela API não têm subclasse.
409	`ECT000029`	Um contrato deste fundo com este fornecedor foi reprovado em definitivo pelo compliance. Não é possível criar outro contrato entre os dois.

Exemplo
{
  "title": "Expense type already contracted",
  "description": "The expense type audit_tax for the sub class None is already in another open, active or expired contract of this fund class and vendor.",
  "translation": "O tipo de despesa audit_tax da sub-classe None ja esta em outro contrato em andamento, ativo ou expirado deste fundo e fornecedor.",
  "code": "ECT000014"
}

Erros de autenticação, permissão e host: veja Erros da API.

Próximo passo

Documento do contrato: obtenha a URL de envio e envie o PDF.

Criar contrato​

Parâmetros de caminho​

Atributos do corpo​

Resposta​

Atributos do contrato​

Erros​

Próximo passo​