2026年7月18日 · 阅读约 12 分钟

如何用 JSON API 生成 PDF 发票（无需版式库）

实战指南：一次 REST 调用即可从 JSON 生成多页 PDF 发票——无需 mPDF、iText 或 X/Y 坐标。

从应用数据生成 PDF 发票，几乎是所有 Web 应用、管理软件和 ERP 系统的标准需求。然而，凡是尝试过实现这一功能的人都知道，它很快就会变成一场开发噩梦。

手动计算像素坐标（X 和 Y）、处理包含数十行的表格分页、避免文本被拦腰截断，以及配置自定义字体，需要花费数小时。每当商务团队或客户提出哪怕只是移动一下 Logo 的版式修改时，开发人员都必须重新改动源码、测试并重新部署。

在本指南中，我们将说明如何摆脱这种过时做法，通过一次 HTTP REST 调用，从简单的 JSON 字典生成专业的多页 PDF 发票，并将版式管理交给外部云引擎——无需在你的技术栈中引入版式库（PHP、Node.js、C#、Python）。

传统 PDF 库的问题（mPDF、FPDF、iText、PDFSharp）

老式 PDF 渲染库（无论是 PHP、Node.js、C# 还是 Python）对现代软件公司而言存在三个根本问题：

数据与版式耦合：从数据库取数的代码与绘制表格的图形指令混在一起。
灵活性差：修改发票模板需要改代码并走部署周期。
资源消耗：大批量 PDF 生成是 CPU 密集型操作，若未正确隔离，可能拖慢主应用。

把数据与设计分离才是正解：后端应用只需收集数据、整理成干净的 JSON 对象，再发给文档生成 API，即可拿回现成 PDF。如果你在找如何从 JSON 生成 PDF、用 API 创建 PDF 发票，或C# / PHP / Node PDF 库的替代方案，这就是现代的 JSON-to-PDF 模式。

第 1 步：构建发票 JSON 载荷

第一步是定义数据结构。设计良好的发票 JSON 字典应包含开票方、客户、单据元数据以及明细行数组。

以下是标准化载荷示例（可复制并适配到你的模板结构）：

{
  "documento": {
    "tipo": "Fattura Differita",
    "numero": "FPA-2026-1044",
    "data": "18/07/2026",
    "valuta": "EUR"
  },
  "emittente": {
    "ragione_sociale": "Sviluppo Software S.r.l.",
    "partita_iva": "IT01234567890",
    "indirizzo": "Via dell'Innovazione 42",
    "cap_citta": "66034 Lanciano (CH)",
    "email": "amministrazione@softwarehouse.it"
  },
  "cliente": {
    "ragione_sociale": "Azienda Cliente SpA",
    "partita_iva": "IT09876543210",
    "indirizzo": "Corso Vittorio Emanuele II, 100",
    "cap_citta": "00100 Roma (RM)"
  },
  "righe_fattura": [
    {
      "codice": "SW-SAAS-01",
      "descrizione": "Abbonamento Cloud SaaS QuartzAPI - Licenza Enterprise (Mensile)",
      "quantita": 1,
      "prezzo_unitario": 249.00,
      "aliquota_iva": 22
    },
    {
      "codice": "CONS-PRO-02",
      "descrizione": "Attività di integrazione sistemi ERP e configurazione Webhook",
      "quantita": 8,
      "prezzo_unitario": 75.00,
      "aliquota_iva": 22
    }
  ],
  "totali": {
    "imponibile": 849.00,
    "imposta": 186.78,
    "totale_documento": 1035.78
  }
}

第 2 步：在云门户配置模板

不必再为在 PDF 中打印表格行编写 foreach 循环逻辑，而是在 QuartzAPI 门户上传图形模板（可视化 Template Builder）。在模板中插入与 JSON 键对应的占位符（例如绑定到 cliente.ragione_sociale 的字段）。

引擎读取 righe_fattura 数组并自动循环表格的 Details 区段，在明细跨 2、3 或更多页时计算分页位置，同时保留页眉与页脚。你的管理系统里无需编写任何 X/Y 坐标。

第 3 步：调用 Web API 生成 PDF

配置好模板（门户中的模板代码，例如 INVOICE1）并获取 API key 后，你的应用发送 HTTP POST 请求。QuartzAPI 生成 PDF，并可将其保存到文档文件夹（folderId），便于下载和邮件发送。

接口：POST …/index.php?r=api/v1-jobs/generate-document — 请求体包含 templateCode、data（上文 JSON）以及可选的 folderId。文档：Web API。

Node.js 示例（Axios）

const axios = require('axios');

const payloadFattura = { /* ... 上文定义的 JSON ... */ };

async function generaFattura() {
  try {
    const response = await axios.post(
      'https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document',
      {
        templateCode: 'INVOICE1',
        folderId: 'fld_ESEMPIO_CARTELLA',
        externalId: 'FPA-2026-1044',
        outputFormat: 'pdf',
        data: payloadFattura
      },
      {
        headers: {
          Authorization: 'Bearer TUO_API_KEY_SEGRETA',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('PDF 生成成功！', response.data);
    // result.documentId 与 downloadUrl 用于安全下载
  } catch (error) {
    console.error(
      '生成 PDF 时出错：',
      error.response ? error.response.data : error.message
    );
  }
}

generaFattura();

PHP 示例（cURL）

<?php

$payloadFattura = [ /* ... PHP 数组形式的 JSON 字典 ... */ ];

$ch = curl_init('https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'templateCode' => 'INVOICE1',
    'folderId' => 'fld_ESEMPIO_CARTELLA',
    'externalId' => 'FPA-2026-1044',
    'outputFormat' => 'pdf',
    'data' => $payloadFattura,
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer TUO_API_KEY_SEGRETA',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'cURL 错误：' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo '文档已保存。documentId: ' . ($data['result']['documentId'] ?? '');
}
curl_close($ch);

通过 API 从 JSON 生成的 PDF 发票预览 — 多页 PDF 发票示例：版式在云模板上，数据来自你的 JSON。

后续处理：下载与自动邮件发送

基于 API 的方案在生成之后的灵活性是一大优势。由于 PDF 已保存在门户文件夹中：

按需下载：使用 GET …/index.php?r=api/v1-documents/download&uid={documentId} 下载文件。
集成邮件发送：调用 POST …/index.php?r=api/v1-jobs/send-document，传入 documentId 和收件人。可使用 API key 上配置的 SMTP，无需在管理系统中维护复杂的邮件组件。

结语

把 PDF 文档当作需要维护的图形代码，是软件公司再也承受不起的技术债。转向通过 API 的 JSON-to-PDF 架构可缩短开发时间、隔离计算负载，并让非技术人员也能更新模板，而无需改动应用的一行代码。

准备好从代码中移除 PDF 库了吗？ QuartzAPI 现已公开 Beta：免费注册、获取 API key，发送你的 JSON 对象即可测试发票与报表生成。

👉 免费开始使用 QuartzAPI Beta

即用代码片段

复制上文 JSON 与 Node/PHP 示例，并替换 INVOICE1 / API key。
在门户中：Templates → JSON Postman，可获得已对齐你模板的请求体。
完整参考：Web API 文档。