The Sales endpoints let you retrieve your full transaction history from SmartPyme, including individual line items, customer details, and payment information. Use these endpoints to build reporting dashboards, sync data to external systems, or audit completed and pending transactions. All requests must include your API key in the Authorization header.
GET /sales Returns a paginated list of sales records. Apply query parameters to narrow results by date range, status, or sort order. Each record in the response includes the full sale object with its associated detalles line items.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/sales?fecha_inicio=2025-01-01&fecha_fin=2025-01-31&estado=Completada&per_page=50" \ --header "Authorization: Bearer {api_key}"
Query parameters Start date for filtering sales, in Y-m-d format (e.g. 2025-01-01). Used together with fecha_fin to define a date range.
End date for filtering sales, in Y-m-d format (e.g. 2025-01-31). Used together with fecha_inicio to define a date range.
Filter by sale status. Accepted values: Completada, Pendiente, Anulada, Cotizacion.
Page number to retrieve. Defaults to 1.
Number of records per page. Accepts values between 1 and 200. Defaults to 100.
Field to sort results by. Accepted values: fecha, total, correlativo, created_at.
Sort direction. Accepted values: asc, desc.
Response example { "success" : true , "data" : [ { "id" : 10421 , "fecha" : "2025-01-15" , "correlativo" : "FAC-002501" , "estado" : "Completada" , "forma_pago" : "Efectivo" , "monto_pago" : 200.00 , "cambio" : 20.00 , "iva_percibido" : 16.25 , "iva_retenido" : 0.00 , "renta_retenida" : 0.00 , "iva" : 16.25 , "total_costo" : 120.00 , "descuento" : 10.00 , "sub_total" : 163.75 , "no_sujeta" : 0.00 , "exenta" : 0.00 , "gravada" : 163.75 , "cuenta_a_terceros" : 0.00 , "total" : 180.00 , "propina" : 0.00 , "observaciones" : "Entrega en tienda" , "recurrente" : false , "cotizacion" : false , "saldo" : 0.00 , "nombre_cliente" : "María López" , "nombre_usuario" : "admin" , "nombre_vendedor" : "Carlos Díaz" , "nombre_sucursal" : "Sucursal Central" , "nombre_canal" : "Mostrador" , "nombre_documento" : "Factura" , "created_at" : "2025-01-15T10:35:00Z" , "updated_at" : "2025-01-15T10:35:00Z" , "detalles" : [ { "nombre_producto" : "Laptop Dell Inspiron 15" , "codigo_producto" : "LAP-DELL-015" , "marca_producto" : "Dell" , "cantidad" : 1 , "precio" : 163.75 , "costo" : 120.00 , "descuento" : 10.00 , "total_costo" : 120.00 , "total" : 163.75 , "iva" : 16.25 } ] } ], "pagination" : { "current_page" : 1 , "per_page" : 50 , "total" : 120 , "total_pages" : 3 , "has_next" : true , "has_prev" : false }, "meta" : { "empresa" : "Mi Empresa S.A." , "timestamp" : "2025-01-31T15:00:00Z" , "filters_applied" : { "fecha_inicio" : "2025-01-01" , "fecha_fin" : "2025-01-31" , "estado" : "Completada" } } }
Response fields Indicates whether the request completed successfully.
Array of sale objects matching the applied filters. Unique numeric identifier for the sale.
Date the sale was made, in Y-m-d format.
Human-readable document number assigned to the sale (e.g. FAC-002501).
Current status of the sale: Completada, Pendiente, Anulada, or Cotizacion.
Payment method used (e.g. Efectivo, Tarjeta, Transferencia).
Amount tendered by the customer.
Change returned to the customer. Applies to cash payments.
IVA collected on the transaction.
IVA withheld on the transaction, when applicable.
Income tax withheld on the transaction, when applicable.
Total tax amount applied to the sale.
Sum of costs for all products sold in this transaction.
Total discount amount applied to the sale.
Pre-tax subtotal of all line items.
Portion of the sale not subject to tax classification.
Tax-exempt portion of the sale amount.
Taxable base amount of the sale.
Amount invoiced on behalf of third parties, when applicable.
Final total charged to the customer, including taxes and after discounts.
Tip amount included in the transaction, if any.
Free-text notes or observations recorded at the time of sale.
Indicates whether this is a recurring sale.
Indicates whether this record is a quotation rather than a confirmed sale.
Outstanding balance remaining on the sale, for credit transactions.
Display name of the customer associated with the sale.
Username of the operator who created the sale record.
Name of the salesperson credited with the transaction.
Branch or location where the sale was processed.
Sales channel through which the transaction was made (e.g. Mostrador, En línea).
Document type used for the transaction (e.g. Factura, Ticket).
ISO 8601 timestamp of when the record was created.
ISO 8601 timestamp of the most recent update to the record.
Line items included in the sale. Full name of the product sold.
Internal SKU or product code.
Brand name of the product.
Quantity sold in this line item. Supports up to three decimal places for fractional units.
Unit price of the product at time of sale.
Unit cost of the product at time of sale, used for margin calculations.
Discount amount applied to this line item.
Total cost for this line item, calculated as costo × cantidad.
Line item total after applying quantity, discount, and tax.
Tax amount applied to this line item.
GET /sales/{id} Retrieves a single sale record by its numeric ID. The response returns the same full Sale object described above, including the detalles array of line items.
Path parameter The unique numeric identifier of the sale you want to retrieve.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/sales/10421" \ --header "Authorization: Bearer {api_key}"
The response wraps the Sale object under a data key with "success": true. All fields, including detalles, are identical to the structure documented in the GET /sales response above.
GET /sales/summary Returns aggregate statistics for your sales data over an optional date range. Use this endpoint to build high-level reporting widgets — total revenue, average transaction value, tax collected, and a breakdown of transaction counts and totals by status.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/sales/summary?fecha_inicio=2025-01-01&fecha_fin=2025-01-31" \ --header "Authorization: Bearer {api_key}"
Query parameters Start date for the summary period, in Y-m-d format. Omit to include all records from the beginning.
End date for the summary period, in Y-m-d format. Omit to include all records up to the current date.
Limit the summary to a specific sale status. Accepted values: Completada, Pendiente, Anulada, Cotizacion.
Response example { "success" : true , "data" : { "cantidad_ventas" : 125 , "total_ventas" : 18750.50 , "total_iva" : 1687.55 , "total_descuentos" : 250.00 , "promedio_venta" : 150.00 , "ventas_por_estado" : [ { "estado" : "Completada" , "cantidad" : 120 , "total" : 18000.00 }, { "estado" : "Anulada" , "cantidad" : 5 , "total" : 750.50 } ] }, "meta" : { "empresa" : "Mi Empresa S.A." , "timestamp" : "2025-01-31T23:59:00Z" , "filters_applied" : { "fecha_inicio" : "2025-01-01" , "fecha_fin" : "2025-01-31" } } }
Response fields Total number of sale records within the requested period.
Gross revenue across all sales in the period.
Total tax collected across all sales in the period.
Total discount amount applied across all sales in the period.
Average sale value for the period, calculated as total_ventas / cantidad_ventas.
Breakdown of sales count and total revenue grouped by status. Show ventas_por_estado fields
The sale status group (e.g. Completada, Pendiente, Anulada, Cotizacion).
Number of sales in this status group.
Combined total value of sales in this status group.
Display name of the company associated with your API key.
ISO 8601 timestamp indicating when the summary was generated.
Echo of the filters used to compute the summary, useful for confirming the request parameters.
