AUTHENTICATION
CARGO MANAGEMENT
PASSPORT MANAGEMENT
Welcome to the Cargo Poster API documentation. Our API provides programmatic access to manage cargo shipments, passports, and track deliveries efficiently.
https://cargoposter.com
Most endpoints require authentication using Bearer tokens. Make sure to include your token in the Authorization header.
Authenticate a user and receive an access token for API requests.
/api/auth/login
{
"email": "user@example.com",
"password": "your_password"
}{
"user": {
"id": 1,
"email": "user@example.com",
"name": "John Doe"
},
"token": "your_access_token_here"
}Retrieve a list of all cargo shipments for the authenticated user.
/api/cargos
Authorization: Bearer your_access_token_here
Content-Type: application/json{
"data": [
{
"id": 1,
"title": "Electronics Shipment",
"weight": 1500,
"volume": 2.5,
"pickup_location": "Vilnius, Lithuania",
"delivery_location": "Berlin, Germany",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z"
}
],
"meta": {
"current_page": 1,
"total": 10,
"per_page": 15
}
}Retrieve details of a specific cargo shipment by ID.
/api/cargos/{id}
Authorization: Bearer your_access_token_here
Content-Type: application/jsonid (integer, required): The ID of the cargo to retrieve{
"data": {
"id": 1,
"title": "Electronics Shipment",
"description": "Laptops and mobile phones",
"weight": 1500,
"volume": 2.5,
"pickup_location": "Vilnius, Lithuania",
"pickup_date": "2024-02-01",
"delivery_location": "Berlin, Germany",
"delivery_date": "2024-02-03",
"status": "pending",
"cargo_type": {
"id": 1,
"name": "Electronics"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}Create a new cargo shipment.
/api/cargos
Authorization: Bearer your_access_token_here
Content-Type: application/json{
"title": "Electronics Shipment",
"description": "Laptops and mobile phones",
"weight": 1500,
"volume": 2.5,
"pickup_location": "Vilnius, Lithuania",
"pickup_date": "2024-02-01",
"delivery_location": "Berlin, Germany",
"delivery_date": "2024-02-03",
"cargo_type_id": 1
}{
"data": {
"id": 1,
"title": "Electronics Shipment",
"description": "Laptops and mobile phones",
"weight": 1500,
"volume": 2.5,
"pickup_location": "Vilnius, Lithuania",
"delivery_location": "Berlin, Germany",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z"
}
}Update an existing cargo shipment by its ID.
/api/cargos/{id}
Authorization: Bearer your_access_token_here
Content-Type: application/jsonid (required): The unique identifier of the cargo to update{
"title": "Updated Electronics Shipment",
"description": "Updated laptops and mobile phones",
"weight": 1600,
"volume": 2.8,
"pickup_location": "Vilnius, Lithuania",
"pickup_date": "2024-02-02",
"delivery_location": "Hamburg, Germany",
"delivery_date": "2024-02-05",
"cargo_type_id": 1
}{
"data": {
"id": 1,
"title": "Updated Electronics Shipment",
"description": "Updated laptops and mobile phones",
"weight": 1600,
"volume": 2.8,
"pickup_location": "Vilnius, Lithuania",
"delivery_location": "Hamburg, Germany",
"status": "pending",
"updated_at": "2024-01-15T11:45:00Z"
}
}404 Not Found:
{
"message": "Cargo not found"
}
422 Validation Error:
{
"message": "The given data was invalid.",
"errors": {
"title": ["The title field is required."],
"weight": ["The weight must be a positive number."]
}
}Retrieve a list of all passports for cargo tracking.
/api/passports
Authorization: Bearer your_access_token_here
Content-Type: application/json{
"data": [
{
"id": 1,
"passport_number": "PS001234",
"cargo_id": 1,
"status": "active",
"issued_date": "2024-01-15",
"expiry_date": "2024-12-31",
"created_at": "2024-01-15T10:30:00Z"
}
],
"meta": {
"current_page": 1,
"total": 5,
"per_page": 15
}
}Retrieve details of a specific passport by ID.
/api/passports/{id}
Authorization: Bearer your_access_token_here
Content-Type: application/jsonid (integer, required): The ID of the passport to retrieve{
"data": {
"id": 1,
"passport_number": "PS001234",
"cargo_id": 1,
"status": "active",
"issued_date": "2024-01-15",
"expiry_date": "2024-12-31",
"notes": "Special handling required",
"cargo": {
"id": 1,
"title": "Electronics Shipment",
"weight": 1500,
"volume": 2.5
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}Create a new passport for cargo tracking.
/api/passports
Authorization: Bearer your_access_token_here
Content-Type: application/json{
"cargo_id": 1,
"passport_number": "PS001234",
"issued_date": "2024-01-15",
"expiry_date": "2024-12-31",
"notes": "Special handling required"
}{
"data": {
"id": 1,
"passport_number": "PS001234",
"cargo_id": 1,
"status": "active",
"issued_date": "2024-01-15",
"expiry_date": "2024-12-31",
"notes": "Special handling required",
"created_at": "2024-01-15T10:30:00Z"
}
}The API uses conventional HTTP response codes to indicate success or failure of requests.
| Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Authentication required |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Resource not found |
| 422 | Unprocessable Entity | Validation error |
| 500 | Internal Server Error | Server error |
The API implements rate limiting to ensure fair usage. Each authenticated user is limited to:
If you have questions about using the API or encounter any issues, please don't hesitate to reach out:
We connect shippers and carries for seamless cargo orders experience.
Post your cargo & get it delivered!