Synchronous Upload

• Regular Upload Interface: Returns immediately after uploading the file, requires subsequent querying of processing results through the /file/fetch interface
• Synchronous Upload Interface: Waits for processing to complete after uploading the file, directly returns complete processing results without additional queries

​

01 Upload Single File Synchronously

curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "file=@/path/to/your/file.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload/sync?workspace_id=<your-workspace-id>"

​

02 Upload Multiple Files Synchronously

curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "file=@/path/to/1.pdf" \
  -F "file=@/path/to/2.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload/sync?workspace_id=<your-workspace-id>&batch_number=202412190001"

​

03 Upload via URL Synchronously

curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/document.pdf"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload/sync?workspace_id=<your-workspace-id>"

​

04 Parameter Description

​

Required Parameters

• workspace_id: Workspace ID. You can refer to the Get Workspace ID documentation.

​

Optional Parameters

• category: File category (e.g., invoice)
• batch_number: Batch number, automatically generated by the system if not provided
• auto_verify_vat: Whether to enable invoice verification, default false
• split_flag: Whether to perform file splitting, default false (see File Splitting section)
• crop_flag: Whether to perform multi-image cropping, default false (see Multi-image Cropping section)
• target_process: Target processing type, optional classify or extract.
  Docflow will perform the complete process of parsing->classification->extraction by default. When target_process is classify, the process ends after classification

​

Request Body Parameters

1. File Upload: Use multipart/form-data format, field name is file (can be repeated multiple times)
2. URL Upload: Use application/json format, contains urls array (up to 10 URLs)

​

05 Response Format

{
   "code": 200,
   "msg": "Success",
   "result": {
      "total": 1,
      "page": 1,
      "page_size": 20,
      "files": [
         {
            "id": "1955840505753140508",
            "task_id": "1955840505753140509",
            "task_type": 1,
            "batch_number": "202412190001",
            "name": "invoice.pdf",
            "format": "pdf",
            "recognition_status": 1,
            "verification_status": 0,
            "category": "invoice",
            "pages": [
               {
                  "page": 0,
                  "angle": 0,
                  "width": 1024,
                  "height": 1448,
                  "dpi": 144
               }
            ],
            "data": {
               "fields": [
                  {
                     "key": "Invoice Code",
                     "identifier": "Invoice Code Identifier",
                     "value": "3100231130",
                     "position": [
                        {
                           "page": 0,
                           "vertices": [100, 200, 300, 200, 300, 250, 100, 250]
                        }
                     ]
                  },
                  {
                     "key": "Invoice Number",
                     "identifier": "Invoice Number Identifier",
                     "value": "28737000",
                     "position": [
                        {
                           "page": 0,
                           "vertices": [350, 200, 500, 200, 500, 250, 350, 250]
                        }
                     ]
                  }
               ],
               "items": [],
               "tables": [],
               "stamps": [],
               "handwritings": []
            },
            "duration_ms": 5000
         }
      ]
   }
}

• result.files[]: File list, each file contains complete processing results
• result.files[].data.fields[]: Extracted field list
• result.files[].data.items[]: Table data list
• result.files[].data.tables[]: All table data list
• result.files[].data.stamps[]: Stamp information
• result.files[].data.handwritings[]: Handwriting information
• result.files[].recognition_status: Recognition status (1 indicates success)
• result.files[].duration_ms: Processing time (milliseconds)

​

06 Use Cases

​

Scenarios Suitable for Synchronous Upload

• Scenarios that require immediate access to processing results
• Single file or small number of files processing
• File processing time is short (usually seconds to tens of seconds)
• Simplify code logic, avoid polling queries

​

Scenarios Not Suitable for Synchronous Upload

• Batch processing of large numbers of files
• File processing time is long (exceeding 1 minute)
• Scenarios requiring asynchronous processing
• Unstable network or scenarios requiring resumable uploads

​

07 Notes

1. Timeout Settings: The synchronous upload interface needs to wait for processing to complete. It is recommended to set a longer timeout (at least 300 seconds)
2. Processing Time: Processing time depends on file size, number of pages, and complexity. Large files may require longer processing time
3. Error Handling: If processing fails, the response will contain error information. recognition_status of 2 indicates failure
4. Batch Processing: When uploading multiple files at once, it will wait for all files to be processed, which may result in longer total processing time
5. Network Stability: Since a long connection needs to be maintained, ensure network connection stability