David/xpeditis2.0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
87db05398a
xpeditis2.0/postman
History
David 2069cfb69d feature
2025-11-04 07:30:15 +01:00
..
README.md fix path controller 2025-10-27 20:49:06 +01:00
Xpeditis_API.postman_collection.json feature 2025-11-04 07:30:15 +01:00
Xpeditis_Complete_API.postman_collection.json feature 2025-11-04 07:30:15 +01:00
Xpeditis_Local.postman_environment.json feature 2025-11-04 07:30:15 +01:00

README.md

Xpeditis API - Postman Collection

Complete Postman collection for testing the Xpeditis B2B Maritime Freight Platform API.

Overview

This Postman collection provides comprehensive API testing coverage for all Xpeditis endpoints, including:

  • Authentication (register, login, refresh tokens)
  • Rate search (standard and CSV-based with advanced filters)
  • Booking management (create, list, search, export)
  • User management (CRUD operations)
  • Organization management
  • Notifications
  • Audit logs
  • GDPR compliance
  • Webhooks
  • Dashboard analytics
  • Admin CSV rate uploads
  • Health checks

Files

  • Xpeditis_Complete_API.postman_collection.json - Complete API collection with all endpoints
  • Xpeditis_Local.postman_environment.json - Local development environment variables

Quick Start

1. Import Collection and Environment

  1. Open Postman
  2. Click Import button
  3. Select both files:
    • Xpeditis_Complete_API.postman_collection.json
    • Xpeditis_Local.postman_environment.json
  4. Click Import

2. Select Environment

  1. Click the environment dropdown (top right)
  2. Select Xpeditis Local Environment

3. Start Backend Server

Ensure the Xpeditis backend is running:

cd apps/backend
npm run dev

Backend will be available at: http://localhost:4000

4. Test Authentication

  1. Open the Authentication folder
  2. Run Register New User or Login
  3. The access token will be automatically saved to the environment

Now you're ready to test all authenticated endpoints!

API Endpoint Summary

Authentication (5 endpoints)

  • POST /auth/register - Register new user (Public)
  • POST /auth/login - Login with credentials (Public)
  • POST /auth/refresh - Refresh access token (Public)
  • POST /auth/logout - Logout user (Auth required)
  • GET /auth/me - Get current user profile (Auth required)

Rates (4 endpoints)

  • POST /api/v1/rates/search - Search shipping rates (Auth required)
  • POST /api/v1/rates/search-csv - Advanced CSV rate search (Auth required)
  • GET /api/v1/rates/companies - Get available companies (Auth required)
  • GET /api/v1/rates/filters/options - Get filter options (Auth required)

Bookings (8 endpoints)

  • POST /api/v1/bookings - Create booking (Auth required)
  • GET /api/v1/bookings/:id - Get booking by ID (Auth required)
  • GET /api/v1/bookings/number/:bookingNumber - Get booking by number (Auth required)
  • GET /api/v1/bookings - List bookings with pagination (Auth required)
  • GET /api/v1/bookings/search/fuzzy - Fuzzy search bookings (Auth required)
  • GET /api/v1/bookings/advanced/search - Advanced search with filters (Auth required)
  • POST /api/v1/bookings/export - Export bookings (CSV/Excel/JSON) (Auth required)

Users (6 endpoints)

  • POST /api/v1/users - Create user (Admin/Manager)
  • GET /api/v1/users/:id - Get user by ID (Auth required)
  • PATCH /api/v1/users/:id - Update user (Admin/Manager)
  • DELETE /api/v1/users/:id - Delete user (Admin only)
  • GET /api/v1/users - List users (Auth required)
  • PATCH /api/v1/users/me/password - Update own password (Auth required)

Organizations (4 endpoints)

  • POST /api/v1/organizations - Create organization (Admin only)
  • GET /api/v1/organizations/:id - Get organization by ID (Auth required)
  • PATCH /api/v1/organizations/:id - Update organization (Admin/Manager)
  • GET /api/v1/organizations - List organizations (Auth required)

Notifications (6 endpoints)

  • GET /api/v1/notifications - Get notifications (Auth required)
  • GET /api/v1/notifications/unread - Get unread notifications (Auth required)
  • GET /api/v1/notifications/unread/count - Get unread count (Auth required)
  • PATCH /api/v1/notifications/:id/read - Mark as read (Auth required)
  • POST /api/v1/notifications/read-all - Mark all as read (Auth required)
  • DELETE /api/v1/notifications/:id - Delete notification (Auth required)

