• API 功能

    • 识别增值税发票、餐饮小票与购物小票,返回逐张票据结果;
    • 支持公开 HTTPS 图片地址,也可通过文件流上传 PNG 或 JPEG 图片;
    • 单张票据可选择 single 模式,保留完整图片中的文字与字段证据;
    • auto 模式支持深色背景上完整分离的浅色票据,最多 5 张;
    • 返回票据边界与文字行坐标,便于对照原图核验;
    • 按可识别证据抽取日期、金额、发票及购销方等字段,缺失字段不补造;
    • 字段附带原始文字、置信度和对应文字行,便于业务复核;
    • 对缺失、冲突与低置信度结果标记待复核,不替代人工审核或发票查验;
    • 图片不超过 10 MiB、1,200 万像素,最长边不超过 6,000 像素;
    • 服务繁忙时返回 429,请降低并发后重试,更高处理量需先联系确认。
  • API 文档

    接口地址: https://api.gugudata.com/ai/receipt-recognition

    返回格式: application/json; charset=utf-8

    请求方式: POST

    请求协议: HTTPS

    请求示例: https://api.gugudata.com/ai/receipt-recognition

    数据预览: https://www.gugudata.com/preview/receipt-recognition

    接口测试:  https://api.gugudata.com/ai/receipt-recognition/demo

    OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

    请求参数(POST 请求体使用 application/json,仅包含 imageurl 和 mode;AppKey 仅通过 X-AppKey 请求头传递)

    参数名 参数类型 是否必须 默认值 备注
    X-AppKey string 是 YOUR_APPKEY HTTP 请求头;仅使用票据识别产品的 APPKEY,不支持 Query、Body 或 Bearer。
    imageurl string 是 https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png 公开 HTTPS PNG 或 JPEG 图片地址,不支持重定向或私网;JSON 模式必填。
    mode string 否 auto auto 或 single,服务默认 auto;演示样例使用 single。文件上传请使用 multipart/form-data 的 image 与 mode,不与 imageurl 混用。

    返回参数

    参数名 参数类型 备注
    DataStatus.StatusCode integer 成功为 100;业务错误码与 HTTP 状态分别判断。
    DataStatus.RequestParameter string 正式请求仅返回 mode,不回显用户图片地址;固定 Demo 返回公开样例 imageurl 与 mode。
    DataStatus.StatusDescription string 请求处理说明。
    DataStatus.RequestId string 请求 UUID,与 Data.request_id 和 X-Request-ID 响应头一致。
    DataStatus.DataTotalCount integer 成功时为票据数量,失败时为 0。
    Data.request_id string 本次请求 UUID。
    Data.status string complete 或 needs_review;成功不表示字段已通过人工或税务核验。
    Data.image object 原始图片 width、height。
    Data.receipts array 逐张票据结果。
    Data.receipts[].receipt_index integer 当前图片内的票据序号,从 1 开始。
    Data.receipts[].receipt_type string vat_invoice、restaurant_receipt、shopping_receipt 或 unknown。
    Data.receipts[].polygon array 票据在原图中的多边形坐标。
    Data.receipts[].fields object 仅包含有证据且可解析的字段,不保证所有字段存在。
    Data.receipts[].fields.*.value string 标准化字段值;金额为十进制字符串。
    Data.receipts[].fields.*.raw_text string 提取字段的原始文字证据。
    Data.receipts[].fields.*.line_indices array 证据在本张票据 lines 中的零基索引。
    Data.receipts[].fields.*.confidence number OCR 证据置信度,不是字段正确率。
    Data.receipts[].lines array 文字行 text、confidence 与原图 polygon。
    Data.receipts[].needs_review boolean 是否需要人工复核。
    Data.receipts[].warnings array 本张票据的缺失、冲突或识别警告。
    Data.warnings array 图片级处理警告。

    响应示例(真实数据节选)

    接口数据预览

    仅展示部分示例数据,数组最多展示 3 项,长内容已省略;完整数据请调用接口获取。

    {
      "DataStatus": {
        "RequestParameter": "imageurl=https%3A%2F%2Fstatic.gugudata.com%2Fdemo%2Freceipt-recognition%2Fv1%2Finput.ade755a263c27a1f2246.png&mode=single",
        "StatusCode": 100,
        "StatusDescription": "固定示例识别结果,请核对原始图片。",
        "ResponseDateTime": "2026-10-24 02:57:52.289",
        "DataTotalCount": 1,
        "RequestId": "f1bc1930-afec-4f98-bad3-186d817e2a56"
      },
      "Data": {
        "status": "needs_review",
        "receipts": [
          {
            "fields": {
              "date": {
                "confidence": 0.99983,
                "line_indices": [
                  3
                ],
                "raw_text": "开票日期:2016年01月06日",
                "value": "2016-01-06"
              },
              "total_amount": {
                "confidence": 0.9921,
                "line_indices": [
                  37,
                  40
                ],
                "raw_text": "价税合计(大写)\n(小写)¥1.00",
                "value": "1.00"
              }
            },
            "lines": [
              {
                "confidence": 0.9938,
                "polygon": [
                  [
                    856.0,
                    16.0
                  ],
                  [
                    942.0,
                    16.0
                  ],
                  [
                    942.0,
                    43.0
                  ]
                ],
                "text": "发票代码:"
              },
              {
                "confidence": 0.99093,
                "polygon": [
                  [
                    388.0,
                    38.0
                  ],
                  [
                    828.0,
                    38.0
                  ],
                  [
                    828.0,
                    83.0
                  ]
                ],
                "text": "广东增值税电子普通发票"
              },
              {
                "confidence": 0.99091,
                "polygon": [
                  [
                    856.0,
                    49.0
                  ],
                  [
                    942.0,
                    49.0
                  ],
                  [
                    942.0,
                    76.0
                  ]
                ],
                "text": "发票号码:"
              }
            ],
            "needs_review": true,
            "polygon": [
              [
                0.0,
                0.0
              ],
              [
                1195.0,
                0.0
              ],
              [
                1195.0,
                759.0
              ]
            ],
            "receipt_index": 1,
            "receipt_type": "vat_invoice",
            "warnings": [
              "invalid_invoice_code",
              "invalid_invoice_number",
              "invalid_tax_amount"
            ]
          }
        ],
        "warnings": [],
        "image": {
          "height": 760,
          "width": 1196
        },
        "request_id": "f1bc1930-afec-4f98-bad3-186d817e2a56"
      }
    }
  • 鉴权方式

    本接口仅接受 X-AppKey 请求头。查询参数与 JSON 请求体不接受 AppKey。

    传输载体参数示例说明
    HTTP HeaderX-AppKeyX-AppKey: YOUR_APPKEY必填,请使用当前产品的 AppKey。

    票据识别的处理量需按实际响应控制;如需更高处理量,请先联系确认。

  • 接口常见 HTTP 响应状态码

    以下为接口调用中常见的 HTTP 传输层状态码,不等同于响应体内的业务状态码;完整状态码注册表以 IANA HTTP Status Code Registry 为准。

    状态码 状态码解释 备注
    200 请求成功 HTTP 请求已成功处理;业务状态请结合响应体中的自定义业务码判断。
    201 资源已创建 创建类接口请求成功,并已生成对应资源。
    202 请求已接受 请求已被接受处理,结果可能异步完成。
    204 无响应内容 请求成功但响应体为空,适用于无需返回数据的操作。
    400 请求参数错误 请求参数缺失、格式错误或参数组合不合法。
    401 认证失败 缺少、无效或未通过认证的访问凭证(如 AppKey)。
    403 无权限访问 订单到期、权限不足或接口额度不可用。
    404 资源不存在 请求路径不存在。
    405 请求方法不允许 当前路径不支持该 HTTP 方法。
    408 请求超时 客户端请求在服务端等待时间内未完成,可稍后重试。
    409 请求冲突 请求与当前资源状态冲突,调整参数或业务状态后重试。
    413 请求内容过大 上传文件或请求体超过接口限制。
    414 请求地址过长 请求 URL 超过服务端可处理长度,建议减少查询参数或改用 POST。
    415 请求内容类型不支持 上传或请求体的内容类型不符合接口要求。
    422 请求语义错误 请求格式正确,但参数取值、语义或业务约束无法处理。
    429 请求频率或处理容量受限 请降低并发并稍后重试;如需更高处理量,请先联系确认。
    431 请求头过大 请求头字段过大或过多,建议精简 Header 后重试。
    500 服务器内部错误 服务端处理异常,请稍后重试。
    502 服务暂时不可用 请稍后重试。
    503 服务暂时不可用 请稍后重试。
    504 请求超时 请稍后重试。
  • 接口自定义业务状态码

    业务状态码 业务状态码解释 备注
    100 成功 HTTP 200;仍需检查 needs_review 与 warnings。
    501 参数或图片不可处理 HTTP 400、408、413、422;根据错误说明修正。
    502 请求频率或处理容量受限 HTTP 429,按 Retry-After 降低并发重试。
    503 订单已到期 HTTP 403。
    504 凭据无效或未开通票据识别权限 HTTP 401;仅 X-AppKey 请求头。
    505 调用额度耗尽 HTTP 403。
    901 服务不可用或处理超时 HTTP 503、504。
  • 请求示例代码

    curl --location --request POST 'https://api.gugudata.com/ai/receipt-recognition' \
    --header 'X-AppKey: YOUR_APPKEY' \
    --header 'Content-Type: application/json' \
    --data '{"imageurl":"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png","mode":"single"}'
    #include <curl/curl.h>
    
    int main(void) {
      CURL *curl = curl_easy_init();
      if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/ai/receipt-recognition");
        curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/json");
        headers = curl_slist_append(headers, "X-AppKey: YOUR_APPKEY");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}");
        CURLcode res = curl_easy_perform(curl);
        (void)res;
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
      }
      return 0;
    }
    
    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Net.Http;
    using System.Text;
    
    var client = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Post, "https://api.gugudata.com/ai/receipt-recognition");
    request.Headers.Add("X-AppKey", "YOUR_APPKEY");
    request.Content = new StringContent("{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}", Encoding.UTF8, "application/json");
    var response = client.SendAsync(request).Result;
    Console.WriteLine(response.Content.ReadAsStringAsync().Result);
    
    package main
    
    import (
      "strings"
      "fmt"
      "io"
      "net/http"
    )
    
    func main() {
      url := "https://api.gugudata.com/ai/receipt-recognition"
      payload := strings.NewReader("{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}")
      req, err := http.NewRequest("POST", url, payload)
      if err != nil {
        fmt.Println(err)
        return
      }
      req.Header.Set("X-AppKey", "YOUR_APPKEY")
      req.Header.Add("Content-Type", "application/json")
      res, err := http.DefaultClient.Do(req)
      if err != nil {
        fmt.Println(err)
        return
      }
      defer res.Body.Close()
      body, err := io.ReadAll(res.Body)
      if err != nil {
        fmt.Println(err)
        return
      }
      fmt.Println(string(body))
    }
    
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}");
    Request request = new Request.Builder()
      .url("https://api.gugudata.com/ai/receipt-recognition")
      .addHeader("X-AppKey", "YOUR_APPKEY")
      .method("POST", body)
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
    
    $.ajax({
      url: "https://api.gugudata.com/ai/receipt-recognition",
      method: "POST",
      headers: { "X-AppKey": "YOUR_APPKEY" },
      contentType: "application/json",
      data: JSON.stringify({"imageurl":"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png","mode":"single"}),
    }).done(function (response) {
      console.log(response);
    });
    
    const https = require("node:https");
    const url = "https://api.gugudata.com/ai/receipt-recognition";
    const body = JSON.stringify({"imageurl":"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png","mode":"single"});
    
    const request = https.request(url, {
      method: "POST",
      headers: {
        "X-AppKey": "YOUR_APPKEY",
        "Content-Type": "application/json",
        "Content-Length": Buffer.byteLength(body)
      }
    }, handleResponse);
    request.on("error", console.error);
    request.write(body);
    request.end();
    
    function handleResponse(response) {
      const chunks = [];
      response.on("data", function (chunk) {
        chunks.push(chunk);
      });
      response.on("end", function () {
        console.log(Buffer.concat(chunks).toString("utf8"));
      });
    }
    
    #import <Foundation/Foundation.h>
    
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.gugudata.com/ai/receipt-recognition"]];
    [request setHTTPMethod:@"POST"];
    [request setValue:@"YOUR_APPKEY" forHTTPHeaderField:@"X-AppKey"];
    NSString *body = @"{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}";
    [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [request setHTTPBody:[body dataUsingEncoding:NSUTF8StringEncoding]];
    NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
      if (error) {
        NSLog(@"%@", error);
        return;
      }
      NSLog(@"%@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
    }];
    [task resume];
    
    <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.gugudata.com/ai/receipt-recognition",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => "{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}",
      CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json",
        "X-AppKey: YOUR_APPKEY",
      ),
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
    
    import requests
    import json
    
    url = "https://api.gugudata.com/ai/receipt-recognition"
    headers = { "X-AppKey": "YOUR_APPKEY" }
    payload = json.loads('{"imageurl":"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png","mode":"single"}')
    response = requests.post(url, json=payload, headers=headers)
    print(response.text)
    
    require "uri"
    require "net/http"
    
    url = URI("https://api.gugudata.com/ai/receipt-recognition")
    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true
    request = Net::HTTP::Post.new(url)
    request["X-AppKey"] = "YOUR_APPKEY"
    request["Content-Type"] = "application/json"
    request.body = "{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}"
    response = https.request(request)
    puts response.read_body
    
    import Foundation
    
    let semaphore = DispatchSemaphore(value: 0)
    var request = URLRequest(url: URL(string: "https://api.gugudata.com/ai/receipt-recognition")!, timeoutInterval: .infinity)
    request.httpMethod = "POST"
    request.addValue("YOUR_APPKEY", forHTTPHeaderField: "X-AppKey")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = "{\"imageurl\":\"https://static.gugudata.com/demo/receipt-recognition/v1/input.ade755a263c27a1f2246.png\",\"mode\":\"single\"}".data(using: .utf8)
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      defer { semaphore.signal() }
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
    }
    task.resume()
    semaphore.wait()
    
  • 常见问题 Q&A

    • Q: 是否支持发票真伪查验?

      A: 不支持。本接口提取图片文字与票据字段,不连接税务查验系统;入账、报销等关键内容须人工核验。

    • Q: 如何使用多张票据?

      A: auto 模式适用于深色背景上完整分离的浅色票据,最多 5 张。重叠、裁切、复杂背景或无法可靠分区时,请拆分为单张并使用 single 模式。

    • Q: 为什么成功响应仍标记 needs_review?

      A: 成功表示完成识别处理。字段缺失、金额冲突、低置信度或未知票种仍需复核,不应直接作为自动报销或入账依据。

    • Q: 预览中的图片是什么?

      A: 公开历史增值税发票样例,经标识遮盖后展示;图片来源及许可见预览页。固定演示结果由同一识别流程生成,不代表所有票据的识别效果。

    • Q: 如何完成第一次 API 调用?

      A: 先确认当前接口的请求方法、必填参数和成功状态,再使用对应产品的 AppKey 发起请求;以实际响应中的业务状态判断结果。 查看接入指南

    • Q: 如何保证请求时 AppKey 的安全性?

      A: 在开发者中心的 APP KEY 管理页面复制对应产品的 AppKey,并保存在服务端环境变量或密钥管理服务中。不要写入网页、App 客户端、公开仓库或日志。

    • Q: 接口可以用于哪些开发语言?

      A: Java、Python、Node.js、PHP、Go、C#、Swift、Kotlin 等支持 HTTP 请求的语言均可接入;也可以通过 OpenAPI、Postman 或 Apifox 查看和调试接口。

    • Q: 请求失败或超时后可以重试吗?

      A: 先区分 HTTP 状态与业务错误。参数、鉴权和权限错误应修正后再请求;超时并不表示服务端未执行,重试前需确认接口是否会重复计费或产生副作用。 查看接入指南

    • Q: 接口的性能可以保证吗?

      A: 实际响应时间受接口类型、参数和网络环境影响。请按当前套餐的 QPS 控制并发,生产接入前完成联调与容量评估。

  • 服务协议与免责声明

    购买或使用 GuGuData API 服务前,请充分阅读服务协议、免责声明与数据合规声明。相关页面均支持在浏览器中快速导出 PDF,便于内部归档、评审和合规留存。

  • 技术支持

    技术支持邮箱:
    support@gugudata.com
    企业微信客服:
    联系客服
  • 专业软件开发与系统工程服务

    GuGuData 官方认证工程合作伙伴,专注企业级数据接口集成、AI 工程化与大规模数据处理。团队深度理解 GuGuData 数据接口体系,具备海量数据采集、治理、检索与高并发接口服务经验,可围绕业务场景构建 AI Agent、MCP 接入、智能工作流和生产级数据应用,让数据能力稳定进入现有流程、内部平台和核心业务系统。

    了解工程服务