A mesma operação em quatro clientes: navegador, curl, MCP e pdfx
A mesma mesclagem do PDF123 por quatro clientes: o formulário do navegador, o curl em /api/v1/general/merge-pdfs, o MCP em /mcp e o pdfx local ou --cloud.
Quatro clientes parecem quatro produtos. Na verdade, compartilham um único catálogo. Tome Mesclar como a tarefa concreta: combinar PDFs na ordem de upload sem rasterizar páginas em imagens. O mesmo padrão vale para todas as outras ferramentas do catálogo (compress, OCR, convert e o resto): um id de operação, quatro formas de chamá-la.
Navegador
Abra /pt/merge, adicione os arquivos na ordem desejada, clique em Process e baixe. Nada de conta para as ferramentas do catálogo. O bloco "Call this from code" da página monta o curl a partir dos mesmos campos que o formulário envia, então a interface e o contrato HTTP permanecem alinhados.
Esse bloco não é texto de marketing. Ele é gerado a partir da definição de ferramenta que o portal já usa no formulário, e é por isso que a renomeação de um parâmetro aparece nos dois lugares ao mesmo tempo. Se o formulário aceita sortType=byFileName como opção, o exemplo de curl pode levar o mesmo campo.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
As chamadas anônimas do catálogo não precisam de chave. As chaves de Desenvolvedores dão identidade estável à automação (e controle de acesso aos servidores self-hosted). A OpenAPI fica em /v1/openapi.json.
Para tarefas de várias etapas, POST /api/v1/pipeline aceita operações ordenadas num campo steps (por exemplo, mesclar, depois aplicar watermark, depois comprimir). Envie Idempotency-Key quando uma nova tentativa não puder executar o trabalho duas vezes; uma repetição bem-sucedida pode voltar com Idempotency-Replayed. As falhas usam application/problem+json com códigos estáveis como rate_limited e bad_request (Erros para desenvolvedores).
As respostas do serviço hospedado também trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; o HTTP 429 inclui Retry-After. Trate esses cabeçalhos como o orçamento real, não como um número decorado de um post (limite de requisições anônimas).
MCP
Agentes que falam Model Context Protocol se conectam a /mcp, descobrem o merge como ferramenta e o chamam com a mesma lógica de chave de API do REST. Documentação: MCP para desenvolvedores.
O MCP não é um segundo catálogo. É um protocolo de descoberta e invocação sobre as mesmas operações que a OpenAPI lista. Se uma operação não aparece no MCP, isso é uma falha do servidor, não um roteiro de produto separado. Combine o MCP com o /llms.txt quando quiser um índice em prosa das ferramentas antes de o cliente se conectar.
CLI pdfx
Com o pdf-core local:
pdfx merge a.pdf b.pdf -o merged.pdf
Ou contra o mesmo servidor que o portal usa:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
O modo local nunca envia nada pela rede; o modo nuvem atinge a sua URL base com o mesmo formato multipart do curl. O skill para agentes de código em dist/skills/pdf-toolbox/SKILL.md documenta os mesmos formatos de merge e pipeline, para que os agentes não inventem uma segunda OpenAPI.
O OCR em qualquer um desses clientes continua devolvendo Markdown em /api/v1/misc/ocr-pdf, não uma camada de texto oculta. Esse fato faz parte do contrato compartilhado: mudar o tipo de retorno em um cliente sem mudar nos outros quebraria a promessa de "mesma operação". O Compress fica em /api/v1/misc/compress-pdf para a recompressão de streams; é outra operação, alcançável das mesmas quatro formas.
Por que essa igualdade importa
Se a mesclagem pelo navegador e a mesclagem pela API divergissem, as automações regrediriam em silêncio enquanto a página de demonstração continuaria parecendo certa. Uma operação, quatro formas de acesso: é disso que se trata. O portal é um cliente de conveniência, não uma segunda implementação de merge, compress ou OCR.
É também por isso que não existe uma versão para desktop: uma quinta árvore de interface recriaria o problema da divergência sob outro nome de binário. Para um contexto mais amplo, veja Feito para agentes de IA, não só para navegadores. Sobre a decisão do desktop, veja Por que não fizemos um aplicativo desktop. Para levantar a API na sua rede, veja Self-host.