Sales List, Search, and XLSX Export Endpoints — API

This page covers the four endpoints used to retrieve and export sales data. A buyer can list their own orders, admins can view and filter all sales across the platform, a dedicated search endpoint supports lookup by status name or customer identification, and an export endpoint generates a downloadable .xlsx report using the same filters as the admin list.

1. List Own Sales

Returns a paginated list of sales belonging to the currently authenticated user.

Endpoint

POST /api/sale/list-sale/:pag?/:perpage?

Authentication

Requires a valid user Token.

Path Parameters

pag

number

Page number to retrieve (optional, defaults to 1).

perpage

number

Number of results per page (optional, uses server default if omitted).

Response — 200

{
  "msj": "Cargando todas las ventas...",
  "status": true,
  "data": [ ],
  "pagination": {
    "pag": "1",
    "perpage": 10,
    "pags": 3
  }
}

Example Request

curl -X POST https://your-api.com/api/sale/list-sale/1/10 \
  -H "Authorization: Bearer <your_token>"

2. List All Sales (Admin)

Returns a paginated list of all sales across all users. Supports optional text search and month-based date filtering.

Endpoint

POST /api/sale/all-list/:pag?/:perpage?

Authentication

Requires a valid user Token.

Path Parameters

pag

number

Page number to retrieve (optional).

perpage

number

Number of results per page (optional).

Request Body (Optional Filters)

general

string

Free-text search string. Performs a case-insensitive regex match across the following fields: name_client, lastName_client, typeIdentification, identification, phone_number, address, email, codeseller, zipCode, city, products.title, deliveryStatus.description, and status.name.

date

string

Month filter in "YYYY/MM" format (e.g., "2024/05"). Returns all sales whose createdAt timestamp falls within that calendar month.

Response — 200

{
  "msj": "Cargando ventas relacionadas...",
  "status": true,
  "data": [ ],
  "pagination": {
    "pag": "1",
    "perpage": 10,
    "pags": 12
  }
}

Example Request

curl -X POST https://your-api.com/api/sale/all-list/1/10 \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "general": "Bogotá",
    "date": "2024/05"
  }'

3. Search Sales

Searches all sales by payment status name or customer identification number.

Endpoint

POST /api/sale/get-search/:query/:pag?/:perpage?

Authentication

Requires a valid user Token and an admin TokenAdmin role.

Path Parameters

query

string

required

The search string. Matched case-insensitively against status.name and identification fields.

pag

number

Page number to retrieve (optional).

perpage

number

Number of results per page (optional).

Response — 200

{
  "msj": "Cargando venta",
  "status": true,
  "data": [ ],
  "pagination": {
    "pag": "1",
    "perpage": 10,
    "pags": 2
  }
}

Example Request

curl -X POST https://your-api.com/api/sale/get-search/Pendiente/1/10 \
  -H "Authorization: Bearer <your_token>" \
  -H "TokenAdmin: <your_admin_token>"

4. Export Sales to XLSX

Applies the same filters as the List All Sales endpoint and returns a downloadable Excel (.xlsx) file containing the full matching sales dataset.

Endpoint

POST /api/sale/export-list-sale-xlsx

Authentication

Requires a valid user Token.

Request Body (Optional Filters)

general

string

Free-text search string (see List All Sales for matched fields).

date

string

Month filter in "YYYY/MM" format.

Response

Returns a binary file with content type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. The exported workbook contains a sheet named Sales Report with the following columns:

Column Header	Source Field
Estado	`status.name`
Total	`total`
Domicilio	`address`
Ciudad	`city`
Codigo postal	`zipCode`
Fecha	`createdAt`
Correo	`email`
Tipo de identificacion	`typeIdentification`
Identification	`identification`
Nombre	`name_client`
Apellido	`lastName_client`
Telefono	`phone_number`

The .xlsx file is written to a temporary path (private/temp/{userId}/Sales_report.xlsx) on the server and is automatically deleted 60 seconds after it is sent. Download the file promptly after receiving the response.

Example Request

