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

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`	`<meta 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)

{
  "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)

{
  "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)

curl -X GET "https://enicebakerygh.com/api/v1/products?category=pastries-bakehouse&search=meat" \
  -H "Accept: application/json"

Success Response (HTTP 200 OK)

{
  "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)

curl -X GET "https://enicebakerygh.com/api/v1/products/signature-red-velvet-cake" \
  -H "Accept: application/json"

Success Response (HTTP 200 OK)

{
  "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)

curl -X GET "https://enicebakerygh.com/api/v1/categories" \
  -H "Accept: application/json"

Success Response (HTTP 200 OK)

{
  "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`)

{
  "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)

{
  "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)

curl -X GET "https://enicebakerygh.com/api/v1/orders/EB-20260927-1845" \
  -H "Accept: application/json"

Success Response (HTTP 200 OK)

{
  "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)

{
  "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:

{
  "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:

{
  "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):

{
  "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

{
  "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 and Payment Systems Guide.

GitBook Docs AI Assistant

REST API (v1) & Web Endpoints Reference Manual

🌐 1. Architecture, Base URLs & Conventions

Base URLs

Standard Request & Response Headers

Standard Response Envelope

Success Response Envelope (HTTP 200 / 201)

Error Response Envelope (HTTP 400 / 404 / 422 / 500)

📦 2. Catalog & Products API (/api/v1/*)

2.1 List Products

Query Parameters

Request Example (cURL)

Success Response (HTTP 200 OK)

2.2 Get Single Product Details

Path Parameters

Request Example (cURL)

Success Response (HTTP 200 OK)

2.3 List Categories

Request Example (cURL)

Success Response (HTTP 200 OK)

🛒 3. Commerce & Checkout API (/api/v1/*)

3.1 Place Storefront Order

Request Headers

Request Payload Body (CheckoutRequest)

Success Response (HTTP 201 Created)

3.2 Get Order Details by Order Number

Path Parameters

Request Example (cURL)

Success Response (HTTP 200 OK)

⚡ 4. Reactive Web & Interactive Cart Endpoints

4.1 Live Cart Drawer Data

Response (HTTP 200 OK)

4.2 Add Item to Basket

4.3 Update Item Quantity

4.4 Remove Item from Basket

4.5 Apply Promotional Coupon

🖥️ 5. Point of Sale (POS) Terminal Endpoints

5.1 Process Counter POS Sale

🔐 6. Payment Webhook Protocols

6.1 Paystack Webhook Receiver

Security & Authentication

Webhook Payload Structure

🤖 7. Model Context Protocol (MCP) Relay

7.1 GitBook MCP Assistant Endpoint

Your Bakery Basket

Your basket is empty

📦 2. Catalog & Products API (`/api/v1/*`)

🛒 3. Commerce & Checkout API (`/api/v1/*`)

Request Payload Body (`CheckoutRequest`)