SaaS服务API文档

  • 产品介绍

    1. PDFluxSaaS提供一套完整易用的REST API，供计算机调用，让您把PDF复杂格式抛诸脑后；

    2. 支持将各类PDF格式的金融文档，包括年报、审计报告、IPO 招股说明书、债券募集说明书、评级报告、研究报告等解析为文本段落、表格、图片等内容块的序列，并保留原文档的阅读顺序；

    3. 支持中英文多栏复杂排版的PDF文档解析，跨栏和跨页内容块智能自动合并；

    4. 智能识别表格的内部结构：单元格合并，单元格文字的对齐方式、缩进、颜色、加粗、斜体等样式信息，跨页和跨栏表格智能合并单元格文字；

    5. 智能识别文档的目录结构，支持多达10个层级，长文档信息抽取必不可少；

    6. 支撑后续各类文档智能的应用：PDF文档全文检索、文档级别信息抽取等；

    7. 使用庖丁科技自研Fin-OCR，高效识别模糊以及含有涂写、水印等干扰因素的文档。

    开发者中心
    申请试用

  • 使用说明

    1. 在https://saas.pdflux.com/中点击申请试用或通过contact@paodingai.com邮件联系我们开通试用；

    2. 申请成功后我们会提供专属用户名、Secret和get_token.py文件；

    3. 根据下文中的描述拼接https请求URL，再通过运行get_token.py来获取带有token的URL；

    4. 通过上一步中获取的带有token的URL即可上传文件、下载结果；

    5. 除下载接口外，系统接口返回数据格式一般为 json；

    6. https 请求提交数据时，如未特殊说明，也使用 json 格式；

    请求成功
    {
  status: true,
  errcode: 0,
  msg: null,
  data: {},
}
    请求异常
    {
  status: false,
  errcode: 1,
  msg: 'No File Found',
  data: null,
}

  • Token生成方法

    URL均需要添加验证参数：
    _timestamp 时间戳
_token 令牌
    验证参数生成方法：
    使用python3运行get_token.py + 对应URL
    示例
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/upload?user=####&force_update=true"
    根据URL生成Token示例（Python3）：
    
import sys
import hashlib
import urllib.parse
from datetime import datetime

def revise_url(url, extra_params=None, excludes=None):
    extra_params = extra_params or {}
    excludes = excludes or []
    main_url, query = urllib.parse.splitquery(url)
    params = urllib.parse.parse_qs(query) if query else {}
    params.update(extra_params)
    keys = list(params.keys())
    keys.sort()
    params_strings = []
    for key in keys:
        if key in excludes:
            continue
        values = params[key]
        if isinstance(values, list):
            values.sort()
            params_strings.extend(["{}={}".format(key, urllib.parse.quote(str(value))) for value in values])
        else:
            params_strings.append("{}={}".format(key, urllib.parse.quote(str(values))))

    return "{}?{}".format(main_url, "&".join(params_strings)) if params_strings else main_url

def generate_timestamp():
    delta = datetime.utcnow() - datetime.utcfromtimestamp(0)
    return int(delta.total_seconds())

def _generate_token(url, app_id, secret_key, extra_params=None, timestamp=None):
    url = revise_url(url, extra_params=extra_params, excludes=["_token", "_timestamp"])
    timestamp_now = timestamp or generate_timestamp()
    source = "{}#{}#{}#{}".format(url, app_id, secret_key, timestamp_now)
    token = hashlib.md5(source.encode()).hexdigest()
    return token

def encode_url(url, app_id, secret_key, params=None, timestamp=None):
    timestamp = timestamp or generate_timestamp()
    token = _generate_token(url, app_id, secret_key, params, timestamp)
    extra_params = {
        '_timestamp': timestamp,
        '_token': token
    }
    extra_params.update(params or {})
    url = revise_url(url, extra_params=extra_params)
    return url

