配置
上传文件
向 VelaFi 上传 KYC/KYB 身份证明文件或发票文件。每次请求最多支持 5 个文件，格式为 JPG、PNG、JPEG 或 PDF。
POST
/
v2
/
base
/
file
/
upload
上传文件
curl --request POST \
--url https://api-test.velafi.com/v2/base/file/upload \
--header 'Content-Type: multipart/form-data' \
--header 'X-BH-TOKEN: <api-key>' \
--form 'businessType=<string>' \
--form files=@example-fileimport requests
url = "https://api-test.velafi.com/v2/base/file/upload"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = { "businessType": "<string>" }
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('businessType', '<string>');
form.append('files', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {'X-BH-TOKEN': '<api-key>'}};
options.body = form;
fetch('https://api-test.velafi.com/v2/base/file/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/base/file/upload")
.header("X-BH-TOKEN", "<api-key>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"businessType\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();{
"code": 123,
"msg": "<string>",
"data": [
{
"fileName": "<string>",
"fileType": "<string>",
"fileUrl": "<string>",
"tempFileUrl": "<string>"
}
]
}使用 POST
/v2/base/file/upload 端点向 VelaFi 上传文件。该端点支持上传 KYC/KYB 身份验证文件以及商户账户的发票文件。请求必须以 multipart/form-data 格式发送。单次请求最多可上传五个文件；每个文件大小必须在 10 KB 到 3 MB 之间，且为受支持的格式之一。响应会为每个已上传的文件返回一个临时签名 URL，以便您在后续 API 调用中引用该文件之前确认上传成功。
此端点需要授权。每个请求都必须包含
X-BH-TOKEN 请求头。没有有效令牌的请求将被拒绝。请求
POST /v2/base/file/upload
请求头
| 请求头 | 值 | 必填 |
|---|---|---|
X-BH-TOKEN | 通过 GET /v2/token/generate 获取的令牌 | ✓ |
Content-Type | multipart/form-data | ✓ |
请求体参数
string
必填
所上传文件的业务类型。目前固定为
FIAT_ACCOUNT。file
必填
要上传的一个或多个文件。每次请求最多 5 个文件。每个文件大小必须在 10 KB 到 3 MB 之间。支持的格式：
jpg、jpeg、png、pdf。响应字段
number
HTTP 风格的状态码。
200 表示成功。string
可读的状态消息，例如
"SUCCESS"。array
已上传文件对象的数组，每个文件对应一个条目。
显示 data[]
显示 data[]
string
上传时提供的原始文件名（例如
"id-front.jpg"）。string
已上传文件的扩展名（例如
"jpg"、"pdf"）。string
文件的相对存储路径（例如
"1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.jpg"）。在后续 API 调用中引用该文件时使用此值，例如 Pix - Woovi 渠道激活中的文件字段（govIdFrontUrl、govIdBackUrl、certificateOfIncorporationDocumentUrl、taxIdentificationDocumentUrl）。string
临时预签名 URL，可用于确认文件已正确上传。该 URL 在上传 30 分钟后过期，不应永久存储。
示例
curl --request POST \
--url 'https://api.velafi.com/v2/base/file/upload' \
--header 'X-BH-TOKEN: YOUR_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--form 'businessType=FIAT_ACCOUNT' \
--form 'files=@/path/to/id-front.jpg'
curl --request POST \
--url 'https://api.velafi.com/v2/base/file/upload' \
--header 'X-BH-TOKEN: YOUR_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--form 'businessType=FIAT_ACCOUNT' \
--form 'files=@/path/to/id-front.jpg' \
--form 'files=@/path/to/id-back.jpg'
响应
{
"code": 200,
"msg": "SUCCESS",
"data": [
{
"fileName": "id-front.jpg",
"fileType": "jpg",
"fileUrl": "1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.jpg",
"tempFileUrl": "https://chats-images-files.s3.ap.amazonaws.com/8d99-aa4788015e38.jpg?x-amz-security-token=IQoJb3JpZ2luX2VjE"
}
]
}
请保存响应中的
fileUrl 字段——这是您在 KYC/KYB 提交请求中引用的永久相对路径。tempFileUrl 是仅用于验证的短期签名 URL，会过期失效。⌘I
上传文件
curl --request POST \
--url https://api-test.velafi.com/v2/base/file/upload \
--header 'Content-Type: multipart/form-data' \
--header 'X-BH-TOKEN: <api-key>' \
--form 'businessType=<string>' \
--form files=@example-fileimport requests
url = "https://api-test.velafi.com/v2/base/file/upload"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = { "businessType": "<string>" }
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('businessType', '<string>');
form.append('files', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {'X-BH-TOKEN': '<api-key>'}};
options.body = form;
fetch('https://api-test.velafi.com/v2/base/file/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/base/file/upload")
.header("X-BH-TOKEN", "<api-key>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"businessType\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();{
"code": 123,
"msg": "<string>",
"data": [
{
"fileName": "<string>",
"fileType": "<string>",
"fileUrl": "<string>",
"tempFileUrl": "<string>"
}
]
}