SansiStore Admin API Endpoints: Complete Reference

Admin endpoints require a Firebase ID token belonging to a user whose roles array in Firestore contains "admin". Pass the token in every request as Authorization: Bearer <ID_TOKEN>.

GET /api/admin/order_history

Returns the complete history, timeline, items, payment, and delivery for a single order. Supports lookup by full orderId or by the short friendly ID (the part after _).

Query Parameters

orderId

string

required

The full order ID (e.g. ord_abc123) or the short friendly suffix (e.g. abc123). Firestore is searched by exact match first; if not found, all orders are paginated server-side to match the suffix.

Response Fields

orderId

string

Full order identifier.

buyerName

string

Display name of the buyer, resolved from the users collection.

sellerName

string

Display name of the seller, resolved from the users collection. Returns "—" if no seller is set.

customerName

string | null

Customer name as stored on the order document.

customerPhone

string | null

Customer phone number.

address

string | null

Delivery address.

total

number

Order total in bolivianos.

status

string

Current order status (e.g. CREADO, CONFIRMADO, CANCELADO).

paymentStatus

string | null

Payment status string.

deliveryStatus

string | null

Delivery status string.

createdAt

string | null

ISO 8601 timestamp of order creation.

confirmedAt

string | null

ISO 8601 timestamp of seller confirmation.

cancelledAt

string | null

ISO 8601 timestamp of cancellation, if applicable.

incidentReason

string | null

Cancellation or incident reason text.

items

array

Array of orderItems sub-collection documents. Each item includes itemId, productId, productName, unitPrice, quantity, and subtotal.

payment

object | null

Payment record with paymentId, orderId, amount, method, status, registeredBy, verifiedBy, registeredAt, and verifiedAt.

delivery

object | null

Delivery record with deliveryId, courierId, courierName, status, deliveryCode, attemptNumber, incidentReason, evidenceUrl, failureReason, amountCollected, customerConfirmed, and all relevant ISO timestamps.

timeline

array

Chronologically sorted array of events. Each event has label (string), detail (string, optional), timestamp (ISO 8601 string), and type ("info" | "success" | "warning" | "error").

Example

curl -H 'Authorization: Bearer <ID_TOKEN>' \
  'https://sansistore-umss.vercel.app/api/admin/order_history?orderId=abc123'

{
  "orderId": "ord_abc123",
  "buyerName": "Ana Mamani",
  "sellerName": "Tienda Central",
  "total": 150,
  "status": "CONFIRMADO",
  "items": [
    {
      "itemId": "item_001",
      "productName": "Cuaderno universitario",
      "unitPrice": 15,
      "quantity": 10,
      "subtotal": 150
    }
  ],
  "timeline": [
    {
      "label": "Pedido creado",
      "detail": "Comprador: Ana Mamani",
      "timestamp": "2024-11-01T14:00:00.000Z",
      "type": "info"
    }
  ]
}

GET /api/admin/orders_list

Returns a paginated list of all orders, optionally filtered by status.

Query Parameters

status

string

Filter by order status. Omit to return orders of all statuses.

limit

number

Number of orders per page. Defaults to 20, maximum 50.

cursor

string

The orderId of the last item from the previous page for cursor-based pagination.

Response Fields

orders

array

Array of order summary objects. Each object contains orderId, customerName, total, status, paymentStatus, deliveryStatus, createdAt, cancelledAt, and incidentReason.

hasMore

boolean

true if there are additional pages beyond the current result.

nextCursor

string | null

The orderId to use as cursor in the next request. null when this is the last page.

Example

curl -H 'Authorization: Bearer <ID_TOKEN>' \
  'https://sansistore-umss.vercel.app/api/admin/orders_list?status=CREADO&limit=10'

{
  "orders": [
    {
      "orderId": "ord_abc123",
      "customerName": "Ana Mamani",
      "total": 150,
      "status": "CREADO",
      "paymentStatus": null,
      "deliveryStatus": null,
      "createdAt": "2024-11-01T14:00:00.000Z",
      "cancelledAt": null,
      "incidentReason": null
    }
  ],
  "hasMore": true,
  "nextCursor": "ord_abc123"
}

GET /api/admin/courier_sessions

Lists courier shift closures from the messenger_shift_closures Firestore collection, paginated and filtered by closure status.

Query Parameters

status

string

Closure status to filter by. Defaults to "closed". Other values: "validated", "rejected".

limit

number

Number of closures per page. Defaults to 20, maximum 50.

cursor

string

Document ID of the last closure from the previous page.

Response Fields

closures

array

Array of shift closure objects. Each closure includes:

id — Firestore document ID
courierId — UID of the courier
courierName — resolved display name
dateKey — string date key (e.g. "2024-11-01")
status — "closed" | "validated" | "rejected"
startedAt, closedAt, createdAt — ISO 8601 timestamps
summary — object with completedCount, pendingCount, notDeliveredCount, cancelledCount, totalCollected
completedOrders, pendingOrders, incidentOrders — arrays of order snapshots
validatedBy, validatedByName, validatedAt — validation metadata
rejectionReason — populated when status is "rejected"

hasMore

boolean

