# VMASS Public API

Base URL: https://api.vmass.vn/api/public

This is the crawlable reference for bots and agentic AI. The canonical
machine-readable contract is the OpenAPI JSON document:

https://api.vmass.vn/api/public/docs/openapi.json

Interactive Swagger UI:

https://api.vmass.vn/api/public/docs

Health check:

https://api.vmass.vn/api/public/health

Authentication:

Protected routes require the X-API-Key header. Dashboard JWT tokens are not
used for the public API.

Important write rule:

POST /api/public/v1/orders requires Idempotency-Key. Reusing the same
Idempotency-Key returns the original response instead of creating a duplicate
order.

Core endpoints:

- GET /api/public/v1/user
- GET /api/public/v1/orders
- POST /api/public/v1/orders
- GET /api/public/v1/orders/{id}
- PATCH /api/public/v1/orders/{id}/status
- GET /api/public/v1/products
- POST /api/public/v1/products
- GET /api/public/v1/categories
- GET /api/public/v1/inventory
- GET /api/public/v1/recipes
- GET /api/public/v1/customers
- POST /api/public/v1/sandbox/reset

Common error codes:

- API_KEY_MISSING
- INVALID_API_KEY
- API_KEY_EXPIRED
- PERMISSION_DENIED
- RATE_LIMIT_EXCEEDED
- MONTHLY_QUOTA_EXCEEDED
- IDEMPOTENCY_KEY_REQUIRED
- INVALID_IDEMPOTENCY_KEY
- IDEMPOTENCY_IN_PROGRESS
- API_TEMPORARILY_BLOCKED

Example:

curl -X POST "https://api.vmass.vn/api/public/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Idempotency-Key: order-20260707-0001" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"product_id":1,"quantity":2,"price":50000}],"phone":"0901234567","name":"Nguyen Van A","payment_method":"cash"}'