Upload CSV
Upload CSV
Get a presigned URL to upload bulk shipments via CSV
POST
Upload CSV
Bulk Shipment Upload
Upload thousands of shipments at once via a CSV file. This endpoint returns a presigned S3 URL so you can upload your file, which will be processed asynchronously.This method is recommended for bulk uploads. Shipments are persisted in the database and available for subsequent reports.
Upload Flow
Step 1: Request Presigned URL
Request
Headers
Your API key for authenticationExample:
sk_live_1234567890abcdefYour organization UUIDExample:
ff4adcc7-8172-45fe-9cf1-e90a6de53aa9Your user UUIDExample:
a1b2c3d4-e5f6-7890-abcd-ef1234567890Body Parameters
Name of the CSV file you’re going to uploadExample:
"correos_shipments_2024-11.csv"Optional: Name of the recharges/returns CSV fileExample:
"correos_returns_2024-11.csv"Response
Presigned S3 URL to upload the shipments file
File UUID (use it for tracking)
Timestamp when the URL expires (15 minutes)
Example
Successful Response
Step 2: Upload CSV to S3
Use the presigned URL to upload your CSV file directly to S3:CSV Format
The CSV must follow this structure:Required Columns
| Column | Description | Example |
|---|---|---|
client | Client name | "Correos Express" |
origin | Origin city and country | "Madrid, Spain" |
destination | Destination city and country | "Barcelona, Spain" |
toc | Transport type | "van_diesel" |
load | Transported quantity | 1000 |
load_unit | Unit of measurement | "kg" |
date | Shipment date | "2024-11-20" |
reference | Shipment reference | "REF-001" |
Download Template
Download CSV Template
Template with correct format and sample data
Step 3: Asynchronous Processing
Once the CSV is uploaded:- Validation: The system validates the format and data
- Processing: Each row is processed and emissions are calculated
- Storage: Shipments are saved in the database
- Notification: (Coming soon) You’ll receive a webhook when complete
Processing can take from a few seconds to several minutes depending on file size.
Step 4: Verify Results
After processing, you can query your data:Complete Example Script
Common Errors
400 Bad Request - Missing file_name
requests_file_name parameter in the body.
403 Forbidden - URL Expired
Cause: The presigned URL expired (15 minutes) Solution: Request a new presigned URL and upload the file immediately.422 Validation Error - CSV Format
Cause: The CSV has incorrect format or missing columns Solution: Verify that your CSV has all required columns and correct format.Limits and Recommendations
| Limit | Value |
|---|---|
| Maximum file size | 100 MB |
| Maximum rows per CSV | 50,000 |
| URL expiration time | 15 minutes |
| Processing time | ~1 second per 100 rows |
Related Endpoints
Get Clients
List your logistics clients
Get Report
Generate ISO 14083 report
Calculate Shipment
Individual calculation without persistence
Get TOCs
List transport types

