Generare fatture PDF in PHP (Yii2 / Laravel) via REST API

Prerequisiti

• PHP 7.4+ o 8.x
• Account QuartzAPI e API key
• Un template attivo creato nel Visual Builder QuartzAPI (es. INVOICE_V1)
• Opzionale: HTTP client Laravel, oppure yiisoft/yii2-httpclient in Yii2

Fase 1: prepara il payload JSON

Che tu recuperi i dati da Eloquent (Laravel) o Active Record (Yii2), strutturarli in un array associativo allineato ai placeholder del template. QuartzAPI si aspetta i dati in data, in genere con un oggetto master e le righe in master.items.

<?php

$invoiceData = [
    'templateCode' => 'INVOICE_V1',
    'outputFormat' => 'pdf',
    'externalId' => 'INV-2026-0042',
    'data' => [
        'master' => [
            'invoice_number' => 'INV-2026-0042',
            'date' => date('Y-m-d'),
            'customer_name' => 'Acme Corporation',
            'customer_vat' => 'US123456789',
            'customer_email' => 'billing@acme.com',
            'subtotal' => 1090.00,
            'tax' => 239.80,
            'grand_total' => 1329.80,
            'items' => [
                [
                    'description' => 'Web Development Services',
                    'quantity' => 10,
                    'price' => 85.00,
                    'total' => 850.00,
                ],
                [
                    'description' => 'Cloud Hosting (Annual)',
                    'quantity' => 1,
                    'price' => 240.00,
                    'total' => 240.00,
                ],
            ],
        ],
    ],
];

I nomi dei campi devono coincidere con i binding del template. Per il pattern JSON→PDF in generale, vedi Come generare fatture in PDF da JSON.

Fase 2: implementazione in Laravel

Usa l’HTTP client di Laravel (Illuminate\Support\Facades\Http) per chiamare generate-document, scaricare il PDF e restituirlo al browser. Salva la API key in config/services.php (es. services.quartzapi.key).

Esempio controller (InvoiceController.php):

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Http;

class InvoiceController extends Controller
{
    public function downloadPdf(int $invoiceId)
    {
        // 1. Costruisci il payload dal model Eloquent (qui semplificato)
        $payload = [
            'templateCode' => 'INVOICE_V1',
            'outputFormat' => 'pdf',
            'externalId' => 'INV-2026-0042',
            'data' => [
                'master' => [
                    'invoice_number' => 'INV-2026-0042',
                    'grand_total' => 1329.80,
                    // … altri attributi / items …
                    'items' => [],
                ],
            ],
        ];

        // 2. Genera il documento
        $generate = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.quartzapi.key'),
            'Content-Type' => 'application/json',
        ])->post('https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document', $payload);

        if ($generate->failed()) {
            return back()->with('error', 'Generazione PDF fallita.');
        }

        $documentId = $generate->json('result.documentId');
        $downloadUrl = $generate->json('result.downloadUrl')
            ?: 'https://backend.quartzapi.com/index.php?r=api/v1-documents/download&uid=' . urlencode((string) $documentId);

        // 3. Scarica i byte PDF
        $pdf = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.quartzapi.key'),
        ])->get($downloadUrl);

        if ($pdf->failed()) {
            return back()->with('error', 'Download PDF fallito.');
        }

        // 4. Download nel browser
        return response($pdf->body(), 200, [
            'Content-Type' => 'application/pdf',
            'Content-Disposition' => 'attachment; filename="Invoice-2026-0042.pdf"',
        ]);
    }
}

Fase 3: implementazione in Yii2

In Yii2 puoi usare yii\httpclient\Client (o cURL) in un’action del controller. Tieni la API key in params (es. Yii::$app->params['quartzApiKey']).

Esempio controller (InvoiceController.php):

<?php

namespace app\controllers;

use Yii;
use yii\httpclient\Client;
use yii\web\Controller;
use yii\web\ServerErrorHttpException;

class InvoiceController extends Controller
{
    public function actionDownloadPdf($id)
    {
        $payload = [
            'templateCode' => 'INVOICE_V1',
            'outputFormat' => 'pdf',
            'externalId' => 'INV-2026-0042',
            'data' => [
                'master' => [
                    'invoice_number' => 'INV-2026-0042',
                    'grand_total' => 1329.80,
                    'items' => [],
                ],
            ],
        ];

        $client = new Client();
        $generate = $client->createRequest()
            ->setMethod('POST')
            ->setUrl('https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document')
            ->addHeaders([
                'Authorization' => 'Bearer ' . Yii::$app->params['quartzApiKey'],
                'Content-Type' => 'application/json',
            ])
            ->setContent(json_encode($payload))
            ->send();

        if (!$generate->isOk) {
            throw new ServerErrorHttpException('Servizio di rendering PDF non disponibile.');
        }

        $body = $generate->data;
        $documentId = $body['result']['documentId'] ?? '';
        $downloadUrl = $body['result']['downloadUrl']
            ?? ('https://backend.quartzapi.com/index.php?r=api/v1-documents/download&uid=' . rawurlencode($documentId));

        $pdf = $client->createRequest()
            ->setMethod('GET')
            ->setUrl($downloadUrl)
            ->addHeaders([
                'Authorization' => 'Bearer ' . Yii::$app->params['quartzApiKey'],
            ])
            ->send();

        if (!$pdf->isOk) {
            throw new ServerErrorHttpException('Download PDF fallito.');
        }

        return Yii::$app->response->sendContentAsFile(
            $pdf->content,
            'Invoice-2026-0042.pdf',
            ['mimeType' => 'application/pdf', 'inline' => true]
        );
    }
}

Vantaggi rispetto a mPDF / Dompdf

• Zero overhead RAM sui tuoi server applicativi: la memoria resta prevedibile indipendentemente dalla dimensione del documento — il rendering avviene su QuartzAPI.
• Niente workaround CSS: il layout vive nell’editor drag-and-drop, non in stringhe HTML PHP.
• Aggiornamenti di design immediati: cambia intestazioni, font o colonne senza deploy.

Conclusioni

Per i team Yii2 e Laravel, le fatture PDF devono essere un problema di dati, non di layout. Chiama generate-document, scarica il file e consegna il PDF — mentre i designer aggiornano i template nel portale.

Pronto a togliere mPDF dallo stack? QuartzAPI è in Beta pubblica: crea un account gratuito, ottieni la API key e collega gli esempi al tuo controller fatture.

👉 Inizia gratis con la Beta QuartzAPI