PowerShell: juntar PDFs de várias pastas em lote

Para juntar os PDFs de várias pastas no Windows, o PowerShell lista as pastas e monta um pedido por pasta, e a API faz a junção. Guarde a chave na variável AJUSTAPDF_KEY, rode um laço por pasta e chame o curl.exe. Cada pasta gasta uma operação da cota, e o plano define quantos arquivos cabem num pedido.

Prepare a chave e o ambiente

Crie a chave na página Conta, na seção Chaves de API, e copie-a logo, porque ela aparece uma única vez. Para guardá-la sem deixá-la escrita no histórico do terminal, peça-a com o Read-Host e grave-a no ambiente do usuário. Depois abra um novo terminal para a variável valer.

[Environment]::SetEnvironmentVariable("AJUSTAPDF_KEY", (Read-Host "Cole a chave"), "User")

Confira a versão do PowerShell com $PSVersionTable.PSVersion. Na 7 ou superior, o Invoke-WebRequest aceita o parâmetro -Form e envia arquivos direto. Na 5.1, que vem com o Windows, use o curl.exe, o mesmo caminho do guia de comprimir e juntar pelo terminal. Escreva sempre curl.exe, com a extensão, porque no Windows PowerShell 5.1 a palavra curl sozinha é um apelido do Invoke-WebRequest.

O script: uma pasta, um PDF

A estrutura mais simples é uma pasta por documento final, com as partes dentro. O script percorre as subpastas, pega os PDFs de cada uma em ordem de nome e monta um argumento -F por arquivo. A ordem da lista é a ordem das páginas, então nomeie as partes com números: 01, 02, 03.

$raiz = "C:\Contratos"
$falhas = Join-Path $raiz "falhas.txt"

Get-ChildItem -Path $raiz -Directory | ForEach-Object {
    $pasta = $_
    $partes = Get-ChildItem -Path $pasta.FullName -Filter *.pdf | Sort-Object Name
    if ($partes.Count -lt 2) { Write-Warning "$($pasta.Name): menos de 2 PDFs"; return }

    $campos = foreach ($p in $partes) { "-F"; "files=@$($p.FullName)" }
    $saida = Join-Path $raiz "$($pasta.Name)-unido.pdf"

    curl.exe -f -sS -X POST https://api.ajustapdf.com/pdf/merge `
        -H "Authorization: Bearer $env:AJUSTAPDF_KEY" @campos -o $saida

    if ($LASTEXITCODE -ne 0) { Add-Content $falhas $pasta.Name }
}

O cabeçalho de autorização usa a variável de ambiente: em uma string entre aspas duplas, o PowerShell expande $env:AJUSTAPDF_KEY sozinho, então o valor nunca aparece no script. A opção -f faz o curl.exe sair com código 22 quando a API recusa o pedido, e o script anota a pasta num arquivo de falhas para repetir só ela depois. Pastas com menos de dois PDFs são puladas, porque a rota exige pelo menos dois arquivos.

Limites que travam o lote

Os limites são por plano, e o lote estoura o plano antes de estourar o computador. A tabela mostra os números que valem para a juntada:

Duas consequências práticas. Primeiro, uma pasta com sete PDFs não cabe num pedido no plano grátis, que aceita 5 por operação: a API responde 402 com TOO_MANY_FILES. Divida em dois grupos e junte os grupos depois, ou use o Pro. Segundo, o limite de 10 operações por dia do plano grátis não serve para um lote de 12 pastas, que precisa de pelo menos 12 operações. Antes de começar, conte as operações necessárias e compare com a cota do dia.

Leia a cota durante o lote

Peça os cabeçalhos da resposta com a opção -D, gravando num arquivo temporário, e leia os campos x-quota-used e x-quota-limit com o Select-String. Eles dizem quantas operações já foram gastas e qual é o teto, e aparecem nas respostas bem-sucedidas. Um script que lê esses números depois de cada pedido e para antes do teto evita descobrir o bloqueio pelo erro 402.

Quando a cota acaba, a API responde 402 com QUOTA_EXCEEDED. Com o -f, o curl.exe sai com código diferente de zero e não grava o JSON do erro. Trate esse caso como parada: registre a pasta, espere a virada do dia e rode de novo só as que faltam. Para ler a mensagem exata, repita aquele pedido sem o -f e com a saída no terminal.

Cuidados com documentos reais

Junte apenas os arquivos que você tem direito de tratar. Num lote de contratos ou de prontuários, há dados pessoais de outras pessoas, e a responsabilidade pelo envio é de quem envia. Os arquivos são processados no servidor e apagados assim que a resposta sai, mas isso não dispensa conferir o que está na pasta antes de processar.

Teste sempre com uma pasta pequena, com arquivos de teste, e abra o resultado. O juntar copia as páginas, anotações e campos de formulário sem reprocessar, mas não leva marcadores, camadas nem metadados do documento de origem. Se o seu lote depende de um índice interno, gere o índice depois, no arquivo final. Um PDF com senha de abertura precisa ser desbloqueado antes; a API recusa o arquivo com PASSWORD_REQUIRED.

Quando a junção é pontual

Se são poucos arquivos e você não precisa de script, a ferramenta de juntar PDF no navegador resolve em um passo. O PowerShell vale quando a tarefa se repete todo mês, com as mesmas pastas e a mesma ordem. Para comprimir os resultados em seguida, veja o guia de processar uma pasta inteira de PDFs; para juntar, comprimir e proteger numa execução só, o guia de fluxo em uma execução reduz o número de envios (cada etapa ainda conta uma operação). A referência completa de rotas e campos está no guia da API para desenvolvedores.

Checklist antes de rodar

• Confira a versão do PowerShell e use curl.exe se for a 5.1.
• Ordene os arquivos por nome e confirme a ordem na lista antes de enviar.
• Conte as operações necessárias e compare com a cota do dia.
• Grave cada resultado com um nome novo, sem sobrescrever os originais.