README

简介

PDF Generator API 允许您轻松生成交易性 PDF 文档，并通过允许您的用户使用基于浏览器的拖放文档编辑器创建和管理文档模板来降低开发和支持成本。

PDF Generator API 具有基于 Web 的 API 架构，允许您使用您选择的任何语言进行编码。此 API 支持 JSON 媒体类型，并使用 UTF-8 字符编码。

基本 URL

所有 API 端点的基本 URL 为 https://us1.pdfgeneratorapi.com/api/v4

例如

https://us1.pdfgeneratorapi.com/api/v4/templates
https://us1.pdfgeneratorapi.com/api/v4/workspaces
https://us1.pdfgeneratorapi.com/api/v4/templates/123123

编辑器

PDF Generator API 随附一个强大的拖放编辑器，允许您创建各种文档模板，从条形码标签到发票、报价和报告。您可以在我们的支持门户中找到教程和视频。

定义

组织

组织是您账户拥有的工作区组。

工作区

工作区包含模板。每个工作区都可以访问自己的模板和组织默认模板。

主工作区

主工作区是您组织的主要/默认工作区。主工作区标识符是您注册时使用的电子邮件。

默认模板

默认模板是一种默认情况下对所有工作区都可用的模板。您可以在页面设置下设置模板访问类型。如果模板有“组织”访问权限，则您的用户可以在编辑器的“新建”菜单中使用它们。

数据字段

数据字段是 JSON 数据集中特定数据的占位符。在此示例 JSON 中，您可以使用数据字段 {paymentDetails::buyerName} 访问买家名称。深度级别之间的分隔符是 ::（两个冒号）。在设计模板时，您不需要知道每个数据字段，我们的编辑器会自动从您的数据集中提取所有可用的字段，并提供一种简单的方法将它们插入到模板中。

{
    "documentNumber": 1,
    "paymentDetails": {
        "method": "Credit Card",
        "buyerName": "John Smith"
    },
    "items": [
        {
            "id": 1,
            "name": "Item one"
        }
    ]
}

速率限制

我们的 API 端点使用基于 IP 的速率限制，并允许您每秒最多进行 2 个请求，每分钟最多进行 60 个请求。如果您发出更多请求，您将收到一个 HTTP 状态码 429 的响应。

响应头包含额外的值

库和 SDK

Postman 收集

我们创建了一个 Postman 收集，因此您可以轻松测试所有 API 端点而无需开发和代码。您可以通过以下链接下载收集此处。

客户端库

我们所有的客户端库都是使用 OpenAPI Generator 自动生成的，它使用 OpenAPI v3 规范自动生成特定编程语言的客户端库。

我们已经验证了生成的库，但如果您在客户端代码中发现任何异常，请告诉我们。

身份验证

PDF 生成器 API 使用 JSON Web Tokens (JWT) 来验证所有 API 请求。这些令牌提供了一种通过传输包含您的账户 API 密钥和密钥的签名有效负载的紧凑 JSON 对象来建立安全的服务器到服务器身份验证的方法。当验证 PDF 生成器 API 时，JWT 应由 服务器端应用程序 唯一生成，并包含在每个请求的头部中的 Bearer 令牌。

访问您的 API 密钥和密钥

您可以在登录到 PDF 生成器 API 后的 账户设置 页面上找到您的 API 密钥 和 API 密钥。[在这里](https://pdfgeneratorapi.com/login) 登录。

创建 JWT

JSON Web Tokens 由三个部分组成：一个标题、一个负载（包含一组声明）和一个签名。标题和负载是 JSON 对象，它们被序列化为 UTF-8 字节，然后使用 base64url 编码。

JWT 的标题、负载和签名使用点 (.) 连接。因此，JWT 通常具有以下形式

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

我们推荐并支持在 jwt.io 上提供的库。虽然其他库可以创建 JWT，但这些推荐的库是最健壮的。

标题

属性 alg 定义了正在使用的签名算法。PDF 生成器 API 用户 HS256。属性 typ 定义了令牌的类型，并且始终是 JWT。

{
  "alg": "HS256",
  "typ": "JWT"
}

负载

令牌的第二部分是负载，它包含关于用户的信息和任何所需的元数据。必须指定以下声明

发行者 (iss)：您的 API 密钥
主题 (sub)：工作空间标识符
过期时间 (exp)：令牌有效的截止时间戳（Unix 纪元时间）。强烈建议将 exp 时间戳设置为短时间，例如几秒钟。这样，如果令牌被拦截或共享，令牌将仅在短时间内有效。

{
  "iss": "ad54aaff89ffdfeff178bb8a8f359b29fcb20edb56250b9f584aa2cb0162ed4a",
  "sub": "demo.example@actualreports.com",
  "exp": 1586112639
}

签名

要创建签名部分，您必须使用编码的标题、编码的负载、一个秘密、标题中指定的算法来签名。签名用于验证消息在传输过程中没有被更改，在用私有密钥签名的令牌的情况下，它还可以验证 JWT 的发送者是否为它声称的人。

HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    API_SECRET)

