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
1
Request presigned URL
Make a POST request to
/api/v1/logistics/presigned_url with your file name2
Upload to S3
Use the presigned URL to upload your CSV directly to S3 (PUT request)
3
Asynchronous processing
The system processes your file in the background and calculates emissions
4
Verify results
Check your clients and reports with the listing endpoints
Step 1: Request Presigned URL
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
ff4adcc7-8172-45fe-9cf1-e90a6de53aa9string
required
Your user UUIDExample:
a1b2c3d4-e5f6-7890-abcd-ef1234567890Body Parameters
string
required
Name of the CSV file you’re going to uploadExample:
"correos_shipments_2024-11.csv"string
Optional: Name of the recharges/returns CSV fileExample:
"correos_returns_2024-11.csv"Response
string
Presigned S3 URL to upload the shipments file
string
File UUID (use it for tracking)
string
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
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
Cause: requests_file_name is requiredrequests_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
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