{"id":29626296,"url":"https://github.com/emhash/courier-api","last_synced_at":"2025-10-28T05:03:55.068Z","repository":{"id":303852354,"uuid":"1016863470","full_name":"emhash/courier-api","owner":"emhash","description":"A Courier Service Backend System API","archived":false,"fork":false,"pushed_at":"2025-07-09T20:25:45.000Z","size":648,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T03:36:58.904Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emhash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-09T16:35:03.000Z","updated_at":"2025-07-09T20:24:38.000Z","dependencies_parsed_at":"2025-07-10T03:49:05.093Z","dependency_job_id":"1adaec1f-095d-45b6-ba65-ba3fc75f9863","html_url":"https://github.com/emhash/courier-api","commit_stats":null,"previous_names":["emhash/courier-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/emhash/courier-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emhash%2Fcourier-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emhash%2Fcourier-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emhash%2Fcourier-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emhash%2Fcourier-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emhash","download_url":"https://codeload.github.com/emhash/courier-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emhash%2Fcourier-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266255363,"owners_count":23900128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-21T07:05:29.365Z","updated_at":"2025-10-28T05:03:50.023Z","avatar_url":"https://github.com/emhash.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚚 Courier Management System - Backend API\n\nA comprehensive RESTful API for courier and delivery management, built with Django REST Framework. Features role-based access control, integrated Stripe payments, and complete order lifecycle management.\n\n## 📄 Project Overview\n\nThis system provides a complete backend solution for courier services with:\n\n- **Multi-role Authentication** (Admin, Delivery Personnel, Customers)\n- **Order Management** with real-time status tracking\n- **Integrated Stripe Payments** with webhook automation\n- **Role-based Permissions** ensuring secure access\n- **Comprehensive API Documentation** with Swagger UI\n- **Payment Success/Cancel Pages** for seamless UX\n\n## 🔗 Live Links\n\n| Resource | URL |\n|----------|-----|\n| **🌐 Live API** | **https://courierapi.pythonanywhere.com** |\n| **📖 API Documentation** | **https://courierapi.pythonanywhere.com/api/docs/** |\n| **📋 Admin Panel** | **https://courierapi.pythonanywhere.com/admin/** |\n| **📂 GitHub Repository** | **https://github.com/emhash/courier-api** |\n| **📮 Postman Collection** | [Download JSON](./Courier_Management_API.postman_collection.json) |\n\n## 🗄️ Database Schema\n\n![Database ERD](./model_diagram.png)\n\n### Core Models\n- **User**: Authentication with role-based access (admin, delivery_man, user)\n- **Order**: Complete order lifecycle with customer assignment \n- **Payment**: Stripe integration for secure transactions\n\n![UML Class Diagram](./courier_project_uml.png)\n\n## 🔐 Login Credentials\n| Role | Username | Password | Email |\n|------|----------|----------|-------|\n| **Super Admin** | `admin` | `admin` | admin@gmail.com |\n| **Admin** | `ashiq` | `111111qqqqqq` | md.e.h.ashiq@gmail.com |\n| **Delivery Man** | `rafiq` | `111111qqqqqq` | rafiq@gmail.com |\n| **Customer** | `shafiq` | `111111qqqqqq` | shafiq@gmail.com |\n\n## 🚀 Quick Start\n\n### 1. Local Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/emhash/courier-api.git\ncd courier-api\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Environment setup (.env file)\nSECRET_KEY=\nDEBUG=True\nSTRIPE_SECRET_KEY=\nSTRIPE_WEBHOOK_SECRET=\nFRONTEND_URL=\n\n# Database setup\npython manage.py migrate\npython manage.py createsuperuser\n\n# Run development server\npython manage.py runserver\n```\n\n### 2. Access Points\n- **API Documentation**: http://localhost:8000/api/docs/\n- **Admin Panel**: http://localhost:8000/admin/\n- **Homepage**: Redirects to API documentation\n\n---\n\n## 📚 API Documentation\n\n### Base URL\n- **Live**: `https://courierapi.pythonanywhere.com`\n- **Local**: `http://localhost:8000`\n\nAll endpoints return standardized responses:\n\n**Success Response Format:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 201,\n    \"message\": \"Operation completed successfully\",\n    \"Data\": { /* response data */ }\n}\n```\n\n**Error Response Format:**\n```json\n{\n    \"success\": false,\n    \"message\": \"Validation error occurred.\",\n    \"errorDetails\": {\n        \"field\": \"email\",\n        \"message\": \"Invalid email format.\"\n    }\n}\n```\n\n---\n\n## 🔑 Authentication Endpoints\n\n### Register New User\n**`POST /api/v1/auth/register/`**\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/auth/register/' \\\n--form 'email=\"newuser@gmail.com\"' \\\n--form 'password=\"111111qqqqqq\"' \\\n--form 'username=\"newuser\"' \\\n--form 'confirm_password=\"111111qqqqqq\"' \\\n--form 'role=\"user\"'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 201,\n    \"message\": \"User Registration successful\",\n    \"Data\": {\n        \"username\": \"newuser\",\n        \"email\": \"newuser@gmail.com\",\n        \"role\": \"user\",\n        \"access\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n    }\n}\n```\n\n**Available Roles:** `admin`, `delivery_man`, `user`\n\n### User Login\n**`POST /api/v1/auth/login/`**\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/auth/login/' \\\n--form 'username_or_email=\"shafiq@gmail.com\"' \\\n--form 'password=\"111111qqqqqq\"'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 200,\n    \"message\": \"Login successful\",\n    \"Data\": {\n        \"username\": \"shafiq\",\n        \"email\": \"shafiq@gmail.com\",\n        \"role\": \"user\",\n        \"access\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n        \"refresh\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n    }\n}\n```\n\n### Get User Profile\n**`GET /api/v1/auth/profile/`** *(Requires Authorization)*\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/auth/profile/' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n```\n\n### Update Profile\n**`PUT /api/v1/auth/profile/`** *(Requires Authorization)*\n\n```bash\ncurl --location --request PUT 'https://courierapi.pythonanywhere.com/api/v1/auth/profile/' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n--form 'first_name=\"John\"' \\\n--form 'last_name=\"Doe\"'\n```\n\n---\n\n## 📦 Order Management Endpoints\n\n### Create Order (Without Payment)\n**`POST /api/v1/orders/create/`** *(Requires Authorization - User Role)*\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/orders/create/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n--data '{\n    \"description\": \"Pickup documents from Gulshan office and deliver to Dhanmondi residence\",\n    \"address\": \"House 45, Road 12A, Dhanmondi, Dhaka-1209\",\n    \"cost\": \"250.00\"\n}'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 201,\n    \"message\": \"Order created successfully\",\n    \"Data\": {\n        \"id\": 4,\n        \"customer\": \"shafiq\",\n        \"delivery_man\": null,\n        \"payment_status\": null,\n        \"has_payment\": false,\n        \"description\": \"Pickup documents from Gulshan office and deliver to Dhanmondi residence\",\n        \"address\": \"House 45, Road 12A, Dhanmondi, Dhaka-1209\",\n        \"cost\": \"250.00\",\n        \"status\": \"PENDING\",\n        \"created_at\": \"2025-07-09T19:08:53.403473Z\",\n        \"updated_at\": \"2025-07-09T19:08:53.403517Z\"\n    }\n}\n```\n\n###  Create Order WITH Payment\n**`POST /api/v1/orders/create/`** *(Single API Call)*\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/orders/create/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n--data '{\n    \"description\": \"Pickup documents from office\",\n    \"address\": \"House 45, Road 12A, Dhanmondi\",\n    \"cost\": \"50.00\",\n    \"create_payment\": true\n}'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 201,\n    \"message\": \"Order created successfully. Redirect user to checkout_url to complete payment.\",\n    \"Data\": {\n        \"id\": 5,\n        \"customer\": \"shafiq\",\n        \"delivery_man\": null,\n        \"payment_status\": \"PENDING\",\n        \"has_payment\": true,\n        \"description\": \"Pickup documents from office\",\n        \"address\": \"House 45, Road 12A, Dhanmondi\",\n        \"cost\": \"50.00\",\n        \"status\": \"PENDING\",\n        \"created_at\": \"2025-07-09T19:19:53.369943Z\",\n        \"updated_at\": \"2025-07-09T19:19:53.370005Z\",\n        \"checkout_url\": \"https://checkout.stripe.com/c/pay/cs_test_...\",\n        \"session_id\": \"cs_test_...\"\n    }\n}\n```\n\n**Key Features:**\n- ✅ Single API call creates order + payment\n- ✅ Returns Stripe checkout URL immediately  \n- ✅ Automatic webhook handling for payment status\n- ✅ Optional custom success/cancel URLs\n\n### List Orders\n**`GET /api/v1/orders/`** *(Role-based filtering)*\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/orders/' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n```\n\n**Access Control:**\n- **Admin**: See all orders\n- **Delivery Man**: See assigned orders only\n- **User**: See own orders only\n\n### Get Order Details\n**`GET /api/v1/orders/{id}/`**\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/orders/4/' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n```\n\n### Update Order (Admin)\n**`PATCH /api/v1/orders/{id}/update/`** *(Admin Only)*\n\n```bash\ncurl --location --request PATCH 'https://courierapi.pythonanywhere.com/api/v1/orders/4/update/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ADMIN_ACCESS_TOKEN' \\\n--data '{\n    \"delivery_man\": \"rafiq\",\n    \"status\": \"PENDING\",\n    \"description\": \"Get the delivery fast\",\n    \"address\": \"Dhaka\"\n}'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 200,\n    \"message\": \"Order updated successfully\",\n    \"Data\": {\n        \"id\": 4,\n        \"customer\": \"shafiq\",\n        \"delivery_man\": \"rafiq\",\n        \"payment_status\": \"PENDING\",\n        \"has_payment\": true,\n        \"description\": \"Get the delivery fast\",\n        \"address\": \"Dhaka\",\n        \"cost\": \"250.00\",\n        \"status\": \"PENDING\",\n        \"created_at\": \"2025-07-09T19:08:53.403473Z\",\n        \"updated_at\": \"2025-07-09T19:27:46.085245Z\"\n    }\n}\n```\n\n### Update Order Status (Delivery Man)\n**`PATCH /api/v1/orders/{id}/update/`** *(Delivery Man - Status Only)*\n\n```bash\ncurl --location --request PATCH 'https://courierapi.pythonanywhere.com/api/v1/orders/5/update/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer DELIVERY_MAN_TOKEN' \\\n--data '{\n    \"status\": \"DELIVERED\"\n}'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 200,\n    \"message\": \"Order status updated successfully\",\n    \"Data\": {\n        \"id\": 5,\n        \"customer\": \"shafiq\",\n        \"delivery_man\": \"rafiq\",\n        \"payment_status\": \"SUCCEEDED\",\n        \"has_payment\": true,\n        \"description\": \"Pickup documents from office\",\n        \"address\": \"House 45, Road 12A, Dhanmondi\",\n        \"cost\": \"50.00\",\n        \"status\": \"DELIVERED\",\n        \"created_at\": \"2025-07-09T19:19:53.369943Z\",\n        \"updated_at\": \"2025-07-09T19:31:57.707559Z\"\n    }\n}\n```\n\n---\n\n## 💳 Payment Integration\n\n### Payment for Existing Order\n**`POST /api/v1/payments/checkout/`** *(Create Stripe Checkout)*\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/payments/checkout/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n--data '{\n    \"order_id\": 4\n}'\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"statusCode\": 201,\n    \"message\": \"Checkout session created successfully. Redirect user to checkout_url\",\n    \"Data\": {\n        \"checkout_url\": \"https://checkout.stripe.com/c/pay/cs_test_...\",\n        \"session_id\": \"cs_test_...\",\n        \"order_id\": 4,\n        \"amount\": 250.0\n    }\n}\n```\n\n### Retry Failed Payment\n**`POST /api/v1/payments/retry/{payment_id}/`**\n\n```bash\ncurl --location 'https://courierapi.pythonanywhere.com/api/v1/payments/retry/1/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n```\n\n### Stripe Webhook (Automatic)\n**`POST /api/v1/payments/webhook/`** *(No Auth - Webhook Signature)*\n\nThis endpoint is automatically called by Stripe to update payment statuses. It handles:\n- `checkout.session.completed` → Payment Success\n- `checkout.session.expired` → Session Timeout  \n- `payment_intent.succeeded` → Backup Confirmation\n- `payment_intent.payment_failed` → Payment Failure\n\n---\n\n![Payment Success](./payment-success.jpg)\n\n## 🎨 Payment UI Pages\n\n### Success Page\n**URL**: `https://courierapi.pythonanywhere.com/payment/success/`\n- ✅ Payment confirmation display\n- ✅ Session ID tracking\n- ✅ Modern responsive design\n- ✅ Automatic status updates\n\n### Cancel Page  \n**URL**: `https://courierapi.pythonanywhere.com/payment/cancel/`\n- ❌ Payment cancellation handling\n- 🔄 Retry payment functionality\n- 📝 Order tracking via URL parameters\n- 🎯 User-friendly error messaging\n\n---\n\n## 🔐 Role-Based Access Control\n\n### Admin Permissions\n- ✅ Manage all orders (create, read, update, delete)\n- ✅ Assign delivery personnel to orders\n- ✅ View all payments and transactions\n- ✅ User management capabilities\n\n### Delivery Man Permissions  \n- ✅ View assigned orders only\n- ✅ Update order status (PENDING → IN_PROGRESS → DELIVERED)\n- ❌ Cannot modify order details or assign other delivery men\n- ❌ Cannot access other users' orders\n\n### User (Customer) Permissions\n- ✅ Create new orders\n- ✅ View own orders only\n- ✅ Process payments for orders\n- ✅ Retry failed payments\n- ❌ Cannot access other users' data\n\n---\n\n\n## 📂 Project Structure\n\n```\ncourier-api/\n├── apps/\n│   ├── users/          # Authentication \u0026 user management\n│   ├── orders/         # Order CRUD operations\n│   └── payments/       # Stripe integration\n├── core/\n│   ├── settings/       # Django configuration  \n│   └── urls.py         # URL routing\n├── templates/\n│   └── payment/        # Success/cancel pages\n├── static/             # Static files\n├── requirements.txt    # Dependencies\n└── README.md          # This file\n```\n\n---\n\n## 🚀 Deployment\n\nThe API is deployed on **PythonAnywhere** with:\n- ✅ SSL Certificate (HTTPS)\n- ✅ Database persistence\n- ✅ Environment variable security\n- ✅ Stripe webhook endpoints\n- ✅ Static file serving\n\n**Live API**: https://courierapi.pythonanywhere.com\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femhash%2Fcourier-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femhash%2Fcourier-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femhash%2Fcourier-api/lists"}