API de Manipulação de PDF

Início rápido

Toda operação é POST multipart/form-data e responde com o arquivo binário resultante. Exemplo — unir 2 PDFs:

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

Autenticação

Envie a API key (emitida pelo administrador, por serviço) no header:

Authorization: Bearer pdfi_live_xxxxxxxx...

A chave é guardada com hash — o valor em claro aparece uma única vez na criação. Trate-a como segredo (variável de ambiente, nunca no front-end). Use uma chave por serviço para poder revogar isoladamente.

Convenções e erros

• Sucesso: corpo = arquivo binário (Content-Disposition: attachment).
• Erro: JSON { "error": { "message", "status", "detail?" } }.
• Sempre verifique o status HTTP antes de tratar o corpo como arquivo.

Limites e arquivos grandes

O servidor de app aceita ~4,5 MB por requisição. Para arquivos grandes, chame o mesmo endpoint no worker (síncrono, sem limite) ou use o fluxo assíncrono (abaixo).

use PdfInteligente\Laravel\Pdfi;

// síncrono no worker (sem limite de tamanho)
$bytes = Pdfi::callLarge('compress', ['file' => [storage_path('app/grande.pdf')]], ['level' => 'ebook']);

Assíncrono e webhooks

Operações longas (OCR, arquivos grandes): submeta um job e acompanhe por polling ou webhook. O resultado fica em URL temporária assinada (TTL) e depois é apagado.

use PdfInteligente\Laravel\Pdfi;

// submete + aguarda (polling automático)
$pdf = Pdfi::process('ocr', ['file' => [storage_path('app/scan.pdf')]], ['lang' => 'por']);

// ou só submete com webhook (não bloqueia)
$job = Pdfi::submit('ocr', ['file' => [storage_path('app/scan.pdf')]], [], 'https://seu-app/webhooks/pdfi');

O webhook chega como POST com header X-PDFI-Signature = HMAC-SHA256(corpo, segredo). Valide antes de confiar:

use PdfInteligente\PdfInteligente;

public function pdfiWebhook(\Illuminate\Http\Request $request)
{
    $ok = PdfInteligente::verifyWebhook(
        $request->getContent(),
        $request->header('X-PDFI-Signature', ''),
        config('pdf-inteligente.webhook_secret'),
    );
    abort_unless($ok, 401);

    $data = $request->json()->all();
    if (($data['status'] ?? '') === 'done') {
        $bytes = file_get_contents($data['downloadUrl']); // URL assinada (TTL)
        // ... persistir
    }
    return response()->noContent();
}

SDK PHP / Laravel

Pacote Composer com integração nativa do Laravel (ServiceProvider + Facade Pdfi auto-descobertos). Código em php-sdk/ no repositório.

# composer.json do seu app:
"repositories": [
  { "type": "vcs", "url": "https://github.com/ajbondstar/pdf-inteligente" }
]

composer require pdf-inteligente/php-sdk:dev-main
php artisan vendor:publish --tag=pdf-inteligente-config

No .env:

PDFI_API_KEY=pdfi_live_xxxxxxxx
PDFI_BASE_URL=https://pdfdoc.com.br
PDFI_WORKER_URL=https://pdf-inteligente-worker.onrender.com
PDFI_WEBHOOK_SECRET=...   # combine com o admin (para validar webhooks)

Recebendo uploads do request? Passe os caminhos: collect($request->file('docs'))->map->getRealPath()->all(). Para bytes em memória use PdfInteligente\Upload::fromString($bytes, 'a.pdf'). Detalhes no php-sdk/README.md.

Editor embutível (iframe)

Embuta o editor (preencher / editar / censura) no seu produto. Comunicação por postMessage:

<iframe id="pdfi" src="https://pdfdoc.com.br/embed/editor"
        style="width:100%;height:80vh;border:0"></iframe>
<script>
  const f = document.getElementById("pdfi");
  addEventListener("message", (e) => {
    if (e.data?.type === "pdfi:ready")
      f.contentWindow.postMessage({ type: "pdfi:load", pdf: arrayBuffer, fileName: "req.pdf" }, "*");
    if (e.data?.type === "pdfi:result")
      new Blob([e.data.pdf], { type: "application/pdf" }); // PDF final
  });
</script>

Operações

* obrigatório