VMASS Public API

VMASS Public API Documentation

Static, crawlable API documentation for search bots, integration tools, and agentic AI. This page does not require client-side JavaScript.

Open OpenAPI JSON Open Swagger UI Check API Health

Base URL

Production base URL: https://api.vmass.vn/api/public. Versioned partner endpoints are under /v1.

Machine-readable contract

/api/public/docs/openapi.json

Interactive reference

/api/public/docs

AI agent summary

/llms.txt

Authentication

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

curl -X GET "https://api.vmass.vn/api/public/v1/user" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

Core Endpoints

Method Path Purpose Permission
GET /api/public/health Public API health check. Public
GET /api/public/v1/user Connected VMASS account profile for the API partner. Valid API key
GET /api/public/v1/orders List orders with pagination and filters. orders:read
POST /api/public/v1/orders Create an order. Requires Idempotency-Key. orders:write
GET /api/public/v1/products List products. products:read
GET /api/public/v1/categories List product categories. products:read
GET /api/public/v1/inventory Read inventory and stock data. inventory:read
GET /api/public/v1/customers List customers. customers:read
POST /api/public/v1/sandbox/reset Reset test data for sandbox integrations. sandbox:write and test API key

Order Creation Example

Send a stable Idempotency-Key for each intended order. Reusing the same key returns the original response instead of creating a duplicate order. 

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"
  }'

Rate Limits, Quota, and Abuse Defense

The gateway uses API-key rate limits, monthly package quota, pre-auth throttling, and temporary lockouts for repeated suspicious traffic. Responses may include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.

Common Error Codes

Code Meaning
API_KEY_MISSINGX-API-Key header is required.
INVALID_API_KEYThe key is invalid or inactive.
PERMISSION_DENIEDThe API key lacks the required permission.
RATE_LIMIT_EXCEEDEDToo many requests in the current window.
MONTHLY_QUOTA_EXCEEDEDThe account exceeded monthly API quota.
IDEMPOTENCY_KEY_REQUIREDOrder creation requires Idempotency-Key.
API_TEMPORARILY_BLOCKEDRepeated suspicious traffic triggered a temporary lockout.