curl -X POST https://your-api.com/api/sale/export-list-sale-xlsx \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024/05"
  }' \
  --output Sales_report.xlsx

Sale Response Object

The data array returned by the listing endpoints contains Sale documents. The full structure is described below.

data

array

Array of sale objects.

Show Sale object fields

_id

string

MongoDB ObjectId of the sale document.

userId

string

ID of the user who placed the order.

codeseller

string

Seller or referral code associated with the sale, if any.

total

number

Computed order total (unitPrice × cantBuy).

cantBuy

number

Quantity of items purchased.

codeSale

string

Unique sale code generated at order creation.

status

object

Current payment/fulfilment status.

Show status fields

name

string

Human-readable label (e.g., "Pendiente", "Pagado").

value

string

Numeric string key ("1" – "5").

name_client

string

Customer first name.

lastName_client

string

Customer last name.

typeIdentification

string

Type of government-issued ID provided by the customer.

identification

string

Customer’s ID number.

phone_number

string

Customer’s phone number.

address

string

Delivery street address.

string

Customer’s email address.

zipCode

string

Delivery postal code.

city

string

Delivery city.

imgPay

array

Array of stored image filenames for payment proof uploads.

dateproof

string

Date the payment proof was uploaded, formatted as YYYY-M-D.

colorsSize

array

Selected color variant(s). Each entry has { label: string, value: string }.

sizes

array

Selected size variant(s). Each entry has { label: string, value: string }.

typeShirt

string

Shirt cut/style selected at order creation.

products

array

Line items included in the order.

Show product entry fields

string

Product ObjectId.

title

string

Product title at time of purchase.

price

number

Unit price at time of purchase.

subtotal

number

Line-item subtotal (price × cantBuy).

productImg

array

Product image URLs captured at order creation.

deliveryStatus

array

Chronological log of delivery tracking events.

Show deliveryStatus entry fields

description

string

Summary of the delivery event.

detail

string

Optional supplementary note.

date

string

Event date formatted as YYYY-M-D.

timeHour

string

Event time formatted as HH:MM AM/PM.

createdAt

string

ISO 8601 timestamp of when the order was created.

updatedAt

string

ISO 8601 timestamp of the last document update.

pagination

object

Pagination metadata.

Show pagination fields

pag

string

Current page number (as provided in the path parameter).

perpage

number

Number of results per page used for this query.

pags

number

Total number of pages available given the current filter and perpage value.

Users

Products

Sales

Notifications

Sales List, Search, and XLSX Export Endpoints — API

1. List Own Sales

Endpoint

Authentication

Path Parameters

Response — 200

Example Request

2. List All Sales (Admin)

Endpoint

Authentication

Path Parameters

Request Body (Optional Filters)

Response — 200

Example Request

3. Search Sales

Endpoint

Authentication

Path Parameters

Response — 200

Example Request

4. Export Sales to XLSX

Endpoint

Authentication

Request Body (Optional Filters)

Response

Example Request

Sale Response Object

Build docs developers (and LLMs) love

Users

Products

Sales

Notifications

Documentation Index

​1. List Own Sales

​Endpoint

​Authentication

​Path Parameters

​Response — 200

​Example Request

​2. List All Sales (Admin)

​Endpoint

​Authentication

​Path Parameters

​Request Body (Optional Filters)

​Response — 200

​Example Request

​3. Search Sales

​Endpoint

​Authentication

​Path Parameters

​Response — 200

​Example Request

​4. Export Sales to XLSX

​Endpoint

​Authentication

​Request Body (Optional Filters)

​Response

​Example Request

​Sale Response Object

Build docs developers (and LLMs) love

1. List Own Sales

Endpoint

Authentication

Path Parameters

Response — 200

Example Request

2. List All Sales (Admin)

Endpoint

Authentication

Path Parameters

Request Body (Optional Filters)

Response — 200

Example Request

3. Search Sales

Endpoint

Authentication

Path Parameters

Response — 200

Example Request

4. Export Sales to XLSX

Endpoint

Authentication

Request Body (Optional Filters)

Response

Example Request

Sale Response Object