Compressão gzip

A API QTrust usa gzip para reduzir o tráfego dos arquivos enviados na integração. A compressão aqui funciona de um jeito específico, que costuma causar confusão — vale ler antes de implementar.

1. O gzip vai no campo, não no `Content-Encoding`

⚠️ Não use o header Content-Encoding: gzip. O corpo da requisição é sempre um JSON em texto puro. O que está comprimido é o conteúdo de um campo desse JSON, entregue como texto Base64.

A regra é:

campo = base64( gzip( arquivo ) )

Isso mantém o corpo legível e depurável (você consegue ver FileName, MovementDate etc.) enquanto o arquivo, que é a parte pesada, viaja comprimido.

2. Onde a compressão é obrigatória

Método	Caminho	Campo comprimido
`POST`	`/v1/import-bank-return/`	`ReturnFileGzip`

Nenhum outro endpoint REST exige compressão. Os endpoints SOAP seguem outra regra — veja a seção 6.

3. Como montar a requisição

Três passos:

Leia o arquivo de retorno bancário (.txt ou .ret) como bytes.

Comprima esses bytes em gzip.

Codifique o resultado em Base64 e coloque a string no campo ReturnFileGzip.

Corpo resultante:

{
  "FileName": "RETORNO_20260910.ret",
  "MovementDate": "2026-09-10",
  "ReturnFileGzip": "H4sIAAAAAAAAA+3BAQ0AAADCoPdPbQ8HFAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA",
  "Regularizar": false
}

Campo	Obrigatório	Observação
`FileName`	Sim	Somente as extensões `.txt` e `.ret` são aceitas
`ReturnFileGzip`	Sim	`base64(gzip(arquivo))`
`MovementDate`	Não	Ausente, assume-se o último dia útil. Aceita `yyyy-MM-dd`, `dd/MM/yyyy` ou `ddMMyyyy`. Data futura é rejeitada
`Regularizar`	Não	Padrão `false`. Indica se as ocorrências devem ser regularizadas no processamento

Lembre que este endpoint exige Authorization: Basic e não aceita os headers username/password.

4. Exemplos

cURL

Como o campo precisa ir dentro de um JSON, o caminho mais simples é gerar o corpo antes:

C#

💡 No GZipStream, o Base64 só fica correto depois que o stream é fechado — é o Dispose que grava o rodapé do gzip. Por isso o using interno fecha antes do ToArray(). Ler o MemoryStream com o GZipStream ainda aberto produz um arquivo truncado, e o QTrust responde "Não foi possível descompactar o arquivo".

Python

5. Limites e tratamentos do servidor

Regra	Detalhe
Tamanho descompactado	Máximo de 10 MB. Acima disso a resposta é `400` com `ValidationError` e a mensagem "O arquivo descompactado excede o tamanho máximo permitido de 10 MB." O limite vale para o conteúdo depois de descomprimir, não para o Base64 enviado
Quebras de linha	Normalizadas para CRLF pelo servidor. Se a sua origem gera o arquivo com LF (comum em pipelines Linux), não precisa converter antes
Conteúdo inválido	Base64 quebrado, bytes que não são gzip ou gzip corrompido resultam em `400` com "Não foi possível descompactar o arquivo..."
Campo vazio	`ReturnFileGzip` ausente ou vazio resulta em `400` com `ValidationError`

Note que o CNPJ do fundo não vai no corpo: ele é lido do próprio arquivo de retorno, no campo do beneficiário. Se o CNPJ não puder ser lido, ou não corresponder a um fundo cadastrado, a resposta é 400.

Resposta de sucesso

{
  "success": true,
  "message": "Arquivo de retorno enviado para processamento.",
  "dataMovimento": "2026-09-10"
}

6. Não confunda: os endpoints SOAP usam ZIP, não gzip

A importação de remessa CNAB (POST /soap/importacaoArquivoCnab) não usa gzip. Nela o elemento arquivo do envelope recebe um arquivo ZIP, de duas formas possíveis:

Base64 direto — o conteúdo do ZIP codificado no próprio elemento; ou

referência MTOM — o elemento traz cid:... e o ZIP vem como anexo multipart/related.

Regras do ZIP: ele deve conter exatamente um arquivo .REM. Nenhum .REM ou mais de um resultam em ValidationError.

Resumindo as duas famílias:

Integração	Formato do arquivo	Como viaja
Retorno bancário (REST)	gzip	Base64 no campo `ReturnFileGzip` do JSON
Remessa CNAB (SOAP)	ZIP com um `.REM`	Base64 no elemento `arquivo`, ou anexo MTOM via `cid:`

7. Notas para ferramentas de teste

No Postman, Insomnia ou Apidog, gere o Base64 em um script de pré-requisição — colar o conteúdo binário do arquivo direto no campo não funciona.

Não marque a opção de compressão automática do corpo na ferramenta. Ela adicionaria Content-Encoding: gzip e comprimiria o JSON inteiro, que não é o que a API espera.

Para validar rapidamente o que você gerou, o caminho inverso deve devolver o arquivo original:

Compressão gzip

1. O gzip vai no campo, não no Content-Encoding#

2. Onde a compressão é obrigatória#

3. Como montar a requisição#

4. Exemplos#

cURL#

C##

Python#

5. Limites e tratamentos do servidor#

Resposta de sucesso#

6. Não confunda: os endpoints SOAP usam ZIP, não gzip#

7. Notas para ferramentas de teste#