The Avanzar In Time Shop backend is a Hono v4 REST API running on Bun. Every response body is JSON — successes and errors alike follow a consistent shape. All business endpoints live under theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/ItsJhonAlex/Ecommerce/llms.txt
Use this file to discover all available pages before exploring further.
/api/v1 prefix so the version can evolve independently. An interactive Swagger UI is available at /api/v1/docs and the raw OpenAPI spec is served at /api/v1/openapi.json, making it easy to explore and test every route without leaving the browser.
Base URL
The development server listens on port3000:
/api/v1. For example, the products list is available at http://localhost:3000/api/v1/products.
Endpoint Groups
The API is split into two families: public routes that the storefront and authenticated customers can reach, and admin routes gated behindrequireAdmin middleware.
Public: Products
Browse and search the active product catalog available to all storefront visitors.
Public: Categories
Retrieve the category tree used to organise and filter products.
Public: Checkout
Submit orders, select shipping rates, and initiate the payment flow.
Public: Orders
Let authenticated customers view and track their own order history.
Public: Addresses
Create, update, and manage saved delivery addresses for a customer account.
Public: Shipping Rates
Fetch available shipping options and their rates for a given destination.
Admin: Products
Create, update, archive, and manage product inventory — staff and admin only.
Admin: Orders
View all orders, advance order status, and confirm or reject payments.
Authentication
The API uses session cookies issued by Better Auth — there are no API keys or Bearer tokens. Auth endpoints live at/api/auth/* and are handled separately from the versioned API.
Two middleware guards protect business routes:
requireSession— requires any valid session. Used on customer-facing routes such as order history and saved addresses.requireAdmin— requires a session whose role isstafforadmin. Used on every route under/api/v1/admin/.
Response Format
All responses use a consistent JSON envelope so client code can handle them uniformly. Success responses wrap the returned data in a named key that matches the resource:"error" string. Some errors include additional fields to give the client machine-readable context:
HTTP Status Codes
| Status | Meaning | When it is returned |
|---|---|---|
200 OK | Success | Successful GET or PATCH |
201 Created | Resource created | Successful POST that produces a new resource |
204 No Content | Deleted | Successful DELETE — no body |
400 Bad Request | Bad input | Invalid request body schema or query parameters |
401 Unauthorized | No session | Request reaches a protected route without a valid session cookie |
403 Forbidden | Insufficient role | Authenticated user lacks the staff or admin role |
404 Not Found | Missing resource | The requested product, order, address, etc. does not exist |
409 Conflict | Duplicate | Slug already taken, duplicate price currency for a product, or double payment confirmation |
422 Unprocessable Entity | Business rule violation | Invalid order status transition, insufficient stock at checkout |
503 Service Unavailable | Temporary failure | Order number collision after maximum retry attempts |
500 Internal Server Error | Unexpected error | An unhandled exception was caught by the global error handler |