API Contract Overview¶
Base URLs¶
| Environment | Base URL |
|---|---|
| Production | https://api.saas-courier.com |
| Development | http://localhost:8080 |
API Version¶
Current version: v1
Version prefix: /api/v1/
Communication¶
| Format | Content-Type |
|---|---|
| JSON | application/json |
| WebSocket | ws:// or wss:// |
Timezone¶
All datetime operations use UTC.
Endpoint Summary¶
| Category | Endpoints |
|---|---|
| Auth | Register, Login, Refresh, Logout, OAuth, Email verification, Password reset |
| Shipments | CRUD operations, Assign to bag |
| Bags | CRUD operations, List shipments |
| Flights | CRUD operations, Status sync, Search |
| Courier | Get bags, Get bag shipments, Mark delivered |
| Tracking | Public tracking by ID |
| WebSocket | Real-time notifications |
Error Response Format¶
Error Status Codes¶
| Code | Meaning |
|---|---|
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid credentials |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 422 | Validation Error - Schema validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
OpenAPI Schema¶
Full schema available at: GET /openapi.json
Interactive documentation at: GET /docs
Implementation Status¶
- [x] Token storage
- [x] Authorization header
- [x] Token refresh
- [x] Rate limit handling (429)
- [x] Authentication errors (401)
- [x] Email verification flow
- [x] Password reset flow
- [x] OAuth authentication
- [x] WebSocket real-time updates