合并所有内容

输出是三个用点分隔的 Base64-URL 字符串。以下显示了一个使用先前标题和负载编码，并使用秘密签名的 JWT。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZDU0YWFmZjg5ZmZkZmVmZjE3OGJiOGE4ZjM1OWIyOWZjYjIwZWRiNTYyNTBiOWY1ODRhYTJjYjAxNjJlZDRhIiwic3ViIjoiZGVtby5leGFtcGxlQGFjdHVhbHJlcG9ydHMuY29tIn0.SxO-H7UYYYsclS8RGWO1qf0z1cB1m73wF9FLl9RCc1Q

// Base64 encoded header: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
// Base64 encoded payload: eyJpc3MiOiJhZDU0YWFmZjg5ZmZkZmVmZjE3OGJiOGE4ZjM1OWIyOWZjYjIwZWRiNTYyNTBiOWY1ODRhYTJjYjAxNjJlZDRhIiwic3ViIjoiZGVtby5leGFtcGxlQGFjdHVhbHJlcG9ydHMuY29tIn0
// Signature: SxO-H7UYYYsclS8RGWO1qf0z1cB1m73wF9FLl9RCc1Q

临时 JWT

您可以在登录到 PDF 生成器 API 后的账户设置页面上创建临时令牌。生成的令牌使用您的电子邮件地址作为主题 (sub) 值，有效期为 15 分钟。您还可以使用 jwt.io 为您的 API 调用生成测试令牌。这些测试令牌绝不应该在生产应用程序中使用。

错误代码

401 未授权

402 需要支付

403 禁止

404 实体未找到

422 无法处理的实体

429 请求过多

获取更多信息，请访问 https://support.pdfgeneratorapi.com。

安装与使用

需求

PHP 7.4 及更高版本。也应与 PHP 8.0 兼容。

Composer

通过 Composer 安装绑定，请在 composer.json 中添加以下内容

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/pdfgeneratorapi/php-client.git"
    }
  ],
  "require": {
    "pdfgeneratorapi/php-client": "master"
  }
}

然后运行 composer install

手动安装

下载文件并包含 autoload.php

<?php
require_once('/path/to/PDFGeneratorAPI/vendor/autoload.php');

入门指南

请遵循安装过程，然后运行以下命令

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure Bearer (JWT) authorization: JSONWebTokenAuth
$config = PDFGeneratorAPI\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new PDFGeneratorAPI\Api\ConversionApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$convert_html2_pdf_request = new \PDFGeneratorAPI\Model\ConvertHTML2PDFRequest(); // \PDFGeneratorAPI\Model\ConvertHTML2PDFRequest

try {
    $result = $apiInstance->convertHTML2PDF($convert_html2_pdf_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ConversionApi->convertHTML2PDF: ', $e->getMessage(), PHP_EOL;
}

API 端点

所有 URI 都是相对于 https://us1.pdfgeneratorapi.com/api/v4

模型

授权

JSONWebTokenAuth

类型：Bearer 认证 (JWT)

测试

运行测试，使用

composer install
vendor/bin/phpunit

作者

support@pdfgeneratorapi.com

关于此包

此 PHP 包由 OpenAPI Generator 项目自动生成

API 版本：4.0.4
构建包：org.openapitools.codegen.languages.PhpClientCodegen

pdfgeneratorapi / php-client

维护者

详细信息