Audit Logs (4 endpoints)

  • GET /api/v1/audit-logs - Get audit logs with filters (Admin/Manager)
  • GET /api/v1/audit-logs/resource/:type/:id - Get resource audit trail (Auth required)
  • GET /api/v1/audit-logs/organization/activity - Get organization activity (Admin/Manager)
  • GET /api/v1/audit-logs/user/:userId/activity - Get user activity (Admin/Manager)

GDPR (6 endpoints)

  • GET /gdpr/export - Export user data as JSON (Auth required)
  • GET /gdpr/export/csv - Export user data as CSV (Auth required)
  • DELETE /gdpr/delete-account - Delete account (Auth required)
  • POST /gdpr/consent - Record consent (Auth required)
  • POST /gdpr/consent/withdraw - Withdraw consent (Auth required)
  • GET /gdpr/consent - Get consent status (Auth required)

Webhooks (7 endpoints)

  • POST /api/v1/webhooks - Create webhook (Admin/Manager)
  • GET /api/v1/webhooks - Get all webhooks (Admin/Manager)
  • GET /api/v1/webhooks/:id - Get webhook by ID (Admin/Manager)
  • PATCH /api/v1/webhooks/:id - Update webhook (Admin/Manager)
  • POST /api/v1/webhooks/:id/activate - Activate webhook (Admin/Manager)
  • POST /api/v1/webhooks/:id/deactivate - Deactivate webhook (Admin/Manager)
  • DELETE /api/v1/webhooks/:id - Delete webhook (Admin/Manager)

Dashboard (4 endpoints)

  • GET /api/v1/dashboard/kpis - Get dashboard KPIs (Auth required)
  • GET /api/v1/dashboard/bookings-chart - Get bookings chart data (Auth required)
  • GET /api/v1/dashboard/top-trade-lanes - Get top trade lanes (Auth required)
  • GET /api/v1/dashboard/alerts - Get dashboard alerts (Auth required)

Admin - CSV Rates (5 endpoints)

  • POST /api/v1/admin/csv-rates/upload - Upload CSV rate file (Admin only)
  • GET /api/v1/admin/csv-rates/config - Get all configurations (Admin only)
  • GET /api/v1/admin/csv-rates/config/:companyName - Get config by company (Admin only)
  • POST /api/v1/admin/csv-rates/validate/:companyName - Validate CSV file (Admin only)
  • DELETE /api/v1/admin/csv-rates/config/:companyName - Delete configuration (Admin only)

Health (3 endpoints)

  • GET /health - Health check (Public)
  • GET /health/ready - Readiness check (Public)
  • GET /health/live - Liveness check (Public)

Total: 68 endpoints

Environment Variables

The environment file includes the following variables:

