Admin Sales Management: Orders and Fulfillment Status

The admin sales endpoints give administrators visibility into all purchase orders and the ability to advance orders through the fulfillment workflow. Read endpoints are accessible to both admin and demo roles; the status-update operation is restricted to full admin accounts.

GET /admin/ventas

Returns every order in the system, ordered by date descending, with a nested summary of the purchasing customer.

Property	Value
Method	`GET`
Path	`/admin/ventas`
Auth	JWT — `admin` or `demo` role

Request parameters

No query parameters or request body required.

Response

Returns an array of venta (sale) objects.

id_venta

integer

Unique identifier for the order.

id_cliente

integer

Foreign key referencing the purchasing user’s id_usuario.

total

number

Total order value in the store’s currency, calculated server-side at checkout time.

estado

string

Current fulfillment status of the order. One of pendiente, pagada, enviada, entregada, cancelada.

fecha

datetime

ISO 8601 timestamp of when the order was placed.

cliente

object

Nested summary of the customer who placed the order.

Show cliente fields

id_usuario

integer

The customer’s unique user ID.

nombre

string

The customer’s username.

Example request

curl -X GET https://api.vinylvibes.example/admin/ventas \
  -H "Authorization: Bearer <admin_token>"

Example response

[
  {
    "id_venta": 42,
    "id_cliente": 7,
    "total": "89.97",
    "estado": "enviada",
    "fecha": "2025-01-10T18:34:00.000Z",
    "cliente": {
      "id_usuario": 7,
      "nombre": "crate_digger"
    }
  }
]

Error responses

Status	Description
`401`	Missing or invalid JWT token.
`403`	Authenticated user does not have `admin` or `demo` role.
`500`	Internal server error while querying the database.

GET /admin/ventas/:id

Returns the complete record for a single order, including all line items and the full shipping address.

Property	Value
Method	`GET`
Path	`/admin/ventas/:id`
Auth	JWT — `admin` or `demo` role

Path parameters

integer

required

The unique identifier (id_venta) of the order to retrieve.

Response

Returns the full venta object, including top-level fields from GET /admin/ventas plus the expanded lineas and envio relationships.

lineas

array

Ordered line items included in this purchase.

Show lineas item fields

id_linea

integer

Unique identifier for the line item.

discogs_id

string

Discogs release ID for the vinyl record.

titulo

string

Album/release title as captured at checkout.

artista

string

Artist name as captured at checkout.

cantidad

integer

Number of units purchased.

p_unitario

number

Per-unit price at the time of purchase, computed server-side from Discogs popularity data.

subtotal

number

cantidad × p_unitario for this line.

envio

object

Full shipping address recorded at checkout.

Show envio fields

nombre_receptor

string

Full name of the person receiving the package.

calle

string

Street name.

numero_ext

string

Exterior building/street number.

numero_int

string

Interior apartment or unit number. May be null if not provided.

colonia

string

Neighborhood or district (colonia).

ciudad

string

City.

estado

string

State or province.

codigo_postal

string

Postal/ZIP code.

referencias

string

Optional delivery notes or landmark references. May be null.

Example request

curl -X GET https://api.vinylvibes.example/admin/ventas/42 \
  -H "Authorization: Bearer <admin_token>"

Example response

{
  "id_venta": 42,
  "id_cliente": 7,
  "total": "89.97",
  "estado": "enviada",
  "fecha": "2025-01-10T18:34:00.000Z",
  "cliente": {
    "id_usuario": 7,
    "nombre": "crate_digger"
  },
  "lineas": [
    {
      "id_linea": 101,
      "discogs_id": "1234567",
      "titulo": "The Dark Side of the Moon",
      "artista": "Pink Floyd",
      "cantidad": 1,
      "p_unitario": "34.99",
      "subtotal": "34.99"
    },
    {
      "id_linea": 102,
      "discogs_id": "7654321",
      "titulo": "Rumours",
      "artista": "Fleetwood Mac",
      "cantidad": 2,
      "p_unitario": "27.49",
      "subtotal": "54.98"
    }
  ],
  "envio": {
    "nombre_receptor": "Valentina Ríos",
    "calle": "Av. Insurgentes Sur",
    "numero_ext": "1602",
    "numero_int": "4B",
    "colonia": "Crédito Constructor",
    "ciudad": "Ciudad de México",
    "estado": "CDMX",
    "codigo_postal": "03940",
    "referencias": "Edificio azul frente a la farmacia"
  }
}

Error responses

Status	Description
`401`	Missing or invalid JWT token.
`403`	Authenticated user does not have `admin` or `demo` role.
`404`	No order found with the given `id_venta`.
`500`	Internal server error while querying the database.

PUT /admin/ventas/:id/estado

Updates the fulfillment status of an existing order.

Property	Value
Method	`PUT`
Path	`/admin/ventas/:id/estado`
Auth	JWT — `admin` role only

Path parameters

integer

required

The unique identifier (id_venta) of the order to update.

Body parameters

estado

string

required

The new fulfillment status. Must be one of pendiente, pagada, enviada, entregada, cancelada.

Valid states

Estado	Description
`pendiente`	Order created; payment not yet confirmed.
`pagada`	Payment confirmed. This is the initial state assigned at checkout.
`enviada`	Order has been dispatched to the carrier.
`entregada`	Order received by the customer.
`cancelada`	Order was cancelled.

Orders created through /checkout always start in the pagada state because payment is assumed confirmed at submission time. Use pendiente only when manually creating or re-opening an order outside the normal checkout flow.

Response

{
  "mensaje": "Estado actualizado a \"enviada\"."
}

Example request

curl -X PUT https://api.vinylvibes.example/admin/ventas/42/estado \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"estado": "enviada"}'

Error responses

Status	Description
`400`	`estado` is missing or not one of the five valid values.
`401`	Missing or invalid JWT token.
`403`	Authenticated user is not `admin`, or is a `demo` account (write blocked).
`500`	Internal server error while updating the database.

Auth

Catalog

User

Admin

Admin Sales Management: Orders and Fulfillment Status

GET /admin/ventas

Request parameters

Response

Example request

Example response

Error responses

GET /admin/ventas/:id

Path parameters

Response

Example request

Example response

Error responses

PUT /admin/ventas/:id/estado

Path parameters

Body parameters

Valid states

Response

Example request

Error responses

Build docs developers (and LLMs) love

Auth

Catalog

User

Admin

Documentation Index

​GET /admin/ventas

​Request parameters

​Response

​Example request

​Example response

​Error responses

​GET /admin/ventas/:id

​Path parameters

​Response

​Example request

​Example response

​Error responses

​PUT /admin/ventas/:id/estado

​Path parameters

​Body parameters

​Valid states

​Response

​Example request

​Error responses

Build docs developers (and LLMs) love

GET /admin/ventas

Request parameters

Response

Example request

Example response

Error responses

GET /admin/ventas/:id

Path parameters

Response

Example request

Example response

Error responses

PUT /admin/ventas/:id/estado

Path parameters

Body parameters

Valid states

Response

Example request

Error responses