Sales API Endpoints — Checkout and Order History

The Sales API powers the checkout flow and order history for AutoPart Pro. Both endpoints require authentication. GET /api/sales is role-aware: admin users receive every order ever placed across all customers, while users with the client role see only their own orders. POST /api/sales executes a full checkout inside a MySQL transaction — it inserts the sale record, creates individual line items, and decrements inventory stock atomically. If any step fails, the entire transaction is rolled back so inventory counts never fall out of sync with recorded sales.

GET /api/sales

Retrieves order history. The response is scoped automatically by the authenticated user’s role: admins receive all sales with customer identity fields (user_name, user_email), while clients receive only their own orders without those fields.

Each sale includes a nested items array built server-side using JSON_ARRAYAGG. The array always contains at least one entry because a sale cannot be created with an empty cart.

Example request — as admin

curl -X GET https://api.autopartpro.com/api/sales \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiNm9sZSI6ImFkbWluIiwiaWF0IjoxNzEwODY0MDAwLCJleHAiOjE3MTA4Njc2MDB9.admintoken"

Example request — as client

curl -X GET https://api.autopartpro.com/api/sales \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInJvbGUiOiJjbGllbnQiLCJpYXQiOjE3MTA4NjQwMDAsImV4cCI6MTcxMDg2NzYwMH0.xyz789"

Responses

success

boolean

true on a successful fetch.

data

array

Array of sale objects ordered by created_at DESC.

Show sale fields

integer

Auto-incremented sale ID.

total

float

Sum of all line items (quantity × unit_price). Always returned as a float.

status

string

Current order status. One of "pending", "completed", or "cancelled".

created_at

string

ISO 8601 timestamp of when the order was placed.

user_name

string

Full name of the customer. Admin only — not present in client-scoped responses.

user_email

string

Email of the customer. Admin only — not present in client-scoped responses.

items

array

Line items for this order.

Show item fields

product_id

integer

ID of the product purchased.

product_name

string

Name of the product at the time of purchase.

quantity

integer

Number of units purchased.

unit_price

float

Price per unit charged at checkout.

200 — OK (admin response)

{
  "success": true,
  "data": [
    {
      "id": 18,
      "total": 103.48,
      "status": "completed",
      "created_at": "2024-03-20T16:45:00.000Z",
      "user_name": "Carlos Mendoza",
      "user_email": "carlos.mendoza@example.com",
      "items": [
        {
          "product_id": 7,
          "product_name": "Filtro de Aceite Premium",
          "quantity": 2,
          "unit_price": 12.99
        },
        {
          "product_id": 23,
          "product_name": "Pastillas de Freno Delanteras",
          "quantity": 2,
          "unit_price": 38.75
        }
      ]
    }
  ]
}

200 — OK (client response)

{
  "success": true,
  "data": [
    {
      "id": 18,
      "total": 103.48,
      "status": "completed",
      "created_at": "2024-03-20T16:45:00.000Z",
      "items": [
        {
          "product_id": 7,
          "product_name": "Filtro de Aceite Premium",
          "quantity": 2,
          "unit_price": 12.99
        },
        {
          "product_id": 23,
          "product_name": "Pastillas de Freno Delanteras",
          "quantity": 2,
          "unit_price": 38.75
        }
      ]
    }
  ]
}

401 — No token provided

{
  "message": "No autorizado, no se proporcionó un token."
}

401 — Invalid or expired token

{
  "message": "Token no válido o expirado."
}

POST /api/sales

Processes a checkout for the authenticated user. The server computes the order total by summing quantity × unit_price for every item in the request — the client-supplied unit_price values are the source of truth and should match the current product prices fetched from GET /api/products. The entire operation runs inside a MySQL transaction: if inserting any line item or decrementing any product’s stock fails, the whole transaction is rolled back and no data is persisted.

Stock is decremented atomically during the transaction using UPDATE products SET stock = stock - ? WHERE id = ?. There is no inventory reservation step — concurrent purchases of the same product can result in negative stock if you do not enforce a check constraint at the database level.

Request body

items

array

required

An array of line items to purchase. Must contain at least one entry; an empty array returns a 400 error.

Show item fields

product_id

number

required

The database ID of the product to purchase.

quantity

number

required

Number of units to buy. Should be a positive integer.

unit_price

number

required

Price per unit at the time of checkout. The server multiplies this by quantity to compute the line-item subtotal.

Example request

curl -X POST https://api.autopartpro.com/api/sales \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInJvbGUiOiJjbGllbnQiLCJpYXQiOjE3MTA4NjQwMDAsImV4cCI6MTcxMDg2NzYwMH0.xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": 7,
        "quantity": 2,
        "unit_price": 12.99
      },
      {
        "product_id": 23,
        "quantity": 2,
        "unit_price": 38.75
      },
      {
        "product_id": 11,
        "quantity": 1,
        "unit_price": 6.25
      }
    ]
  }'

Responses

success

boolean

true when the transaction commits successfully.

message

string

Confirmation: "Compra realizada con éxito."

saleId

integer

The auto-incremented ID of the newly created sale record. Use this to retrieve the order later via GET /api/sales.

201 — Created

{
  "success": true,
  "message": "Compra realizada con éxito.",
  "saleId": 19
}

400 — Empty cart

{
  "success": false,
  "message": "El carrito está vacío."
}

500 — Transaction failure (rolled back)

{
  "success": false,
  "message": "Error al procesar la compra."
}

Overview

Endpoints

Sales API Endpoints — Checkout and Order History

GET /api/sales

Example request — as admin

Example request — as client

Responses

POST /api/sales

Request body

Example request

Responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/sales

​Example request — as admin

​Example request — as client

​Responses

​POST /api/sales

​Request body

​Example request

​Responses

Build docs developers (and LLMs) love

GET /api/sales

Example request — as admin

Example request — as client

Responses

POST /api/sales

Request body

Example request

Responses