Variable Description Auto-populated
baseUrl API base URL No (default: http://localhost:4000)
token JWT access token Yes (after login/register)
refreshToken JWT refresh token Yes (after login/register)
userId Current user ID Yes (after login/register)
userEmail Current user email Yes (after login/register)
organizationId Current user's organization ID Yes (after login/register)
rateQuoteId Last searched rate quote ID Yes (after rate search)
bookingId Last created booking ID Yes (after booking creation)
bookingNumber Last created booking number Yes (after booking creation)

Variables marked "Yes" under Auto-populated are automatically set by test scripts when you run the corresponding requests.

Common Workflows

1. Complete Booking Flow

  1. Register/Login → Auto-saves token
  2. Search Rates → Auto-saves rateQuoteId
  3. Create Booking → Auto-saves bookingId and bookingNumber
  4. Get Booking Details → Use saved bookingId
  5. List Bookings → View all bookings
  6. Export Bookings → Download CSV/Excel

2. User Management Flow

  1. Login as Admin → Auto-saves token
  2. Create User → Create new team member
  3. List Users → View all users
  4. Update User → Change role or details
  5. Delete User → Deactivate account

3. CSV Rate Upload Flow (Admin)

  1. Login as Admin → Auto-saves token
  2. Upload CSV File → Upload carrier rates
  3. Validate CSV → Check file structure
  4. Search CSV Rates → Test the uploaded rates
  5. Get Filter Options → View available carriers

Authentication

Most endpoints require authentication. The collection uses Bearer Token authentication.

How It Works

  1. Run Register or Login request
  2. Test script automatically saves accessToken to {{token}} variable
  3. All authenticated requests use {{token}} in the Authorization header
  4. Tokens expire after 15 minutes (configurable)
  5. Use Refresh Access Token to get a new token

Manual Token Setup

If needed, you can manually set the token:

  1. Copy the access token from a login response
  2. Go to Environments → Xpeditis Local Environment
  3. Paste into the token variable
  4. Save

Role-Based Access Control (RBAC)

Different endpoints require different roles:

  • Public: No authentication required
  • User: Any authenticated user
  • Manager: Manager or Admin role
  • Admin: Admin role only
Role Permissions
viewer Read-only access to bookings and rates
user Create and view own bookings, search rates
manager Manage organization bookings and users
admin Full system access, manage all organizations

Testing Best Practices

1. Run Requests in Order

For best results, run requests in this order:

  1. Health Check (verify backend is running)
  2. Register/Login (get authentication token)
  3. Test feature-specific endpoints

2. Check Response Status

  • ✅ 200/201 - Success
  • ⚠️ 400 - Validation error (check request body)
  • 🔒 401 - Unauthorized (token missing/expired)
  • 🚫 403 - Forbidden (insufficient permissions)
  • ❌ 404 - Not found
  • 💥 500 - Server error

3. Use Console for Debugging

The collection includes test scripts that log useful info:

  1. Open Postman Console (bottom left)
  2. Run a request
  3. View logged variables and debug info

4. Validate Responses

Test scripts automatically validate responses and extract key data. Check the Test Results tab after each request.

Example Request Bodies

Register User

{
  "email": "john.doe@acme.com",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe"
}

Search Rates

{
  "origin": "NLRTM",
  "destination": "CNSHA",
  "containerType": "40HC",
  "mode": "FCL",
  "departureDate": "2025-02-15",
  "quantity": 2,
  "weight": 20000,
  "volume": 50.5,
  "isHazmat": false
}

Create Booking

{
  "rateQuoteId": "{{rateQuoteId}}",
  "shipper": {
    "name": "Acme Corporation",
    "address": {
      "street": "123 Main Street",
      "city": "Rotterdam",
      "postalCode": "3000 AB",
      "country": "NL"
    },
    "contactName": "John Doe",
    "contactEmail": "john.doe@acme.com",
    "contactPhone": "+31612345678"
  },
  "consignee": {
    "name": "Global Trading Ltd",
    "address": {
      "street": "456 Harbor Road",
      "city": "Shanghai",
      "postalCode": "200000",
      "country": "CN"
    },
    "contactName": "Jane Smith",
    "contactEmail": "jane.smith@globaltrading.com",
    "contactPhone": "+8613800000000"
  },
  "cargoDescription": "Electronics and consumer goods - fragile items",
  "containers": [
    {
      "type": "40HC",
      "vgm": 22000,
      "sealNumber": "SEAL123456"
    }
  ],
  "specialInstructions": "Please handle with care. Delivery before 5 PM."
}

Advanced Features

1. Fuzzy Search

The fuzzy search endpoint is tolerant to typos and partial matches:

GET /api/v1/bookings/search/fuzzy?q=WCM-2025&limit=20

Searches across:

  • Booking number
  • Shipper name
  • Consignee name

2. Advanced Filtering

Use the advanced search endpoint for complex queries:

GET /api/v1/bookings/advanced/search?
  status=confirmed,in_transit&
  createdFrom=2025-01-01&
  shipper=Acme&
  sortBy=createdAt&
  sortOrder=desc

3. Export Formats

Export bookings in multiple formats:

  • CSV - Spreadsheet format
  • XLSX - Excel format
  • JSON - Raw data format

Specify fields to export:

{
  "format": "csv",
  "fields": [
    "bookingNumber",
    "status",
    "shipper",
    "consignee",
    "origin",
    "destination",
    "carrier",
    "createdAt"
  ]
}

4. Webhook Events

Available webhook events:

  • booking.created
  • booking.confirmed
  • booking.cancelled
  • shipment.departed
  • shipment.arrived
  • document.uploaded

Troubleshooting

Issue: 401 Unauthorized

Solution: Token expired or missing

  1. Run Login request again
  2. Or use Refresh Access Token

Issue: 403 Forbidden

Solution: Insufficient permissions

  • Check your user role
  • Some endpoints require Admin or Manager role

Issue: 404 Not Found

Solution: Resource doesn't exist

  • Verify the ID in the URL
  • Check if the resource belongs to your organization

Issue: 500 Internal Server Error

Solution: Backend error

  1. Check backend logs
  2. Verify database is running
  3. Check Redis connection

Issue: Connection Refused

Solution: Backend not running

cd apps/backend
npm run dev

Additional Resources

Support

For issues or questions:

  1. Check the API documentation
  2. Review controller source code in apps/backend/src/application/controllers/
  3. Check DTO definitions in apps/backend/src/application/dto/

Version History

  • v1.0.0 (2025-10-27) - Initial complete collection with all 68 endpoints

Happy Testing! 🚢✨