# PDF Inteligente — API

> API HTTP para manipular PDFs (unir, dividir, editar páginas, OCR, comprimir,
> converter Office/imagem, PDF→imagem, desbloquear, reparar, remoção real).
> Integração server-to-server. Respostas binárias (o arquivo); erros em JSON.

## Autenticação
Header: Authorization: Bearer pdfi_live_...
A chave é emitida pelo administrador, por serviço consumidor.

## Convenções
- Toda operação é POST multipart/form-data.
- Sucesso: corpo = arquivo binário (Content-Disposition: attachment).
- Erro: JSON { "error": { "message": string, "status": number, "detail"?: string } }.
- Limite do app: ~4,5MB/requisição. Arquivos grandes: use o worker (sync sem limite) ou Jobs (assíncrono).

## Servidores
- App (síncrono, ≤4,5MB): https://pdfdoc.com.br
- Worker (síncrono sem limite + assíncrono): https://pdf-inteligente-worker.onrender.com

## Assíncrono (worker)
- POST https://pdf-inteligente-worker.onrender.com/api/v1/jobs/{op}  → 202 { jobId, statusUrl }   (campo opcional webhookUrl)
- GET  https://pdf-inteligente-worker.onrender.com/api/v1/jobs/{id}  → { status, downloadUrl? }
- GET  https://pdf-inteligente-worker.onrender.com/api/v1/jobs/{id}/result?token=...  → arquivo binário
Webhook ao concluir: POST com header X-PDFI-Signature = HMAC-SHA256(corpo, segredo).

## Operações
- POST /api/v1/merge — Une vários PDFs em um, na ordem enviada. [servidor] (files*:files) → application/pdf
- POST /api/v1/split — Extrai páginas em um único PDF. [servidor] (file*:file, ranges:string, pages:string) → application/pdf
- POST /api/v1/pages — Editor de páginas: remover, extrair, reordenar ou girar. [servidor] (file*:file, action*:string, pages:string, rotation:int) → application/pdf
- POST /api/v1/bates — Numeração Bates / foliação: carimba número sequencial nas páginas. [servidor] (file*:file, prefix:string, suffix:string, start:int, digits:int, position:string, fontSize:int) → application/pdf
- POST /api/v1/watermark — Marca d'água de texto, diagonal, em todas as páginas. [servidor] (file*:file, text*:string, opacity:string, fontSize:int, rotation:int) → application/pdf
- POST /api/v1/crop — Recorta (define o CropBox) removendo margens de todas as páginas. [servidor] (file*:file, topPct:string, rightPct:string, bottomPct:string, leftPct:string) → application/pdf
- POST /api/v1/edit — Carimba texto e tarjas visuais (preencher requerimento / editar). [servidor] (file*:file, elements*:json) → application/pdf
- POST /api/v1/redact — Remoção REAL: apaga o conteúdo sob as áreas (não recuperável). [worker] (file*:file, rects*:json) → application/pdf
- POST /api/v1/office-to-pdf — Converte Office (docx/xlsx/pptx/odt…) em PDF. [worker] (file*:file, ext*:string) → application/pdf
- POST /api/v1/pdf-to-office — Converte PDF em Word/Excel. [worker] (file*:file, target:string) → application/vnd.openxmlformats-officedocument.wordprocessingml.document|application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- POST /api/v1/image-to-pdf — Converte uma ou mais imagens em um PDF. [worker] (files*:files) → application/pdf
- POST /api/v1/ocr — OCR: PDF escaneado → PDF/A pesquisável. [worker] (file*:file, lang:string) → application/pdf
- POST /api/v1/compress — Comprime/otimiza o PDF. [worker] (file*:file, level:string) → application/pdf
- POST /api/v1/unlock — Remove senha/restrições do PDF. [worker] (file*:file, password:string) → application/pdf
- POST /api/v1/repair — Repara PDF corrompido. [worker] (file*:file) → application/pdf
- POST /api/v1/heic-to-jpg — Converte foto HEIC em JPG. [worker] (file*:file) → image/jpeg
- POST /api/v1/heic-to-pdf — Converte uma ou mais fotos HEIC em um PDF. [worker] (files*:files) → application/pdf
- POST /api/v1/pdf-to-image — Converte páginas do PDF em imagens (PNG/JPG). 1 página = imagem; várias = zip. [worker] (file*:file, format:string, dpi:int, pages:string) → image/png|image/jpeg|application/zip
- POST /api/v1/protect — Protege o PDF com senha (criptografia AES-256). [worker] (file*:file, userPassword*:string, ownerPassword:string, allowPrint:string, allowCopy:string) → application/pdf
- POST /api/v1/pdfa — Converte para PDF/A-2b (arquivamento de longo prazo). [worker] (file*:file) → application/pdf
- POST /api/v1/grayscale — Converte para tons de cinza e, opcionalmente, reduz a resolução das imagens. [worker] (file*:file, dpi:int) → application/pdf
- POST /api/v1/anonymize — Anonimiza: tarja PII detectada (CPF/CNPJ/e-mail/telefone) e remove metadados. [worker] (file*:file, types:string, stripMetadata:string) → application/pdf
- POST /api/v1/html-to-pdf — Renderiza uma URL pública ou um HTML em PDF (Chromium). [worker] (url:string, file:file) → application/pdf

## Exemplo (curl)
curl -X POST https://pdfdoc.com.br/api/v1/merge \
  -H "Authorization: Bearer $PDFI_KEY" \
  -F "files=@a.pdf" -F "files=@b.pdf" -o merged.pdf

## Recursos
- OpenAPI 3.1: https://pdfdoc.com.br/api/v1/openapi.json
- Guia humano (PHP/Laravel, TypeScript, curl): https://pdfdoc.com.br/docs