Whether additional pages exist.

nextCursor

string | null

Document ID to use as cursor in the next request.

Example

curl -H 'Authorization: Bearer <ID_TOKEN>' \
  'https://sansistore-umss.vercel.app/api/admin/courier_sessions?status=closed&limit=5'

PATCH /api/admin/courier_sessions

Approves or rejects a courier shift closure. Once a closure is "validated" or "rejected" it cannot be changed again.

Request Body

{
  "closureId": "session_doc_id",
  "action": "approve",
  "rejectionReason": ""
}

closureId

string

required

Firestore document ID of the closure to update.

action

string

required

Must be "approve" or "reject".

rejectionReason

string

Required when action is "reject". Describes why the closure was rejected.

Response

Returns the updated closure object wrapped in { message, closure }.

GET /api/admin/top_products

Returns the top-selling active products ordered by soldCount descending.

Query Parameters

limit

number

Maximum number of products to return. Defaults to 10, maximum 50.

categoryId

string

Filter results to a specific product category.

Response Fields

products

array

Array of top product objects, each containing:

productId — Firestore document ID
name — product name
categoryId — category ID
categoryName — resolved category name (falls back to "Sin categoría")
price — regular price in bolivianos
offerPrice — discounted price (omitted if no offer)
hasOffer — boolean
imageUrl — product image URL (omitted if not set)
soldCount — total units sold

total

number

Number of products returned.

Example

curl -H 'Authorization: Bearer <ID_TOKEN>' \
  'https://sansistore-umss.vercel.app/api/admin/top_products?limit=5'

{
  "products": [
    {
      "productId": "prod_xyz",
      "name": "Cuaderno universitario",
      "categoryId": "cat_papeleria",
      "categoryName": "Papelería",
      "price": 15,
      "hasOffer": false,
      "soldCount": 320
    }
  ],
  "total": 1
}

GET /api/users

Returns all platform users, optionally filtered by role or searched by name/email.

Query Parameters

role

string

Filter to users who have this role in their roles array. Valid values: admin, vendedor, mensajero, operador_inv, comprador.

string

Case-insensitive substring match against displayName and email.

Response Fields

users

array

Array of user objects sorted alphabetically by displayName. Each user contains:

uid — Firebase Auth UID
email — institutional UMSS email address
displayName — full name
phoneNumber — 8-digit Bolivian mobile number
ci — national identity number
internalPhone — internal extension (empty string if not set)
roles — array of role strings
isActive — boolean
createdBy — UID of the admin who created the account
createdAt — ISO 8601 timestamp

Example

curl -H 'Authorization: Bearer <ID_TOKEN>' \
  'https://sansistore-umss.vercel.app/api/users?role=vendedor'

POST /api/users

Creates a new UMSS platform user. Only @umss.edu domain emails are accepted.

Request Body

{
  "displayName": "Ana Mamani",
  "email": "ana.mamani@fcyt.umss.edu.bo",
  "phoneNumber": "71234567",
  "ci": "12345678",
  "roles": ["vendedor"]
}

A temporary password is generated automatically and returned in the response. The admin must share it with the new user out-of-band.

PATCH /api/users

Updates an existing user’s profile, roles, or active status.

Request Body

{
  "uid": "firebase_uid_here",
  "displayName": "Ana Mamani Torres",
  "roles": ["vendedor", "operador_inv"],
  "isActive": true
}

All fields except uid are optional. Changing roles also updates Firebase Auth custom claims.

Contributing

API Reference

SansiStore Admin API Endpoints: Complete Reference

GET /api/admin/order_history

Query Parameters

Response Fields

Example

GET /api/admin/orders_list

Query Parameters

Response Fields

Example

GET /api/admin/courier_sessions

Query Parameters

Response Fields

Example

PATCH /api/admin/courier_sessions

Request Body

Response

GET /api/admin/top_products

Query Parameters

Response Fields

Example

GET /api/users

Query Parameters

Response Fields

Example

POST /api/users

Request Body

PATCH /api/users

Request Body

Build docs developers (and LLMs) love

Contributing

API Reference

Documentation Index

​GET /api/admin/order_history

​Query Parameters

​Response Fields

​Example

​GET /api/admin/orders_list

​Query Parameters

​Response Fields

​Example

​GET /api/admin/courier_sessions

​Query Parameters

​Response Fields

​Example

​PATCH /api/admin/courier_sessions

​Request Body

​Response

​GET /api/admin/top_products

​Query Parameters

​Response Fields

​Example

​GET /api/users

​Query Parameters

​Response Fields

​Example

​POST /api/users

​Request Body

​PATCH /api/users

​Request Body

Build docs developers (and LLMs) love

GET /api/admin/order_history

Query Parameters

Response Fields

Example

GET /api/admin/orders_list

Query Parameters

Response Fields

Example

GET /api/admin/courier_sessions

Query Parameters

Response Fields

Example

PATCH /api/admin/courier_sessions

Request Body

Response

GET /api/admin/top_products

Query Parameters

Response Fields

Example

GET /api/users

Query Parameters

Response Fields

Example

POST /api/users

Request Body

PATCH /api/users

Request Body