# REST API (v1) & Web Endpoints Reference Manual This document provides the definitive technical specification for external and internal Application Programming Interfaces (APIs) provided by **Eniceberny Bakery and Culinary Hub**. --- ## 🌐 1. Architecture, Base URLs & Conventions ```mermaid graph LR Client[Client App / Mobile / POS / Web] -->|HTTP REST JSON| Gateway[API Gateway / Laravel Router] Gateway --> Auth[Middleware / Rate Limiter] Auth --> Controllers[API v1 Controllers] Controllers --> Services[Domain Business Services] Services --> DB[(PostgreSQL / SQLite Database)] ``` ### Base URLs - **Production API**: `https://enicebakerygh.com/api/v1` - **Documentation & MCP Relay**: `https://enicebakerygh.com/docs/~gitbook/mcp` - **Local Development**: `http://localhost:8000/api/v1` ### Standard Request & Response Headers All client applications communicating with the API must transmit the following HTTP headers: | Header | Expected Value | Purpose | | :--- | :--- | :--- | | `Content-Type` | `application/json` | Designates the payload formatting | | `Accept` | `application/json` | Enforces JSON response formatting | | `X-Requested-With`| `XMLHttpRequest` | Flags Ajax request context | | `X-CSRF-TOKEN` | `` | Required for web-session based mutations | ### Standard Response Envelope All API v1 endpoints return a uniform JSON envelope structure: #### Success Response Envelope (HTTP 200 / 201) ```json { "success": true, "message": "Human-readable confirmation message", "data": {}, "pagination": { "current_page": 1, "last_page": 5, "total": 95 } } ``` #### Error Response Envelope (HTTP 400 / 404 / 422 / 500) ```json { "success": false, "message": "The given data was invalid.", "errors": { "customer_phone": [ "Please enter a valid Ghanaian phone number (e.g. 024XXXXXXX or +233XXXXXXXXX)." ] } } ``` --- ## 📦 2. Catalog & Products API (`/api/v1/*`) ### 2.1 List Products `GET /api/v1/products` Retrieve a paginated collection of active, available delicacies and bakery items. #### Query Parameters | Parameter | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | `category` | `string` | No | `null` | Filter by category slug (e.g. `continental-dishes`, `pastries-bakehouse`) | | `search` | `string` | No | `null` | Keystroke search against item name or short description | | `page` | `integer`| No | `1` | Pagination page number | #### Request Example (cURL) ```bash curl -X GET "https://enicebakerygh.com/api/v1/products?category=pastries-bakehouse&search=meat" \ -H "Accept: application/json" ``` #### Success Response (HTTP 200 OK) ```json { "success": true, "data": [ { "id": 4, "name": "Golden Flaky Beef Meat Pie", "slug": "golden-flaky-beef-meat-pie", "sku": "BAKE-PIE-001", "short_description": "Buttery shortcrust pastry filled with minced lean beef, vegetables, and savory spices.", "price": "18.00", "sale_price": null, "category": { "id": 3, "name": "Pastries & Bakehouse", "slug": "pastries-bakehouse" }, "primary_image": { "id": 14, "image_path": "images/photo_4_2026-09-25_18-09-31.jpg", "alt_text": "Golden Flaky Beef Meat Pie" }, "variants": [ { "id": 8, "name": "Single Portion", "price": "18.00", "stock_quantity": 45 }, { "id": 9, "name": "Box of 6 (Party Pack)", "price": "100.00", "stock_quantity": 10 } ] } ], "pagination": { "current_page": 1, "last_page": 1, "total": 1 } } ``` --- ### 2.2 Get Single Product Details `GET /api/v1/products/{slug}` Retrieve full product attributes, image galleries, portion variants, and customizable options. #### Path Parameters | Parameter | Type | Description | | :--- | :--- | :--- | | `slug` | `string` | Unique product slug (e.g. `signature-red-velvet-cake`) | #### Request Example (cURL) ```bash curl -X GET "https://enicebakerygh.com/api/v1/products/signature-red-velvet-cake" \ -H "Accept: application/json" ``` #### Success Response (HTTP 200 OK) ```json { "success": true, "data": { "id": 1, "name": "Signature Red Velvet Celebration Cake", "slug": "signature-red-velvet-cake", "sku": "CK-RED-001", "description": "Layers of rich buttermilk sponge with Madagascar vanilla cream cheese frosting.", "price": "280.00", "category": { "id": 1, "name": "Celebration Cakes", "slug": "celebration-cakes" }, "images": [ { "id": 1, "image_path": "images/photo_7_2026-09-25_18-09-31.jpg", "is_primary": true } ], "variants": [ { "id": 1, "name": "6-inch (Feeds 6-8)", "price": "280.00", "stock_quantity": 12 }, { "id": 2, "name": "8-inch (Feeds 12-16)", "price": "400.00", "stock_quantity": 8 }, { "id": 3, "name": "10-inch (Feeds 20+)", "price": "580.00", "stock_quantity": 4 } ], "options": [ { "id": 1, "name": "Cake Inscription", "type": "text", "is_required": false }, { "id": 2, "name": "Frosting Style", "type": "select", "is_required": true, "values": [ { "id": 1, "name": "Smooth Modern Finish", "price_modifier": "0.00" }, { "id": 2, "name": "Textured Rosettes (+GH₵ 30)", "price_modifier": "30.00" } ] } ] } } ``` --- ### 2.3 List Categories `GET /api/v1/categories` Retrieve all active culinary categories with product count metadata. #### Request Example (cURL) ```bash curl -X GET "https://enicebakerygh.com/api/v1/categories" \ -H "Accept: application/json" ``` #### Success Response (HTTP 200 OK) ```json { "success": true, "data": [ { "id": 1, "name": "Pastries & Bakehouse", "slug": "pastries-bakehouse", "products_count": 8 }, { "id": 2, "name": "Continental Dishes", "slug": "continental-dishes", "products_count": 6 }, { "id": 3, "name": "Authentic Ghanaian Cuisine", "slug": "ghanaian-cuisine", "products_count": 7 }, { "id": 4, "name": "Celebration Cakes", "slug": "celebration-cakes", "products_count": 5 }, { "id": 5, "name": "Fresh Drinks & Juices", "slug": "fresh-drinks-juices", "products_count": 4 } ] } ``` --- ## 🛒 3. Commerce & Checkout API (`/api/v1/*`) ### 3.1 Place Storefront Order `POST /api/v1/checkout` Atomically validates cart items, customer details, calculates delivery fees, creates the order, and initializes payment. #### Request Headers - `Content-Type: application/json` - `Accept: application/json` #### Request Payload Body (`CheckoutRequest`) ```json { "customer_name": "Kwame Mensah", "customer_phone": "0244123456", "customer_email": "kwame.mensah@example.com", "order_type": "delivery", "delivery_address": "Plot 14 Block B, Ahodwo", "delivery_city": "Kumasi", "gps_address": "AK-039-2311", "landmark": "Near Shell Petrol Station", "payment_method": "momo", "special_instructions": "Extra shito pepper sauce please", "items": [ { "product_id": 4, "quantity": 2, "variant_id": 8, "notes": "Serve hot" } ] } ``` #### Success Response (HTTP 201 Created) ```json { "success": true, "message": "Order created successfully.", "order": { "id": 89, "order_number": "EB-20260927-1845", "customer_name": "Kwame Mensah", "customer_phone": "0244123456", "subtotal": "36.00", "delivery_fee": "15.00", "discount_amount": "0.00", "total": "51.00", "status": "pending", "payment_status": "pending", "payment_method": "momo", "order_type": "delivery", "items": [ { "id": 142, "product_name": "Golden Flaky Beef Meat Pie", "quantity": 2, "unit_price": "18.00", "subtotal": "36.00" } ] }, "payment": { "gateway": "momo", "reference": "EB-PAY-68DE1049", "redirect_url": "https://checkout.paystack.com/3f08b3e9x8", "instructions": "Authorize the prompt sent to your mobile phone." } } ``` --- ### 3.2 Get Order Details by Order Number `GET /api/v1/orders/{orderNumber}` Look up complete order state, items, live delivery tracking history, and financial receipts. #### Path Parameters | Parameter | Type | Description | | :--- | :--- | :--- | | `orderNumber` | `string` | Unique order identifier (e.g. `EB-20260927-1845`) | #### Request Example (cURL) ```bash curl -X GET "https://enicebakerygh.com/api/v1/orders/EB-20260927-1845" \ -H "Accept: application/json" ``` #### Success Response (HTTP 200 OK) ```json { "success": true, "data": { "id": 89, "order_number": "EB-20260927-1845", "status": "preparing", "payment_status": "paid", "subtotal": "36.00", "delivery_fee": "15.00", "total": "51.00", "items": [ { "product_name": "Golden Flaky Beef Meat Pie", "quantity": 2, "unit_price": "18.00", "subtotal": "36.00" } ], "status_histories": [ { "status": "pending", "notes": "Order placed by customer", "created_at": "2026-09-27T18:45:10Z" }, { "status": "confirmed", "notes": "Payment received via MoMo", "created_at": "2026-09-27T18:46:02Z" }, { "status": "preparing", "notes": "In bakehouse oven", "created_at": "2026-09-27T18:48:30Z" } ], "transactions": [ { "transaction_reference": "EB-PAY-68DE1049", "gateway": "momo", "amount": "51.00", "currency": "GHS", "status": "success", "paid_at": "2026-09-27T18:46:02Z" } ] } } ``` --- ## ⚡ 4. Reactive Web & Interactive Cart Endpoints These endpoints power the Alpine.js sliding shopping cart drawer and instant client interactions. ### 4.1 Live Cart Drawer Data `GET /cart/drawer-data` Fetches real-time shopping cart count and rendered subtotal. #### Response (HTTP 200 OK) ```json { "items_count": 3, "subtotal": "GH₵ 72.00", "items": [ { "id": 104, "product_id": 4, "name": "Golden Flaky Beef Meat Pie", "quantity": 2, "unit_price": "GH₵ 18.00", "line_total": "GH₵ 36.00", "image": "/images/photo_4_2026-09-25_18-09-31.jpg" } ] } ``` ### 4.2 Add Item to Basket `POST /cart/add` - **Payload**: ```json { "product_id": 4, "quantity": 1, "variant_id": 8, "options": { "inscription": "Congratulations!" } } ``` - **Response**: `{ "success": true, "message": "Added to cart", "cart_count": 4 }` ### 4.3 Update Item Quantity `POST /cart/update/{itemId}` - **Payload**: `{ "quantity": 3 }` - **Response**: `{ "success": true, "subtotal": "GH₵ 108.00" }` ### 4.4 Remove Item from Basket `DELETE /cart/remove/{itemId}` - **Response**: `{ "success": true, "message": "Item removed" }` ### 4.5 Apply Promotional Coupon `POST /cart/apply-coupon` - **Payload**: `{ "code": "ENICEWELCOME10" }` - **Response**: `{ "success": true, "discount_amount": "GH₵ 10.00", "new_total": "GH₵ 98.00" }` --- ## 🖥️ 5. Point of Sale (POS) Terminal Endpoints ### 5.1 Process Counter POS Sale `POST /admin/pos/checkout` - **Payload**: ```json { "customer_name": "Walk-in Guest", "customer_phone": "0532342126", "payment_method": "cash", "order_type": "takeaway", "discount_amount": 0.00, "items": [ { "id": 4, "name": "Golden Flaky Beef Meat Pie", "quantity": 2, "price": 18.00 } ] } ``` - **Response (HTTP 200 OK)**: ```json { "success": true, "order_id": 142, "order_number": "EB-20260927-9912", "receipt_url": "/orders/EB-20260927-9912/receipt" } ``` --- ## 🔐 6. Payment Webhook Protocols ### 6.1 Paystack Webhook Receiver `POST /webhooks/paystack` Receives asynchronous server-to-server transaction notifications. #### Security & Authentication - Header: `X-Paystack-Signature` - The payload HMAC SHA512 hash must match the signature computed with `PAYSTACK_SECRET_KEY`. #### Webhook Payload Structure ```json { "event": "charge.success", "data": { "reference": "EB-PAY-68DE1049", "amount": 5100, "currency": "GHS", "status": "success", "gateway_response": "Approved", "paid_at": "2026-09-27T18:46:02.000Z", "channel": "mobile_money", "metadata": { "order_number": "EB-20260927-1845" } } } ``` --- ## 🤖 7. Model Context Protocol (MCP) Relay ### 7.1 GitBook MCP Assistant Endpoint `POST /docs/~gitbook/mcp` Relays automated Model Context Protocol requests from the embedded GitBook AI assistant directly to `https://docs.enicebakerygh.com/~gitbook/mcp`. - **Headers**: `Content-Type: application/json` - **Supported Methods**: `POST`, `OPTIONS` - **Authentication**: Origin-verified cross-site request relay. --- *For database entities or payment configurations, consult the [Database Schema Guide](database.md) and [Payment Systems Guide](payments.md).*