if __name__ == '__main__':
    URL = sys.argv[1]

    url = encode_url(URL, 'pdflux', '请在此处填写您的Secret')  # pdflux是appid，请勿改动
    print(url)

  • 获取已使用页数、总页数和起止时间

    接口地址
    /api/v1/saas/usage?user=####
    请求类型
    GET
    请求参数
    参数名类型说明
    userstring用户名，拼接在URL中，例：user=####，必填
    返回字段
    参数名类型说明
    restnumber扫描件剩余页数，可能为负数
    totalnumber扫描件总页数
    trial_startstring起始时间
    trial_endstring截止时间
    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/usage?user=pdflux"
    示例 - 返回结果
    {
  data: {
    rest: 99952, // 扫描件剩余页数
    total: 100001, // 扫描件总页数
    trial_start: "2020-10-01 00:00:00", // 起始时间
    trial_end: "2020-10-31 00:00:00", // 截止时间
  },
  errcode: 0,
  msg: null,
  status: true
}

  • 上传文件

    接口地址
    /api/v1/saas/upload?force_update=true&user=####
    请求类型
    POST
    请求参数
    参数名类型说明
    filefile待分析文档，必填
    userstring用户名，拼接在URL中，例：user=####，必填
    force_updatestring非必填，强制文档重新识别，例如上传重复文件、旧文件时，PDFlux为了经济性默认会优先获取已有的旧结果，增加force_update=true后将会强制重新识别获取最新结果
    返回字段
    参数名类型说明
    uuidstring文件 id，后续用于获取结果
    checksumstring文件hash
    filenamestring文件名
    filepathstring文件路径
    parsedint-1=解析异常、0=待解析、1=解析中、2=解析完毕
    created_utcint创建时间
    updated_utcint修改时间
    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/upload&force_update=true&user=pdflux"
    示例 - 请求上传
    POST https://saas.pdflux.com/api/v1/saas/upload?_timestamp=1590560297&_token=bf5bd348e4a414be0aa57899878bd66c&user=pdflux
    示例 - 返回结果
    {
  status: true,
  data: {
    uuid: 'b75487ae-09d6-4948-bac5-7924d24bedbb',
    checksum: 'dbc325d09eb6c8af234a57fe62ae6a20',
    filename: '第二次公开募股.pdf',
    filepath: '1672345948/f6f8e0b7df6188cd30b37004bbaa2b6d_1816579.pdf',
    parsed: 1,
    created_utc: 1508467057,
    updated_utc: 1508467057,
  },
}

  • 获取文档处理状态

    接口地址
    /api/v1/saas/document/<uuid>?user=####
    请求类型
    GET
    请求参数
    参数名类型说明
    uuidstring文件 uuid，必填
    userstring用户名，必填
    返回字段
    参数名类型说明
    created_utcint创建时间
    deletedint删除，0代表未删除、1代表已删除
    filenamestring文件名
    parsedint-1=解析异常、0=待解析、1=解析中、2=解析完毕
    updated_utcint修改时间
    uuidstring文件 id，后续用于获取结果
    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/document/<uuid>?user=pdflux"
    示例 - 请求获取
    GET https://saas.pdflux.com/api/vl/saas/document/<uuid>?_timestamp=1590560297&_token=bf5bd348e4a414be0aa57899878bd66c&user=pdflux
    示例 - 返回结果
    {
  data: {
    created_utc: 1534819038,
    deleted: 0,
    filename: 'xxx.pdf',
    id: 8,
    parsed: 1,
    updated_utc: 1534820149,
    uuid: 'b5a95e7a-a4ed-11e8-8a4f-8c8590cb4e8f',
  },
  errcode: 0,
  msg: null,
  status: true,
}

  • 获取文档解析结果

    接口地址
    /api/v1/saas/document/<uuid>/pdftables?user=####
    请求类型
    GET
    请求参数
    参数名类型说明
    uuidstring文件 uuid，必填
    userstring用户名，必填
    解析结果中的部分字段含义
    参数名类型说明
    paragraphsstring段落元素块
    tablesstring表格元素块
    imagesstring图片元素块
    page_headerstring页眉元素块
    page_footerstring页脚元素块

    *更多字段说明见结果示例及注释

    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/document/<uuid>/pdftables?user=pdflux"
    示例 - 请求获取
    GET https://saas.pdflux.com/api/v1/saas/document/<uuid>/pdftables?_timestamp=1590562575&_token=bc62219c497be230697368b87930eb33&user=pdflux
    示例 - 返回结果
    {
  "document": [
      {
        "id": 2022,
        "uuid": "2afdca4a-5c65-11eb-a1f8-00163e055917", // 文件uuid
        "parsed": 2,
        "filename": "中国广核电力股份有限公司主体与2019年度第一期中期票据信用评级报告（中诚信国际）.pdf", // 文件名
        "created_utc": 1611287515, // 创建时间
        "updated_utc": 1611287688, // 修改事件
        "exceptions": null // 报错信息
      }
  ],
  "pdf_page": [
      {
        "id": 10379,
        "did": 2022,
        "page": 0, // 页面序号、页码
        "meta": {
          "width": 595, // 页面宽度
          "height": 842, // 页面高度
          "page_file_type": null,
          "page_prob": null,
          "is_image": true // 是否是扫描件或图片
        },
        "created_utc": 1611287679,
        "updated_utc": 1611287679
      },
      ... // ...表示省略
  ],
  "pdf_elements": [
      {
        "page": 1, // 页面序号、页码
        "elements": [
          {
            "page": 1, // 页面序号、页码
            "text": "中诚信国呩 CCXI-20182331D-01", // 文字内容
            "index": 0,
            "element_file_type": "page_headers" // 元素块类型：页眉
          },
          {
            "page": 1,
            "text": "中国广核电力股份有限公司2019年度第一期中期票据信用评级报告",
            "index": 1,
            "syllabus": 1, // 和目录的对应关系
            "element_file_type": "paragraphs" // 元素块类型：段落
          },
          {
            "unit": "", // 表格单位 
            "cells": { // 表格单元格
                "0_0": { // 
                    "value": "发行主体" // 单元格内的文字内容
                },
                "0_1": { // 单元格位置信息：第一个“0”代表的是行数，第二个”0“代表的是列数，”0_0"代表第一个单元格
                    "value": "中国卜核*力股份有限公司"
                },
                ... // 表示省略
            },
            "title": "中国广核电力股份有限公司2019年度第一期中期票据信用评级报告",
            "merged": [ // 单元格合并信息
                [
                    [0,1],[0,2],[0,3],[0,4] // 表示这4个单元格合并
                ],
                [
                    [1,1],[1,2],[1,3],[1,4] // 表示这4个单元格合并
                ],
                ... // 表示省略
            ],
            "element_file_type": "tables", // 元素块类型：表格
            "page": 1, // 页码
            "index": 2 // 在页面中出现的顺序
        },
        {
            "page": 1,
            "text": "www.ccxi.com.cn 中国广核电力股份有限公司2019年度第一期中期票据信用评级报告",
            "index": 3,
            "element_file_type": "page_footers" // 元素块类型：页脚
          }
        ]
      },
      {
        "page": 2,
        "elements": [
            {
                "data": "iVBORw0KGgoA......", // 图片内容，Base64格式
                "page": 2, // 页码
                "index": 0, // 在页面中出现的顺序
                "element_file_type": "images"  // 元素块类型：图片
            },
            {
                "page": 2,
                "text": "关 注",
                "index": 1,
                "element_file_type": "paragraphs",
            },
            ...
        ]
    },
  ...
  ],
  "syllabus": { // 目录
      "index": -1, // 目录根节点 
      "children": [ // 子节点
          {
            "page": 1, // 页码
            "efile_type": "paragraphs", 
            "index": 1, // 目录序号 
            "level": 1, // 目录层级
            "range": [ // 当前目录包含的元素块
                1,10
            ],
            "title": "中国广核电力股份有限公司2019年度第一期中期票据信用评级报告", // 目录标题 
            "parent": -1, // 父节点
            "element": 1, // 目录与元素块的对应关系
            "children": [ // 子节点
              {
                "page": 2,
                "efile_type": "paragraphs",
                "index": 2,
                "level": 2,
                "range": [
                    5,10
                ],
                "title": "关 注",
                "parent": 1,
                "element": 5,
                "children": []
              }
            ]
          },
          {
            "page": 3,
            "efile_type": "paragraphs",
            "index": 3,
            "level": 1,
            "range": [
                10,20
            ],
            "title": "声明",
            "parent": -1,
            "element": 10,
            "children": []
          },
          ...
      ]
    }
}

  • 下载结果 - Excel

    接口地址
    /api/v1/saas/document/<uuid>/excel?user=####
    请求类型
    GET
    请求参数
    参数名类型说明
    uuidstring文件 uuid，必填
    userstring用户名，必填
    返回字段

    返回内容为 excel 文件

    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/document/<uuid>/excel?user=pdflux"
    示例 - 请求下载
    GET https://saas.pdflux.com/api/v1/saas/document/<uuid>/excel?_timestamp=1590562650&_token=1a014dbd2c719cea3ed04f249b50e39e&user=pdflux

  • 下载结果 - HTML

    接口地址
    /api/v1/saas/document/<uuid>/html?user=####
    请求类型
    GET
    请求参数
    参数名类型说明
    uuidstring文件 uuid，必填
    userstring用户名，必填
    返回字段

    返回内容为 html 文件

    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/document/<uuid>/html?user=pdflux"
    示例 - 请求下载
    GET https://saas.pdflux.com/api/v1/saas/document/<uuid>/html?_timestamp=1590562650&_token=1a014dbd2c719cea3ed04f249b50e39e&user=pdflux

  • 发起OCR解析

    发起OCR解析是为了获取PDFlux中FinOCR的OCR识别结果，结果格式为Json，内容为每个字的字符内容和字符位置。

    接口地址
    /api/v1/saas/ocr-parse?user=###
    请求类型
    POST
    请求参数
    参数名类型说明
    filefile待解析的文档，必填
    userstring用户名，必填
    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/ocr-parse?user=pdflux"
    示例 - 返回结果
    {
  "data": {
      "checksum": "401ca19386a424380d6c67d9879fba03",  // 文件校验和
      "created_utc": 1676449866,  // 上传时间
      "deleted": 0,
      "exceptions": null,
      "filename": "普联软件.PDF",  // 文件名称
      "filepath": "普联软件.PDF",
      "id": 4156,  // 文件ID
      "parsed": 1,  // 解析状态
      "pfb_pushed_status": null,
      "type": 3,
      "uid": -2,  // 上传用户ID
      "updated_utc": 1676449866, // 更新时间
      "uuid": "16fed1e4-ad0b-11ed-917c-0242c0a83002"  // 文件uuid
  },
  "errcode": 0,
  "msg": null,
  "status": true
}

  • 获取OCR解析结果

    接口地址
    /api/v1/saas/document/<uuid>/ocr-parse?user=###
    请求类型
    GET
    请求参数
    参数名类型说明
    uuidstring文件 uuid，必填
    示例 - 获取Token
    python3 get_token.py "https://saas.pdflux.com/api/v1/saas/document/<uuid>/ocr-parse?user=pdflux"
    示例 - 请求下载OCR结果
    GET https://saas.pdflux.com/api/v1/saas/document/f97bcec6-5a5b-11ed-ab30-0242c0a83002/ocr-parse?_timestamp=1667359271&_token=766d76096d98bdad98015822ea7e7eca&user=pdflux