Skip to main content
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 name
2

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_1234567890abcdef
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Body 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:
The presigned URL expires in 15 minutes. Make sure to upload the file within that time.

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:
  1. Validation: The system validates the format and data
  2. Processing: Each row is processed and emissions are calculated
  3. Storage: Shipments are saved in the database
  4. 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 required
Solution: Include the 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

For very large files (>50k rows), consider splitting them into multiple smaller CSVs.

Get Clients

List your logistics clients

Get Report

Generate ISO 14083 report

Calculate Shipment

Individual calculation without persistence

Get TOCs

List transport types