上传文件 Try it ↗

POST /api/upload/file

上传文件，返回 fileId 供创建下发单时引用（如营业执照、身份证件等）。

所需权限： files:write

请求头：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx
Content-Type: multipart/form-data
x-file-size: <文件字节数>

请求正文： multipart/form-data，字段名为 file。

响应正文 (Body)

{
  "success": true,
  "data": {
    "fileId": "d4e5f6a7-b8c9-0123-def0-1234567890ab"
  }
}

返回的 fileId 可在创建下发单时的收款方附件字段中引用。

错误响应

// 400 — 请求内容不正确
{ "success": false, "message": "请求内容不正确" }

// 401
{ "success": false, "message": "未授权" }

// 403
{ "success": false, "message": "权限不足" }

示例代码

curl

curl -X POST "https://YOUR_API_ENDPOINT/api/upload/file" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-file-size: 204800" \
  -F "file=@/path/to/document.pdf"

Java

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.UUID;

public class UploadFile {
    public static void main(String[] args) throws IOException, InterruptedException {
        String apiEndpoint = "YOUR_API_ENDPOINT";
        String apiKey = "YOUR_API_KEY";
        Path filePath = Path.of("/path/to/document.pdf");

        byte[] fileBytes = Files.readAllBytes(filePath);
        String boundary = UUID.randomUUID().toString();
        String fileName = filePath.getFileName().toString();

        // 构造 multipart body
        String lineEnd = "\r\n";
        StringBuilder sb = new StringBuilder();
        sb.append("--").append(boundary).append(lineEnd);
        sb.append("Content-Disposition: form-data; name=\"file\"; filename=\"")
          .append(fileName).append("\"").append(lineEnd);
        sb.append("Content-Type: application/octet-stream").append(lineEnd);
        sb.append(lineEnd);

        byte[] header = sb.toString().getBytes();
        byte[] footer = (lineEnd + "--" + boundary + "--" + lineEnd).getBytes();
        byte[] body = new byte[header.length + fileBytes.length + footer.length];
        System.arraycopy(header, 0, body, 0, header.length);
        System.arraycopy(fileBytes, 0, body, header.length, fileBytes.length);
        System.arraycopy(footer, 0, body, header.length + fileBytes.length, footer.length);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://" + apiEndpoint + "/api/upload/file"))
            .header("x-api-key", apiKey)
            .header("x-file-size", String.valueOf(fileBytes.length))
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .POST(HttpRequest.BodyPublishers.ofByteArray(body))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("Status: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
}

Python

import os
import uuid
from urllib.request import Request, urlopen

api_endpoint = "YOUR_API_ENDPOINT"
api_key = "YOUR_API_KEY"
file_path = "/path/to/document.pdf"

file_size = os.path.getsize(file_path)
file_name = os.path.basename(file_path)
boundary = uuid.uuid4().hex

with open(file_path, "rb") as f:
    file_data = f.read()

# 构造 multipart body
body = (
    f"--{boundary}\r\n"
    f'Content-Disposition: form-data; name="file"; filename="{file_name}"\r\n'
    f"Content-Type: application/octet-stream\r\n"
    f"\r\n"
).encode("utf-8") + file_data + f"\r\n--{boundary}--\r\n".encode("utf-8")

req = Request(
    f"https://{api_endpoint}/api/upload/file",
    data=body,
    headers={
        "x-api-key": api_key,
        "x-file-size": str(file_size),
        "Content-Type": f"multipart/form-data; boundary={boundary}",
    },
    method="POST",
)

with urlopen(req) as resp:
    print(f"Status: {resp.status}")
    print(f"Body: {resp.read().decode('utf-8')}")

PHP

<?php
$apiEndpoint = "YOUR_API_ENDPOINT";
$apiKey      = "YOUR_API_KEY";
$filePath    = "/path/to/document.pdf";

$fileSize = filesize($filePath);
$cfile    = new CURLFile($filePath, "application/octet-stream", basename($filePath));

$ch = curl_init("https://{$apiEndpoint}/api/upload/file");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "x-api-key: {$apiKey}",
        "x-file-size: {$fileSize}",
    ],
    CURLOPT_POSTFIELDS => ["file" => $cfile],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: {$httpCode}\n";
echo "Body: {$response}\n";

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
	"strconv"
)

func main() {
	apiEndpoint := "YOUR_API_ENDPOINT"
	apiKey := "YOUR_API_KEY"
	filePath := "/path/to/document.pdf"

	file, err := os.Open(filePath)
	if err != nil {
		panic(err)
	}
	defer file.Close()

	stat, _ := file.Stat()
	fileSize := stat.Size()

	var buf bytes.Buffer
	writer := multipart.NewWriter(&buf)
	part, err := writer.CreateFormFile("file", filepath.Base(filePath))
	if err != nil {
		panic(err)
	}
	io.Copy(part, file)
	writer.Close()

	req, err := http.NewRequest("POST", "https://"+apiEndpoint+"/api/upload/file", &buf)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", apiKey)
	req.Header.Set("x-file-size", strconv.FormatInt(fileSize, 10))
	req.Header.Set("Content-Type", writer.FormDataContentType())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Printf("Status: %d\n", resp.StatusCode)
	fmt.Printf("Body: %s\n", respBody)
}

JavaScript

const apiEndpoint = "YOUR_API_ENDPOINT";
const apiKey = "YOUR_API_KEY";

// Node.js (>= 18) 或浏览器环境
const fileBuffer = await (await import("fs/promises")).readFile("/path/to/document.pdf");
const file = new File([fileBuffer], "document.pdf", { type: "application/pdf" });

const formData = new FormData();
formData.append("file", file);

const resp = await fetch(`https://${apiEndpoint}/api/upload/file`, {
  method: "POST",
  headers: {
    "x-api-key": apiKey,
    "x-file-size": String(file.size),
  },
  body: formData,
});

console.log("Status:", resp.status);
console.log("Body:", await resp.json());