Documentos da despesa

Anexa nota fiscal, memória de cálculo e outros comprovantes a uma despesa do fundo, e lista, baixa ou cancela os documentos anexados. A expense_key vem da consulta de despesas. A nota fiscal para consolidar a despesa vai na análise de consolidação: o envio da nota só considera os documentos da análise.

A forma de anexar depende da origem da despesa (origin.origin_type):

Origem	Como anexar	Quem anexa e quando
Lançada pela gestora ou consultoria (`expense_contract`, `expense`, `reimbursement`, `rebate_fee`)	Arquivo em Base64 no corpo (`document_b64`).	Só quem lançou a despesa (`permission_type: owner`), com a despesa em `pending_submission` ou `pre_approved` e a análise de consolidação fora de revisão.
Calculada ou registrada pela QI Tech (demais origens)	Arquivo em Base64 no corpo, ou em duas etapas: a API registra o documento e devolve uma URL de envio, e você envia o arquivo direto para essa URL.	Só a gestora, e não em despesa `canceled`.

A consultoria anexa e cancela documentos das despesas que lançou. A lista e o download dos documentos da despesa são só da gestora: a consultoria vê os documentos em documents na consulta da despesa e baixa os da análise de consolidação.

Tipos de documento

`document_type`	Descrição
`invoice`	Nota fiscal
`calculation_memory`	Memória de cálculo
`contract`	Contrato
`bank_slip`	Boleto
`payment_receipt`	Comprovante de pagamento
`evidence`	Evidência
`settlement_term`	Termo de quitação
`variance_justification`	Justificativa de diferença de valor
`extra_document`	Documento adicional

Status do documento

Status	Descrição
`in_manual_analysis`	Enviado em Base64, aguardando a análise da QI Tech.
`valid`	Aceito na aprovação da despesa ou da análise.
`invalid`	Recusado pela QI Tech.
`canceled`	Cancelado.
`null`	Registrado pelo envio em duas etapas.

Anexar documento

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Lançar e Editar Despesas ou Enviar Consolidações

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/document

MÉTODO

POST

Parâmetros de caminho

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

Corpo da requisição — arquivo em Base64
{
    "name": "nfe_001234.pdf",
    "document_type": "invoice",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}

Corpo da requisição — envio em duas etapas
{
    "name": "nfe_001234.pdf",
    "document_type": "invoice"
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do documento, até 255 caracteres.
`document_type`	string	Sim	Tipo do documento. Ver tipos.
`document_b64`	string	Condicional	Conteúdo do arquivo em Base64, até 20 MB. Obrigatório nas despesas lançadas pela gestora ou consultoria. Sem ele, a API devolve a URL do envio em duas etapas.

Nenhum outro campo é aceito.

Resposta

STATUS

201

Corpo da resposta — arquivo em Base64
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "document_type": "invoice",
    "status": "in_manual_analysis"
}

Corpo da resposta — envio em duas etapas
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "document_type": "invoice",
    "status": null,
    "upload_url": {
        "url": "https://<link-temporario-de-envio>",
        "fields": {
            "key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
            "policy": "<policy>",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-credential": "<credential>",
            "x-amz-date": "20261109T120000Z",
            "x-amz-signature": "<signature>"
        }
    }
}

Campo	Tipo	Descrição
`name`	string	Nome do documento.
`document_key`	string	Chave do documento (UUID).
`expense_key`	string	Chave da despesa.
`document_type`	string	Tipo do documento.
`status`	string	`in_manual_analysis` no envio em Base64; `null` no envio em duas etapas.
`upload_url.url`	string	Só no envio em duas etapas: endereço para onde o arquivo deve ser enviado.
`upload_url.fields`	object	Só no envio em duas etapas: campos que acompanham o arquivo. Envie todos, sem alterar nomes nem valores; o conjunto exato pode variar.

Envio do arquivo em duas etapas

Faça um POST multipart/form-data para upload_url.url com:

todos os campos de upload_url.fields;
o arquivo no campo file, o último do formulário.

A URL expira em 10 minutos e aceita arquivos de até 50 MB. Essa chamada vai direto para o armazenamento, sem os cabeçalhos de autenticação da QI Tech.

import requests

upload = response_body["upload_url"]

