API para comprimir PDF: como chamar por HTTP com curl

A API do AjustaPDF recebe um PDF por POST em multipart, no campo file, no endereço https://api.ajustapdf.com/pdf/compress, com o nível no campo level (leve, media ou forte). A resposta é o próprio PDF comprimido, pronto para salvar. Não há chave de API: as chamadas usam a cota do plano sem conta, então ela serve para testes e uso leve.

Primeira chamada com curl

O comando abaixo envia um arquivo, pede o nível médio e salva a resposta em outro arquivo. Use a opção -f: sem ela, uma resposta de erro em JSON também é gravada no arquivo de saída, e você pode achar que o PDF foi gerado:

curl -f -X POST https://api.ajustapdf.com/pdf/compress -F "file=@contrato.pdf" -F "level=media" -o contrato-comprimido.pdf

Para testar o fluxo, use um PDF pequeno, de uma ou duas páginas. Cada chamada conta na cota do dia, e um arquivo grande não mostra nada de novo sobre a integração. Quando o fluxo estiver certo, troque pelo arquivo real e confira o tamanho do resultado.

Com a opção -f, o curl sai com erro quando o servidor responde 4xx ou 5xx. Em scripts, isso é o que permite parar no primeiro arquivo que falhar.

As operações disponíveis

Cada ferramenta do site tem um caminho próprio sob /pdf/. A tabela lista as dez operações. A especificação completa, com os campos de cada uma, está publicada em https://www.ajustapdf.com/openapi.json, no formato OpenAPI.

Campos e níveis de compressão

Na compressão, a API lê o arquivo do campo file e o nível do campo level. Se o campo não vier ou tiver outro valor, o servidor usa o nível médio. A tabela mostra o que cada nível faz por dentro, porque é isso que explica o tamanho do resultado:

Texto e vetores não são reamostrados em nenhum dos níveis. Um PDF só de texto encolhe pouco, e a diferença entre os níveis aparece principalmente em fotos e páginas escaneadas.

Limites e códigos de erro

O servidor aplica as mesmas regras de plano ao cliente da API. Sem conta, são 3 operações por dia, 25 MB por arquivo e 2 arquivos por operação. Com conta grátis, 10 por dia, 50 MB e 5 arquivos. Além da cota, há um teto de operações por IP, porque um laço sem controle de quem o executa pode esgotar o serviço para outras pessoas. Por isso, um servidor que faz muitas chamadas seguidas pode receber 429 mesmo sem ter esgotado a cota diária.

Em respostas bem-sucedidas, os cabeçalhos x-quota-used e x-quota-limit mostram quantas operações já foram usadas e o limite do dia. Use-os para mostrar o consumo ao usuário sem fazer uma chamada extra.

Consultar a cota antes de enviar

Antes de montar um lote, consulte o plano e o uso atual com um GET em /pdf/limits. A resposta traz o plano de quem chama (tier), as operações usadas e o limite do dia, além do tamanho máximo por arquivo e o número máximo de arquivos. Com isso, seu código sabe quantas operações ainda cabem antes de começar:

curl https://api.ajustapdf.com/pdf/limits

A consulta não gasta operação. Ela é útil para mostrar ao usuário quanto falta para o limite do dia, em vez de descobrir isso pelo erro 402.

Fluxo recomendado no seu código

1. Verifique o tamanho e a quantidade de arquivos antes de enviar. Recusar no seu código um arquivo acima do limite economiza uma chamada que o servidor responderia com 402.
2. Envie a requisição com multipart/form-data e o campo file. Não defina o Content-Type à mão: a biblioteca HTTP monta o limite do multipart sozinha.
3. Em 200, compare o tamanho do corpo com o do arquivo enviado. Se for igual, a compressão não reduziu nada, e você pode informar isso ao usuário.
4. Em 402 com QUOTA_EXCEEDED ou em 429, não repita a chamada em laço. Espere e mostre a mensagem ao usuário.
5. Não guarde o PDF de saída por mais tempo do que o necessário. O servidor já apagou o seu arquivo quando a resposta saiu, e a cópia do seu sistema é de sua responsabilidade.

Quando a API não serve

A API é útil para integrar uma etapa de compressão a um fluxo pequeno, para testes e para protótipos. Ela não é o caminho para processar milhares de documentos por dia: não há chave, contrato de volume nem cota comprada por integração. Se o seu sistema precisa desse volume, o caminho é rodar o Ghostscript e o qpdf na sua própria infraestrutura, como mostra o guia de compressão no terminal.

Há também o tema de dados pessoais. Quando o PDF tem CPF, endereço ou dados de clientes, ele sai do seu sistema e chega ao servidor. Antes de integrar, leia o guia sobre LGPD e envio de documentos de clientes e defina se o fluxo pode mesmo sair da sua rede.

Para a operação de compressão no site, a mesma lógica está na ferramenta de comprimir PDF. A API faz o mesmo processamento, sem a tela.