{ "openapi": "3.0.0", "info": { "title": "Rocketship API", "description": "API for Rocketship package shipping and logistics management system", "contact": { "email": "support@rocketshipja.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://my-default-host.com", "description": "API Server" } ], "paths": { "/api/v1/addresses": { "get": { "tags": [ "Addresses" ], "summary": "Get user addresses", "description": "Retrieve all addresses for the authenticated user", "operationId": "58864965653185d21f49fd35c098f411", "responses": { "200": { "description": "List of user addresses", "content": { "application/json": { "schema": { "properties": { "addresses": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "location_id": { "type": "integer" }, "location": { "type": "object" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Addresses" ], "summary": "Add new address", "description": "Add a new delivery address for the authenticated user", "operationId": "ccf4b5f0cd7e2e982267e6e9c18ab448", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "address", "location" ], "properties": { "name": { "type": "string", "example": "Home" }, "address": { "type": "string", "example": "123 Main Street, Kingston" }, "location": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Address added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Address added successfully!" }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/addresses/{id}": { "delete": { "tags": [ "Addresses" ], "summary": "Delete address", "description": "Delete a delivery address", "operationId": "848114c5b21d1f8b4d106714bfed25ed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Address deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Address deleted successfully." }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/login": { "post": { "tags": [ "Authentication" ], "summary": "User login", "description": "Authenticate a user and return API token", "operationId": "e97d5621c9053977b2ffcfc5d47c5050", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "api_token": { "type": "string", "example": "abc123..." }, "role": { "type": "string", "example": "customer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sorry, We could not find an account with the provided email and password" } }, "type": "object" } } } } } } }, "/api/v1/calculator/calculate": { "post": { "tags": [ "Calculator" ], "summary": "Calculate shipping cost", "description": "Calculate shipping cost based on package weight with optional fees", "operationId": "2e0c14baecc4ec561787f644cc93c657", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "weight" ], "properties": { "weight": { "description": "Package weight in LBS", "type": "number", "format": "float", "example": 5.5 }, "include_processing_fee": { "description": "Include processing fee ($1.50)", "type": "boolean", "example": true }, "include_insurance": { "description": "Include insurance ($0.06)", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Shipping cost calculated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "weight": { "type": "number", "example": 5.5 }, "shipping_cost": { "type": "number", "example": 15.99 }, "processing_fee": { "type": "number", "example": 1.5 }, "insurance": { "type": "number", "example": 0.06 }, "total_cost": { "type": "number", "example": 17.55 }, "total_cost_jmd": { "type": "string", "example": "2,764.13" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/api/v1/deliveries": { "get": { "tags": [ "Delivery" ], "summary": "Get user deliveries", "description": "Retrieve all scheduled deliveries for the authenticated user", "operationId": "d30fc4fc52cf62d4af8b2082c3bef135", "responses": { "200": { "description": "List of deliveries", "content": { "application/json": { "schema": { "properties": { "deliveries": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "delivery_date": { "type": "string", "format": "date" }, "address": { "type": "string" }, "status_id": { "type": "string" }, "package_count": { "type": "integer" }, "cost": { "type": "string" }, "packages": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Delivery" ], "summary": "Schedule a delivery", "description": "Schedule packages for home delivery (temporarily disabled via API)", "operationId": "8394a3351e4dfecebe029f29e054b8b7", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "package", "date", "address", "location", "paymentOption" ], "properties": { "package": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "date": { "type": "string", "format": "date", "example": "2024-12-20" }, "address": { "type": "string", "example": "123 Main St, Kingston" }, "lat": { "type": "number", "example": 18.0179 }, "lng": { "type": "number", "example": -76.8099 }, "location": { "type": "integer", "example": 1 }, "timeOfDay": { "type": "string", "example": "Morning" }, "instructions": { "type": "string" }, "paymentOption": { "type": "string", "enum": [ "CASH", "PAYPAL" ] } }, "type": "object" } } } }, "responses": { "403": { "description": "Delivery scheduling temporarily disabled via mobile app" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/deliveries/{id}/cancel": { "delete": { "tags": [ "Delivery" ], "summary": "Cancel delivery", "description": "Cancel a scheduled delivery (not available after 9AM on delivery day)", "operationId": "d5baa01149b1b75e919f31fa26368921", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Delivery cancelled successfully" }, "400": { "description": "Cannot cancel - after cutoff time or already paid" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/deliveries/{id}/reschedule": { "put": { "tags": [ "Delivery" ], "summary": "Reschedule delivery", "description": "Change the delivery date for a scheduled delivery", "operationId": "ee28cac2e88f5fe1a987303a62551bda", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date", "example": "2024-12-25" } }, "type": "object" } } } }, "responses": { "200": { "description": "Delivery rescheduled successfully" }, "400": { "description": "Cannot reschedule to selected date" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/deliveries/locations": { "get": { "tags": [ "Delivery" ], "summary": "Get delivery locations", "description": "Retrieve all available delivery locations/areas", "operationId": "c247c235e681f38790f7b447f5540e2b", "responses": { "200": { "description": "List of delivery locations", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "locations": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "cost": { "type": "number" }, "enabled": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } } } } }, "/api/v1/deliveries/rates": { "get": { "tags": [ "Delivery" ], "summary": "Get delivery rates", "description": "Retrieve delivery rates for all locations (standard and express)", "operationId": "0f73b46a7b194bb7cbfbc80fef835c93", "responses": { "200": { "description": "Delivery rates by location", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "rates": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "standard": { "properties": { "cost": { "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" }, "express": { "properties": { "cost": { "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } } } } }, "/api/v1/home": { "get": { "tags": [ "Home" ], "summary": "Get dashboard data", "description": "Retrieve comprehensive dashboard data including packages, deliveries, pickups, addresses, stats, and user information", "operationId": "d623432e829f34fe1ac09f7294d62527", "responses": { "200": { "description": "Dashboard data", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "user": { "type": "object" }, "packages": { "type": "object" }, "addresses": { "type": "array", "items": { "type": "object" } }, "pickups": { "type": "array", "items": { "type": "object" } }, "deliveries": { "type": "array", "items": { "type": "object" } }, "authorizedPersons": { "type": "array", "items": { "type": "object" } }, "branch": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "opening_hours": { "type": "object" } }, "type": "object" }, "stats": { "properties": { "intransit": { "type": "integer" }, "ready": { "type": "integer" }, "balance": { "type": "string" }, "points": { "type": "integer" } }, "type": "object" }, "config": { "type": "object" }, "notice": { "nullable": true, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/notices/{id}": { "get": { "tags": [ "Notices" ], "summary": "Get notice by ID", "description": "Retrieve a specific notice by its ID", "operationId": "40428273e9e13251c66f3881174b9cd3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notice found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "notice": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "active": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Notice not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Notice not found" } }, "type": "object" } } } } } } }, "/api/v1/packages": { "get": { "tags": [ "Packages" ], "summary": "Get user packages", "description": "Retrieve packages for the authenticated user with optional filters", "operationId": "3e2bd3a9a9659ed828144e2e7e8fbf99", "parameters": [ { "name": "paid", "in": "query", "description": "Filter by payment status (false for unpaid)", "schema": { "type": "boolean" } }, { "name": "status", "in": "query", "description": "Filter by status: ready, in-transit, collected", "schema": { "type": "string", "enum": [ "ready", "in-transit", "collected" ] } }, { "name": "search", "in": "query", "description": "Search by tracking number or description", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of packages with pagination", "content": { "application/json": { "schema": { "properties": { "packages": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "current_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Packages" ], "summary": "Create package pre-alert", "description": "Create a new package pre-alert with invoice upload", "operationId": "49c779d335c9dda5147eabe204ffcf3d", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "description", "trackingNumber", "files" ], "properties": { "description": { "type": "string", "example": "Nike Shoes" }, "value": { "type": "number", "example": 150 }, "weight": { "type": "number", "example": 2.5 }, "trackingNumber": { "type": "string", "example": "1Z999AA10123456784" }, "seller": { "type": "string", "example": "Amazon" }, "courier": { "type": "integer", "example": 1 }, "files": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Pre-alert created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "No invoice submitted" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/package/{id}": { "get": { "tags": [ "Packages" ], "summary": "Get package details", "description": "Retrieve detailed information about a specific package", "operationId": "e2acd62a93eb48842d5fbc882cccfcb1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Package details", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "package": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Unauthorized - package does not belong to user" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/package/{id}/activity": { "get": { "tags": [ "Packages" ], "summary": "Get package activity history", "description": "Retrieve the tracking/activity history for a specific package", "operationId": "d0dc5ae3ec28eada4f009fad2474785f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Package activity history", "content": { "application/json": { "schema": { "properties": { "package_id": { "type": "integer" }, "tracking_number": { "type": "string" }, "description": { "type": "string" }, "activities": { "type": "array", "items": { "properties": { "activity_name": { "type": "string" }, "activity_date": { "type": "string" }, "activity_time": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/pickups": { "get": { "tags": [ "Pickup" ], "summary": "Get user pickups", "description": "Retrieve all scheduled pickups for the authenticated user", "operationId": "2008d4638a54fdb7e17c42e9122805f8", "responses": { "200": { "description": "List of pickups", "content": { "application/json": { "schema": { "properties": { "pickups": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "pickup_date": { "type": "string", "format": "date" }, "type": { "type": "string", "enum": [ "CURBSIDE", "WALKIN" ] }, "package_count": { "type": "integer" }, "cost": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Pickup" ], "summary": "Schedule a pickup", "description": "Schedule packages for branch pickup (curbside or walk-in)", "operationId": "ab2f092aa13809ca4fc284ba6fa0f03d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "package", "date", "type" ], "properties": { "package": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "date": { "type": "string", "format": "date", "example": "2024-12-20" }, "type": { "type": "string", "enum": [ "CURBSIDE", "WALKIN" ], "example": "CURBSIDE" }, "timeOfDay": { "type": "string", "example": "Morning" }, "instructions": { "type": "string" }, "paymentOption": { "type": "string", "enum": [ "CASH", "PAYPAL" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Pickup scheduled successfully" }, "500": { "description": "Same-day pickup scheduling closes at 3PM" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/pickups/{id}/cancel": { "delete": { "tags": [ "Pickup" ], "summary": "Cancel pickup", "description": "Cancel a scheduled pickup", "operationId": "19f8027f89c91fb5b8fa055b6d4de2f7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pickup cancelled successfully" }, "400": { "description": "Cannot cancel - already paid" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/pickups/validate-date": { "post": { "tags": [ "Pickup" ], "summary": "Validate pickup date", "description": "Check if a pickup date is valid and available", "operationId": "fbe45296eab77a95c177352d6d1d02eb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date", "example": "2024-12-20" } }, "type": "object" } } } }, "responses": { "200": { "description": "Date is valid" }, "406": { "description": "No date selected" }, "500": { "description": "Same-day pickup closes at 3PM" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/points": { "get": { "tags": [ "Points" ], "summary": "Get user points balance", "description": "Retrieve the current points balance for the authenticated user", "operationId": "95df75ddbd4ff2e409397ba60b64b4e7", "responses": { "200": { "description": "User points balance", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "data": { "properties": { "points": { "type": "integer", "example": 150 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/points/redeem-coupon": { "post": { "tags": [ "Points" ], "summary": "Redeem coupon code", "description": "Redeem a coupon code to earn points", "operationId": "1661992a0140586d4c3bed3a9c14d718", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code" ], "properties": { "code": { "description": "Coupon code to redeem", "type": "string", "example": "WELCOME100" } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon redeemed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Coupon redeemed successfully!" }, "data": { "properties": { "points": { "type": "integer", "example": 100 } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Invalid coupon code" }, "400": { "description": "Coupon expired or already used" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/points/use": { "post": { "tags": [ "Points" ], "summary": "Use points on package", "description": "Apply points as discount to a ready package", "operationId": "c646d05ee34e96215fac51838238c8d9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "packageId", "points" ], "properties": { "packageId": { "type": "integer", "example": 123 }, "points": { "description": "Number of points to use", "type": "integer", "example": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Points applied successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Points used!" } }, "type": "object" } } } }, "400": { "description": "Insufficient points or invalid package" }, "403": { "description": "Package does not belong to user" }, "404": { "description": "Package not found" } }, "security": [ { "bearer": [] } ] } }, "/api/v1/branches": { "get": { "tags": [ "Settings" ], "summary": "Get list of branches", "description": "Returns a list of all available branches with location and opening hours. This is a public endpoint and does not require authentication.", "operationId": "9cb02e7bb6a4f4114fe0cf2b4a7d23f2", "responses": { "200": { "description": "List of branches", "content": { "application/json": { "schema": { "properties": { "status": { "type": "integer", "example": 200 }, "branches": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "V" }, "name": { "type": "string", "example": "Village Plaza" }, "address": { "type": "string", "example": "Constant Spring Road" }, "address_line_1": { "type": "string" }, "address_line_2": { "type": "string" }, "address_line_3": { "type": "string" }, "latitude": { "type": "number", "format": "float" }, "longitude": { "type": "number", "format": "float" }, "opening_hours": { "properties": { "monday": { "type": "string" }, "tuesday": { "type": "string" }, "wednesday": { "type": "string" }, "thursday": { "type": "string" }, "friday": { "type": "string" }, "saturday": { "type": "string" }, "sunday": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } } } } } } }