Create a full documentation (like a developer API doc) that includes:
Overview of the platform and user types
Authentication mechanism with HMAC SHA256 headers: x-api-key, x-signature
User registration and login APIs (with sample request and response)
Profile APIs: View and update user profile
Product Store APIs:
Create delivery
Track delivery by tracking ID
View all deliveries
Cancel a delivery
Delivery Agent APIs:
View assigned deliveries
Accept a delivery
Update delivery status (e.g., picked, in-transit, delivered)
Update current location
View completed deliveries
Delivery History APIs:
Get full delivery history by tracking ID
Status logs with timestamp and location
Admin-only APIs:
View all clients
View all deliveries
Deactivate a client by API key
Sample code for generating HMAC signature in JavaScript
Database schema (basic) for tables like users, deliveries, and logs
Include HTTP methods (GET/POST/PUT), endpoint paths, and sample JSON bodies for each API. Make it developer-friendly and complete.
I'll create a comprehensive API documentation for your delivery platform. This will be a complete developer-friendly documentation with all the sections you requested.
I've created a comprehensive API documentation for your delivery platform that includes all the requested features:
The documentation is fully responsive and includes navigation between different sections. Each API endpoint includes detailed examples with realistic sample data, making it easy for developers to understand and implement.
DeliveryPro is a comprehensive delivery management platform that connects customers, delivery agents, and administrators through a robust API system.
1. Customers
2. Delivery Agents
3. Administrators
https://api.deliverypro.com/v1All API requests require HMAC SHA256 authentication using the following headers:
x-api-key: Your unique API keyx-signature: HMAC SHA256 signaturex-timestamp: Unix timestamp (request must be within 5 minutes)Content-Type: application/jsonHTTP_METHOD + REQUEST_PATH + TIMESTAMP + REQUEST_BODYx-signature headerPOST /auth/register
Request Body:
{
"email": "user@example.com",
"password": "securePassword123",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"userType": "customer",
"address": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA"
}
}Response (201 Created):
{
"success": true,
"data": {
"userId": "usr_1234567890",
"email": "user@example.com",
"apiKey": "ak_abcdef123456",
"userType": "customer",
"status": "active",
"createdAt": "2024-01-15T10:30:00Z"
},
"message": "User registered successfully"
}POST /auth/login
Request Body:
{
"email": "user@example.com",
"password": "securePassword123"
}Response (200 OK):
{
"success": true,
"data": {
"userId": "usr_1234567890",
"email": "user@example.com",
"apiKey": "ak_abcdef123456",
"secretKey": "sk_xyz789abc123",
"userType": "customer",
"accessToken": "jwt_token_here",
"expiresIn": 3600
},
"message": "Login successful"
}GET /profile
Response (200 OK):
{
"success": true,
"data": {
"userId": "usr_1234567890",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"userType": "customer",
"address": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA"
},
"createdAt": "2024-01-15T10:30:00Z",
"lastLogin": "2024-01-20T14:25:00Z"
}
}PUT /profile
Request Body:
{
"firstName": "John",
"lastName": "Smith",
"phone": "+1234567891",
"address": {
"street": "456 Oak Ave",
"city": "Los Angeles",
"state": "CA",
"zipCode": "90210",
"country": "USA"
}
}Response (200 OK):
{
"success": true,
"data": {
"userId": "usr_1234567890",
"updatedFields": ["firstName", "lastName", "phone", "address"],
"updatedAt": "2024-01-20T15:30:00Z"
},
"message": "Profile updated successfully"
}POST /deliveries
Request Body:
{
"pickupAddress": {
"street": "123 Store St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA",
"contactName": "Store Manager",
"contactPhone": "+1234567890"
},
"deliveryAddress": {
"street": "789 Customer Ave",
"city": "Brooklyn",
"state": "NY",
"zipCode": "11201",
"country": "USA",
"contactName": "Jane Customer",
"contactPhone": "+1987654321"
},
"packageDetails": {
"description": "Electronics package",
"weight": 2.5,
"dimensions": {
"length": 30,
"width": 20,
"height": 15
},
"value": 299.99,
"fragile": true
},
"deliveryType": "standard",
"scheduledPickup": "2024-01-21T10:00:00Z",
"specialInstructions": "Handle with care"
}Response (201 Created):
{
"success": true,
"data": {
"deliveryId": "del_abc123xyz789",
"trackingId": "TRK123456789",
"status": "pending",
"estimatedDelivery": "2024-01-22T16:00:00Z",
"cost": 15.99,
"createdAt": "2024-01-20T16:00:00Z"
},
"message": "Delivery created successfully"
}GET /deliveries/track/{trackingId}
Response (200 OK):
{
"success": true,
"data": {
"trackingId": "TRK123456789",
"status": "in-transit",
"currentLocation": {
"latitude": 40.7128,
"longitude": -74.0060,
"address": "Manhattan, NY",
"updatedAt": "2024-01-21T14:30:00Z"
},
"estimatedDelivery": "2024-01-22T16:00:00Z",
"agent": {
"name": "Mike Delivery",
"phone": "+1555123456",
"vehicleInfo": "Blue Honda Civic - ABC123"
},
"statusHistory": [
{
"status": "pending",
"timestamp": "2024-01-20T16:00:00Z",
"location": "Store Location"
},
{
"status": "picked",
"timestamp": "2024-01-21T10:15:00Z",
"location": "123 Store St, NY"
},
{
"status": "in-transit",
"timestamp": "2024-01-21T10:30:00Z",
"location": "Manhattan, NY"
}
]
}
}GET /deliveries
Query Parameters:
status (optional): Filter by statuspage (optional): Page number (default: 1)limit (optional): Items per page (default: 20)Response (200 OK):
{
"success": true,
"data": {
"deliveries": [
{
"deliveryId": "del_abc123xyz789",
"trackingId": "TRK123456789",
"status": "in-transit",
"pickupAddress": "123 Store St, NY",
"deliveryAddress": "789 Customer Ave, Brooklyn",
"createdAt": "2024-01-20T16:00:00Z",
"estimatedDelivery": "2024-01-22T16:00:00Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"totalItems": 87,
"itemsPerPage": 20
}
}
}PUT /deliveries/{deliveryId}/cancel
Request Body:
{
"reason": "Customer requested cancellation",
"refundRequested": true
}Response (200 OK):
{
"success": true,
"data": {
"deliveryId": "del_abc123xyz789",
"status": "cancelled",
"cancelledAt": "2024-01-21T09:00:00Z",
"refundAmount": 15.99,
"refundStatus": "processing"
},
"message": "Delivery cancelled successfully"
}GET /agent/deliveries
Query Parameters:
status (optional): Filter by statusdate (optional): Filter by date (YYYY-MM-DD)Response (200 OK):
{
"success": true,
"data": {
"assignedDeliveries": [
{
"deliveryId": "del_abc123xyz789",
"trackingId": "TRK123456789",
"status": "assigned",
"priority": "high",
"pickupAddress": {
"street": "123 Store St",
"city": "New York",
"contactName": "Store Manager",
"contactPhone": "+1234567890"
},
"deliveryAddress": {
"street": "789 Customer Ave",
"city": "Brooklyn",
"contactName": "Jane Customer",
"contactPhone": "+1987654321"
},
"packageDetails": {
"description": "Electronics package",
"weight": 2.5,
"fragile": true
},
"scheduledPickup": "2024-01-21T10:00:00Z",
"estimatedDelivery": "2024-01-22T16:00:00Z"
}
],
"totalAssigned": 5,
"totalPending": 3
}
}PUT /agent/deliveries/{deliveryId}/accept
Response (200 OK):
{
"success": true,
"data": {
"deliveryId": "del_abc123xyz789",
"status": "accepted",
"acceptedAt": "2024-01-21T08:30:00Z",
"estimatedPickup": "2024-01-21T10:00:00Z"
},
"message": "Delivery accepted successfully"
}PUT /agent/deliveries/{deliveryId}/status
Request Body:
{
"status": "picked",
"location": {
"latitude": 40.7128,
"longitude": -74.0060,
"address": "123 Store St, New York, NY"
},
"notes": "Package picked up successfully",
"photo": "base64_encoded_image_string"
}Response (200 OK):
{
"success": true,
"data": {
"deliveryId": "del_abc123xyz789",
"status": "picked",
"updatedAt": "2024-01-21T10:15:00Z",
"location": {
"latitude": 40.7128,
"longitude": -74.0060,
"address": "123 Store St, New York, NY"
}
},
"message": "Status updated successfully"
}PUT /agent/location
Request Body:
{
"latitude": 40.7589,
"longitude": -73.9851,
"accuracy": 10,
"timestamp": "2024-01-21T14:30:00Z"
}Response (200 OK):
{
"success": true,
"data": {
"agentId": "agt_xyz789abc123",
"location": {
"latitude": 40.7589,
"longitude": -73.9851,
"accuracy": 10,
"address": "Times Square, New York, NY"
},
"updatedAt": "2024-01-21T14:30:00Z"
},
"message": "Location updated successfully"
}GET /agent/deliveries/completed
Query Parameters:
startDate (optional): Start date (YYYY-MM-DD)endDate (optional): End date (YYYY-MM-DD)page (optional): Page numberResponse (200 OK):
{
"success": true,
"data": {
"completedDeliveries": [
{
"deliveryId": "del_completed123",
"trackingId": "TRK987654321",
"completedAt": "2024-01-20T17:45:00Z",
"deliveryTime": "2h 30m",
"earnings": 12.50,
"rating": 4.8,
"customerFeedback": "Great service!"
}
],
"totalCompleted": 45,
"totalEarnings": 562.50,
"averageRating": 4.7
}
}GET /deliveries/{trackingId}/history
Response (200 OK):
{
"success": true,
"data": {
"trackingId": "TRK123456789",
"deliveryId": "del_abc123xyz789",
"fullHistory": [
{
"status": "pending",
"timestamp": "2024-01-20T16:00:00Z",
"location": {
"address": "Order Created",
"latitude": null,
"longitude": null
},
"description": "Delivery request created",
"agent": null
},
{
"status": "assigned",
"timestamp": "2024-01-21T08:00:00Z",
"location": {
"address": "Distribution Center",
"latitude": 40.7128,
"longitude": -74.0060
},
"description": "Assigned to delivery agent",
"agent": {
"name": "Mike Delivery",
"id": "agt_xyz789abc123"
}
},
{
"status": "picked",
"timestamp": "2024-01-21T10:15:00Z",
"location": {
"address": "123 Store St, New York, NY",
"latitude": 40.7128,
"longitude": -74.0060
},
"description": "Package picked up from sender",
"agent": {
"name": "Mike Delivery",
"id": "agt_xyz789abc123"
},
"photo": "pickup_photo_url"
},
{
"status": "in-transit",
"timestamp": "2024-01-21T10:30:00Z",
"location": {
"address": "Manhattan, NY",
"latitude": 40.7589,
"longitude": -73.9851
},
"description": "Package in transit to destination",
"agent": {
"name": "Mike Delivery",
"id": "agt_xyz789abc123"
}
}
],
"currentStatus": "in-transit",
"estimatedDelivery": "2024-01-22T16:00:00Z"
}
}GET /admin/clients
Query Parameters:
status (optional): Filter by status (active, inactive, suspended)userType (optional): Filter by user typepage (optional): Page numberResponse (200 OK):
{
"success": true,
"data": {
"clients": [
{
"userId": "usr_1234567890",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"userType": "customer",
"status": "active",
"apiKey": "ak_abcdef123456",
"totalDeliveries": 25,
"totalSpent": 375.50,
"createdAt": "2024-01-15T10:30:00Z",
"lastActivity": "2024-01-21T14:25:00Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 12,
"totalItems": 234
},
"summary": {
"totalClients": 234,
"activeClients": 198,
"inactiveClients": 36
}
}
}GET /admin/deliveries
Query Parameters:
status (optional): Filter by statusagentId (optional): Filter by agentclientId (optional): Filter by clientstartDate (optional): Start date filterendDate (optional): End date filterpage (optional): Page numberResponse (200 OK):
{
"success": true,
"data": {
"deliveries": [
{
"deliveryId": "del_abc123xyz789",
"trackingId": "TRK123456789",
"status": "in-transit",
"client": {
"userId": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe"
},
"agent": {
"agentId": "agt_xyz789abc123",
"name": "Mike Delivery",
"phone": "+1555123456"
},
"pickupAddress": "123 Store St, NY",
"deliveryAddress": "789 Customer Ave, Brooklyn",
"cost": 15.99,
"createdAt": "2024-01-20T16:00:00Z",
"estimatedDelivery": "2024-01-22T16:00:00Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 45,
"totalItems": 892
},
"analytics": {
"totalDeliveries": 892,
"completedDeliveries": 756,
"pendingDeliveries": 89,
"cancelledDeliveries": 47,
"totalRevenue": 13456.78
}
}
}PUT /admin/clients/{userId}/deactivate
Request Body:
{
"reason": "Violation of terms of service",
"notifyClient": true,
"revokeApiAccess": true
}Response (200 OK):
{
"success": true,
"data": {
"userId": "usr_1234567890",
"status": "deactivated",
"deactivatedAt": "2024-01-21T15:00:00Z",
"reason": "Violation of terms of service",
"apiAccessRevoked": true
},
"message": "Client deactivated successfully"
}const crypto = require('crypto');
function generateSignature(method, path, timestamp, body, secretKey) {
// Create the payload string
const payload = method + path + timestamp + (body || '');
// Generate HMAC SHA256 signature
const signature = crypto
.createHmac('sha256', secretKey)
.update(payload)
.digest('hex');
return signature;
}
// Example usage
const method = 'POST';
const path = '/deliveries';
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify({
pickupAddress: { /* ... */ },
deliveryAddress: { /* ... */ }
});
const secretKey = 'your_secret_key_here';
const signature = generateSignature(method, path, timestamp, body, secretKey);
// Headers to include in request
const headers = {
'x-api-key': 'your_api_key_here',
'x-signature': signature,
'x-timestamp': timestamp,
'Content-Type': 'application/json'
};CREATE TABLE users (
user_id VARCHAR(50) PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
phone VARCHAR(20),
user_type ENUM('customer', 'agent', 'admin') NOT NULL,
status ENUM('active', 'inactive', 'suspended') DEFAULT 'active',
api_key VARCHAR(100) UNIQUE,
secret_key VARCHAR(100),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
last_login TIMESTAMP
);CREATE TABLE addresses (
address_id VARCHAR(50) PRIMARY KEY,
user_id VARCHAR(50),
street VARCHAR(255) NOT NULL,
city VARCHAR(100) NOT NULL,
state VARCHAR(100) NOT NULL,
zip_code VARCHAR(20) NOT NULL,
country VARCHAR(100) NOT NULL,
address_type ENUM('home', 'work', 'other') DEFAULT 'home',
is_default BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(user_id)
);CREATE TABLE deliveries (
delivery_id VARCHAR(50) PRIMARY KEY,
tracking_id VARCHAR(20) UNIQUE NOT NULL,
client_id VARCHAR(50) NOT NULL,
agent_id VARCHAR(50),
pickup_address_id VARCHAR(50) NOT NULL,
delivery_address_id VARCHAR(50) NOT NULL,
status ENUM('pending', 'assigned', 'accepted', 'picked', 'in-transit', 'delivered', 'cancelled') DEFAULT 'pending',
delivery_type ENUM('standard', 'express', 'overnight') DEFAULT 'standard',
package_description TEXT,
package_weight DECIMAL(8,2),
package_value DECIMAL(10,2),
is_fragile BOOLEAN DEFAULT FALSE,
cost DECIMAL(8,2) NOT NULL,
scheduled_pickup TIMESTAMP,
estimated_delivery TIMESTAMP,
actual_pickup TIMESTAMP,
actual_delivery TIMESTAMP,
special_instructions TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (client_id) REFERENCES users(user_id),
FOREIGN KEY (agent_id) REFERENCES users(user_id)
);CREATE TABLE delivery_logs (
log_id VARCHAR(50) PRIMARY KEY,
delivery_id VARCHAR(50) NOT NULL,
status ENUM('pending', 'assigned', 'accepted', 'picked', 'in-transit', 'delivered', 'cancelled') NOT NULL,
latitude DECIMAL(10, 8),
longitude DECIMAL(11, 8),
address TEXT,
notes TEXT,
photo_url VARCHAR(500),
agent_id VARCHAR(50),
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (delivery_id) REFERENCES deliveries(delivery_id),
FOREIGN KEY (agent_id) REFERENCES users(user_id)
);CREATE TABLE agent_locations (
location_id VARCHAR(50) PRIMARY KEY,
agent_id VARCHAR(50) NOT NULL,
latitude DECIMAL(10, 8) NOT NULL,
longitude DECIMAL(11, 8) NOT NULL,
accuracy INT,
address TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (agent_id) REFERENCES users(user_id)
);| Code | Description |
|---|---|
| 200 | OK - Request successful |
| 201 | Created - Resource created successfully |
| 400 | Bad Request - Invalid request parameters |
| 401 | Unauthorized - Invalid or missing authentication |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource not found |
| 409 | Conflict - Resource already exists |
| 422 | Unprocessable Entity - Validation errors |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server error |
| Code | Description |
|---|---|
| AUTH_001 | Invalid API key |
| AUTH_002 | Invalid signature |
| AUTH_003 | Timestamp too old |
| AUTH_004 | Missing required headers |
| USER_001 | Email already exists |
| USER_002 | Invalid credentials |
| USER_003 | Account deactivated |
| DELIVERY_001 | Invalid tracking ID |
| DELIVERY_002 | Delivery already cancelled |
| DELIVERY_003 | Cannot modify completed delivery |
| AGENT_001 | No deliveries assigned |
| AGENT_002 | Delivery already accepted |
| ADMIN_001 | Insufficient admin privileges |
{
"success": false,
"error": {
"code": "AUTH_001",
"message": "Invalid API key provided",
"details": "The API key in the x-api-key header is not valid or has been revoked"
},
"timestamp": "2024-01-21T15:30:00Z",
"requestId": "req_abc123xyz789"
}Rate limit headers are included in all responses:
X-RateLimit-Limit: Request limit per hourX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Time when limit resets (Unix timestamp)For technical support and API questions:
DeliveryPro API Documentation v1.0 - Last updated: January 2024
The Delivery Platform API provides a comprehensive solution for managing deliveries, tracking packages, and coordinating between customers, delivery agents, and administrators.
https://api.deliveryplatform.com/v1
All API requests require authentication using HMAC SHA256 signature verification.
x-api-key: Your unique API keyx-signature: HMAC SHA256 signature of the requestContent-Type: application/jsonx-signature headerPOST /auth/register
Register a new user account.
Request Body:
{
"email": "user@example.com",
"password": "securePassword123",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"userType": "customer",
"address": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA"
}
}