with open("nfe_001234.pdf", "rb") as arquivo:
    resposta = requests.post(
        upload["url"],
        data=upload["fields"],
        files={"file": arquivo},
    )

resposta.raise_for_status()

Uma resposta 204 indica envio concluído. Se a URL expirar antes do envio, anexe o documento de novo para receber outra.

Listar documentos

Devolve todos os documentos da despesa, em qualquer status, sem URL de download e sem paginação. Uma expense_key que não existe na classe de fundo devolve data vazio, sem erro.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/documents

MÉTODO

GET

Corpo da resposta
{
    "data": [
        {
            "name": "nfe_001234.pdf",
            "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
            "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
            "document_type": "invoice",
            "status": "in_manual_analysis"
        }
    ]
}

Consultar documento por chave

Devolve o documento com um link temporário para baixar o arquivo.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Leitura

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/document/{document_key}

MÉTODO

GET

Corpo da resposta
{
    "name": "nfe_001234.pdf",
    "document_key": "d4e5f6a7-b8c9-4123-def4-567890abcdef",
    "expense_key": "b7f1c8e2-5a7d-4c7f-9a0e-2c3d4e5f6a7b",
    "document_type": "invoice",
    "status": "valid",
    "document_url": "https://<link-temporario-de-download>"
}

Campo	Tipo	Descrição
`document_url`	string	URL pré-assinada para baixar o arquivo, válida por 24 horas. O arquivo é servido como `application/pdf`, qualquer que seja o formato enviado. Consulte de novo para obter outra URL.

Cancelar documento

Marca como canceled um documento de uma despesa lançada por você, gestora ou consultoria (permission_type: owner). Vale com a despesa em pending_submission ou pre_approved e a análise de consolidação fora de revisão.

Disponível em

Perfil	Host	Permissão exigida
Gestora	`manager-api`	Escrita
Consultoria	`consultant-api`	Lançar e Editar Despesas ou Enviar Consolidações

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/expense/fund_class/{fund_class_key}/expense/{expense_key}/document/{document_key}

MÉTODO

DELETE

STATUS

200

O documento com status: canceled, na estrutura da lista.

Erros

Status	`code`	Quando acontece
400	`EXP000069`	A classe de fundo não é da gestora.
400	`EXP000072`	Anexo: a despesa, lançada pela gestora ou consultoria, não está em `pending_submission` nem `pre_approved`.
400	`EXP000166`	A análise de consolidação vigente está em revisão (`in_manual_analysis` ou `pending_manager_approval`).
400	`EXP000136`	`document_b64` não é Base64 válido, ou foi omitido numa despesa lançada pela gestora ou consultoria.
400	`EXP000137`	O arquivo passa de 20 MB.
400	`EXP000144`	Cancelamento: a despesa não está em `pending_submission` nem `pre_approved`.
400	`QIT000001`	Corpo inválido: falta `name` ou `document_type`, `document_type` fora da lista ou campo não previsto.
400	`QIT000011`	A consultoria tentou anexar documento a uma despesa calculada pela QI Tech.
403	`EXP000124`	A consultoria não tem vínculo ativo com o fundo. Normalmente o `consultant-api` recusa antes, com `401` (`CIT000018`).
403	`EXP000156`	Você não lançou a despesa (`permission_type` diferente de `owner`). No cancelamento, vale também para despesas calculadas pela QI Tech.
404	`EXP000010`	A `expense_key` não existe nessa classe de fundo (anexar e cancelar).
404	`EXP000072`	Anexo: a despesa, calculada pela QI Tech, está `canceled`.
404	`EXP000071`	A `document_key` não existe para essa despesa.

Exemplo
{
  "title": "Invalid Status For Expense Document",
  "description": "Cannot create an expense document on an expense in status in_provision.",
  "translation": "Nao e possivel criar um documento em uma despesa no status in_provision.",
  "code": "EXP000072"
}

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

Tipos de documento​

Status do documento​

Anexar documento​

Parâmetros de caminho​

Atributos do corpo​

Resposta​

Envio do arquivo em duas etapas​

Listar documentos​

Consultar documento por chave​

Cancelar documento​

Erros​

Tipos de documento

Status do documento

Anexar documento

Parâmetros de caminho

Atributos do corpo

Resposta

Envio do arquivo em duas etapas

Listar documentos

Consultar documento por chave

Cancelar documento

Erros