{ "openapi": "3.0.3", "info": { "title": "Shipzee Trader API", "description": "Trader Order API (`/api/v1`).\n\n## Auth\n1. `POST /auth` (username + password) **or** `POST /auth/api-key` (`apiKey` from trader profile).\n2. Send `Authorization: Bearer {token}` on all endpoints below.", "version": "1.0.0" }, "servers": [ { "url": "/api/v1", "description": "Current Shipzee installation" } ], "tags": [ { "name": "Auth", "description": "Obtain a Bearer token (no auth required)" }, { "name": "Orders", "description": "Authenticated trader order endpoints" }, { "name": "Geography", "description": "Governorates and areas" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Token", "description": "Token from POST /auth or POST /auth/api-key" } }, "schemas": { "AuthTokenResponse": { "type": "object", "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } } }, "ErrorUnauthorized": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } }, "ValidationError": { "type": "object", "properties": { "status": { "type": "string", "example": "Error" }, "response": { "type": "object", "additionalProperties": true } } }, "OrderPayload": { "type": "object", "required": ["customer_name", "customer_phone", "customer_address", "govern_id", "area_id"], "properties": { "customer_name": { "type": "string", "maxLength": 255 }, "customer_phone": { "type": "string", "description": "Egyptian mobile number" }, "customer_secondary_phone": { "type": "string", "nullable": true, "description": "Alias: customer_phone_2" }, "customer_address": { "type": "string", "description": "Alias: address_notes" }, "govern_id": { "type": "integer", "description": "Or send string alias `govern` (name_ar / name_en)" }, "area_id": { "type": "integer", "description": "Or send string alias `area` (name_ar / name_en)" }, "reference_number": { "type": "string", "nullable": true, "description": "Alias: reference_no" }, "item_description": { "type": "string", "nullable": true, "description": "Alias: shipment_description" }, "notes": { "type": "string", "nullable": true }, "pieces_count": { "type": "integer", "minimum": 1, "default": 1 }, "shipment_size": { "type": "string", "enum": ["small", "medium", "large", "xlarge", "xxlarge"], "default": "small" }, "order_type": { "type": "string", "enum": ["delivery", "return", "exchange", "pickup", "cancel"], "default": "delivery" }, "payment_type": { "type": "string", "enum": ["cod", "prepaid", "pay", "wallet"] }, "cost_from_customer": { "type": "number", "description": "Aliases: cost, goods_value" }, "allow_open": { "type": "boolean", "description": "Alias: allow_customer_to_open" }, "allow_part": { "type": "boolean", "description": "Alias: allow_customer_to_part" } }, "example": { "customer_name": "Ahmed Ali", "customer_phone": "01001234567", "customer_address": "Street 10, building 5", "govern_id": 1, "area_id": 12, "cost_from_customer": 250, "item_description": "2 t-shirts", "allow_open": true, "allow_part": false } }, "MappedOrder": { "type": "object", "properties": { "id": { "type": "integer" }, "serial_no": { "type": "string" }, "type": { "type": "string" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "customer_phone_2": { "type": "string", "nullable": true }, "govern": { "type": "string" }, "area": { "type": "string" }, "address_notes": { "type": "string", "nullable": true }, "cost": { "type": "number" }, "deliver_cost": { "type": "number" }, "shipment_description": { "type": "string", "nullable": true }, "allow_customer_to_open": { "type": "integer", "enum": [0, 1] }, "allow_customer_to_part": { "type": "integer", "enum": [0, 1] }, "allow_open": { "type": "boolean" }, "allow_part": { "type": "boolean" }, "reference_no": { "type": "string", "nullable": true }, "order_status": { "type": "string" } } }, "OrderStatusPayload": { "type": "object", "properties": { "id": { "type": "integer" }, "serial_no": { "type": "string" }, "reference_no": { "type": "string", "nullable": true }, "order_status": { "type": "string" }, "order_status_label": { "type": "string" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "updated_at": { "type": "string", "nullable": true } } }, "Govern": { "type": "object", "properties": { "id": { "type": "integer" }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "code": { "type": "string", "nullable": true } } }, "Area": { "type": "object", "properties": { "id": { "type": "integer" }, "govern_id": { "type": "integer" }, "zone_id": { "type": "integer", "nullable": true }, "name_ar": { "type": "string" }, "name_en": { "type": "string" }, "code": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "out_of_zone": { "type": "boolean" }, "label": { "type": "string" } } } }, "parameters": { "OrderIdOrCode": { "name": "order", "in": "path", "required": true, "description": "Order numeric `id` or `order_code` / serial", "schema": { "type": "string" } } } }, "paths": { "/auth": { "post": { "tags": ["Auth"], "summary": "Login with username and password", "operationId": "authPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["username", "password"], "properties": { "username": { "type": "string" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "200": { "description": "Bearer token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Not a trader account", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Trader account required" } } } } } } } } }, "/auth/api-key": { "post": { "tags": ["Auth"], "summary": "Login with trader API key", "operationId": "authApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["apiKey"], "properties": { "apiKey": { "type": "string", "description": "API key from trader profile (مفتاح API)" } } } } } }, "responses": { "200": { "description": "Bearer token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } } } }, "/": { "get": { "tags": ["Orders"], "summary": "API health / welcome", "operationId": "home", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Welcome message", "content": { "application/json": { "schema": { "type": "object", "properties": { "MSG": { "type": "string", "example": "Welcome to Saaed Shipment APIs" } } } } } } } } }, "/orders": { "get": { "tags": ["Orders"], "summary": "List trader orders (latest 200)", "description": "Optional path `/orders/{page}` is accepted for compatibility; page is ignored — always returns latest 200.", "operationId": "listOrders", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "path", "required": false, "schema": { "type": "integer" }, "description": "Ignored; kept for client compatibility" } ], "responses": { "200": { "description": "Orders list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/MappedOrder" } } } } } } } } } }, "/orders/{page}": { "get": { "tags": ["Orders"], "summary": "List trader orders (with optional page segment)", "operationId": "listOrdersPaged", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Ignored; kept for client compatibility" } ], "responses": { "200": { "description": "Orders list (same as GET /orders)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/MappedOrder" } } } } } } } } } }, "/order/{order}/details": { "get": { "tags": ["Orders"], "summary": "Get order details", "operationId": "orderDetails", "security": [{ "bearerAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/OrderIdOrCode" } ], "responses": { "200": { "description": "Order details (`order` may be `{}` if not found)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "order": { "$ref": "#/components/schemas/MappedOrder" } } } } } } } } }, "/order/{order}/status": { "get": { "tags": ["Orders"], "summary": "Get order status", "operationId": "getOrderStatus", "security": [{ "bearerAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/OrderIdOrCode" } ], "responses": { "200": { "description": "Status payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "order": { "$ref": "#/components/schemas/OrderStatusPayload" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Error" }, "message": { "type": "string" } } } } } } } } }, "/order/insert": { "post": { "tags": ["Orders"], "summary": "Create a single order", "operationId": "insertOrder", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["order"], "properties": { "order": { "$ref": "#/components/schemas/OrderPayload" } } } } } }, "responses": { "200": { "description": "Order created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "saved_order": { "$ref": "#/components/schemas/MappedOrder" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/orders/insert": { "post": { "tags": ["Orders"], "summary": "Create multiple orders", "operationId": "insertOrders", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["orders"], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPayload" } } } } } } }, "responses": { "200": { "description": "Per-order results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "422": { "description": "Missing or invalid `orders` array", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Please Add Real Data" } } } } } } } } }, "/order/{order}/update": { "post": { "tags": ["Orders"], "summary": "Update an order", "description": "Full field updates when status is Created / InProcess / AssignCaptainToReceive. Otherwise only name, phones, and allow_open / allow_part.", "operationId": "updateOrder", "security": [{ "bearerAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/OrderIdOrCode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["order"], "properties": { "order": { "$ref": "#/components/schemas/OrderPayload" } } } } } }, "responses": { "200": { "description": "Order updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "updated_order": { "$ref": "#/components/schemas/MappedOrder" } } } } } }, "404": { "description": "Order not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/order/{order}/delete": { "delete": { "tags": ["Orders"], "summary": "Delete an order", "description": "Only when order status is `Created`.", "operationId": "deleteOrder", "security": [{ "bearerAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/OrderIdOrCode" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" } } } } } }, "404": { "description": "Order not found" }, "422": { "description": "Order cannot be deleted in its current status" } } } }, "/governs": { "get": { "tags": ["Geography"], "summary": "List active governorates", "operationId": "governs", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Governorates list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "governs": { "type": "array", "items": { "$ref": "#/components/schemas/Govern" } } } } } } } } } }, "/areas": { "get": { "tags": ["Geography"], "summary": "List areas", "operationId": "areas", "security": [{ "bearerAuth": [] }], "parameters": [ { "name": "govern_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by governorate id" } ], "responses": { "200": { "description": "Areas list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "Success" }, "areas": { "type": "array", "items": { "$ref": "#/components/schemas/Area" } } } } } } } } } } } }