SmartPyme Sales API: Query, Create, and Update Sales

The Sales endpoints let you retrieve your full transaction history from SmartPyme — including individual line items, customer details, and payment information — and create or update sales from external systems such as e-commerce sites, marketplaces, or POS integrations. Use them to build reporting dashboards, sync transactions bidirectionally, audit completed and pending records, or generate quotations programmatically. 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}"

import requests

url = "https://api.smartpyme.site/api/external/v1/sales"
headers = {"Authorization": "Bearer {api_key}"}
params = {
    "fecha_inicio": "2025-01-01",
    "fecha_fin": "2025-01-31",
    "estado": "Completada",
    "per_page": 50,
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const response = await fetch(
  "https://api.smartpyme.site/api/external/v1/sales" +
    "?fecha_inicio=2025-01-01&fecha_fin=2025-01-31&estado=Completada&per_page=50",
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

Query parameters

string

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.

string

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.

string

Filter by sale status. Accepted values: Completada, Pendiente, Anulada, Cotizacion.

integer

Page number to retrieve. Defaults to 1.

integer

Number of records per page. Accepts values between 1 and 200. Defaults to 100.

string

Field to sort results by. Accepted values: fecha, total, correlativo, created_at.

string

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

boolean

Indicates whether the request completed successfully.

array

Array of sale objects matching the applied filters.

Show Sale fields

integer

Unique numeric identifier for the sale.

string

Date the sale was made, in Y-m-d format.

string

Human-readable document number assigned to the sale (e.g. FAC-002501).

string

Current status of the sale: Completada, Pendiente, Anulada, or Cotizacion.

string

Payment method used (e.g. Efectivo, Tarjeta, Transferencia).

number

Amount tendered by the customer.

number

Change returned to the customer. Applies to cash payments.

number

IVA collected on the transaction.

number

IVA withheld on the transaction, when applicable.

number

Income tax withheld on the transaction, when applicable.

number

Total tax amount applied to the sale.

number

Sum of costs for all products sold in this transaction.

number

Total discount amount applied to the sale.

number

Pre-tax subtotal of all line items.

number

Portion of the sale not subject to tax classification.

number

Tax-exempt portion of the sale amount.

number

Taxable base amount of the sale.

number

Amount invoiced on behalf of third parties, when applicable.

number

Final total charged to the customer, including taxes and after discounts.

number

Tip amount included in the transaction, if any.

string

Free-text notes or observations recorded at the time of sale.

boolean

Indicates whether this is a recurring sale.

boolean

Indicates whether this record is a quotation rather than a confirmed sale.

number

Outstanding balance remaining on the sale, for credit transactions.

string

Display name of the customer associated with the sale.

string

Username of the operator who created the sale record.

string

Name of the salesperson credited with the transaction.

string

Branch or location where the sale was processed.

string

Sales channel through which the transaction was made (e.g. Mostrador, En línea).

string

Document type used for the transaction (e.g. Factura, Ticket).

string

ISO 8601 timestamp of when the record was created.

string

ISO 8601 timestamp of the most recent update to the record.

array

Line items included in the sale.

Show Sale detail fields

string

Full name of the product sold.

string

Internal SKU or product code.

string

Brand name of the product.

number

Quantity sold in this line item. Supports up to three decimal places for fractional units.

number

Unit price of the product at time of sale.

number

Unit cost of the product at time of sale, used for margin calculations.

number

Discount amount applied to this line item.

number

Total cost for this line item, calculated as costo × cantidad.

number

Line item total after applying quantity, discount, and tax.

number

Tax amount applied to this line item.

POST /sales

Creates and processes a sale through the same invoicing logic the SmartPyme UI uses. Use this endpoint to push transactions into SmartPyme from external POS, e-commerce, or marketplace systems, or to generate quotations programmatically. The endpoint runs the full business pipeline — stock movements, tax breakdown, document correlatives, and document of sale generation — so the sale you create here is indistinguishable from one entered manually in the app.

When to use it

A confirmed sale needs to be registered immediately and marked as paid (Pagada or Completada).
A pending sale needs to be opened and finalized later from the SmartPyme UI (Pendiente).
A quotation needs to be created from an external quoting tool (Cotizacion).

Idempotency

Pass an external identifier through referencia_externa (or referencia) to make the request idempotent. If a sale with the same referencia already exists for your company, the API returns the existing record with HTTP 200 and meta.idempotent: true instead of creating a duplicate. New sales return HTTP 201. Always set this field when retrying requests or syncing from systems that may resend the same transaction.

curl --request POST \
  --url "https://api.smartpyme.site/api/external/v1/sales" \
  --header "Authorization: Bearer {api_key}" \
  --header "Content-Type: application/json" \
  --data '{
    "referencia_externa": "ORDER-9001",
    "fecha": "2025-01-15",
    "estado": "Pagada",
    "id_sucursal": 3,
    "id_bodega": 7,
    "id_documento": 12,
    "id_canal": 2,
    "id_cliente": 45,
    "forma_pago": "Efectivo",
    "monto_pago": 180.00,
    "cambio": 20.00,
    "observaciones": "Pedido web",
    "detalles": [
      {
        "id_producto": 312,
        "cantidad": 1,
        "precio": 163.75,
        "descuento": 10.00,
        "porcentaje_impuesto": 13
      }
    ]
  }'

import requests

url = "https://api.smartpyme.site/api/external/v1/sales"
headers = {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
}
payload = {
    "referencia_externa": "ORDER-9001",
    "fecha": "2025-01-15",
    "estado": "Pagada",
    "id_sucursal": 3,
    "id_bodega": 7,
    "id_documento": 12,
    "id_canal": 2,
    "id_cliente": 45,
    "forma_pago": "Efectivo",
    "monto_pago": 180.00,
    "cambio": 20.00,
    "observaciones": "Pedido web",
    "detalles": [
        {
            "id_producto": 312,
            "cantidad": 1,
            "precio": 163.75,
            "descuento": 10.00,
            "porcentaje_impuesto": 13,
        }
    ],
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.json())

const response = await fetch(
  "https://api.smartpyme.site/api/external/v1/sales",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      referencia_externa: "ORDER-9001",
      fecha: "2025-01-15",
      estado: "Pagada",
      id_sucursal: 3,
      id_bodega: 7,
      id_documento: 12,
      id_canal: 2,
      id_cliente: 45,
      forma_pago: "Efectivo",
      monto_pago: 180.0,
      cambio: 20.0,
      observaciones: "Pedido web",
      detalles: [
        {
          id_producto: 312,
          cantidad: 1,
          precio: 163.75,
          descuento: 10.0,
          porcentaje_impuesto: 13,
        },
      ],
    }),
  }
);
const data = await response.json();
console.log(data);

Body parameters

string

External identifier from your system. When provided, the endpoint becomes idempotent for this value (see Idempotency). Alias: referencia. Maximum 255 characters.

string

required

Sale date, in Y-m-d format (e.g. 2025-01-15).

string

required

Initial state of the sale. Accepted values: Pagada, Completada, Pendiente, Cotizacion. Use Pendiente for sales that will be finalized later; Pendiente requires id_cliente. Cotizacion creates a quotation rather than a confirmed sale.

integer

Branch identifier. Required if sucursal is not provided.

string

Branch name. Resolved server-side to the matching id_sucursal. Required if id_sucursal is not provided.

integer

required

Warehouse identifier that stock movements will be applied to. Must belong to your company.

integer

required

Sales document type identifier (e.g. invoice, ticket). The correlativo is taken from this document.

integer

Sales channel identifier (e.g. counter, online). Required unless estado is Cotizacion.

integer

Customer identifier. Required when estado is Pendiente. Optional for other states.

string

Payment method (e.g. Efectivo, Tarjeta, Transferencia). Defaults to Efectivo. Maximum 100 characters.

number

Amount tendered by the customer. Defaults to the sale total when estado is Pagada.

number

Change returned to the customer. Defaults to 0.

string

Expiration date for the sale or quotation, in Y-m-d format.

string

Free-text notes recorded on the sale. Maximum 1000 characters.

boolean

Marks the sale as a quotation. Automatically set to true when estado is Cotizacion.

array

required

Line items for the sale. Must contain at least 1 and at most 100 entries.

Show detalles entry

integer

Product identifier. Required if codigo_producto is not provided.

string

Product SKU or code. Required if id_producto is not provided. Resolved server-side to the matching product in your company.

number

required

Quantity sold. Must be at least 0.0001.

number

Unit price (tax-inclusive). When omitted, the product’s current sale price is used.

number

Discount amount applied to this line.

integer

Optional product presentation identifier for products sold in multiple presentations.

number

Tax percentage applied to the line. Range 0–100.

Response

On success, the response wraps the full Sale object under data — identical to the structure returned by GET /sales. The meta.idempotent flag indicates whether the record was newly created or returned from a prior request:

201 Created — a new sale was created (meta.idempotent: false).
200 OK — the request matched an existing referencia and the previously created sale is returned (meta.idempotent: true).

{
  "success": true,
  "data": {
    "id": 10422,
    "fecha": "2025-01-15",
    "correlativo": "FAC-002502",
    "estado": "Completada",
    "total": 180.00,
    "detalles": [ /* ... */ ]
  },
  "meta": {
    "empresa": "Mi Empresa S.A.",
    "timestamp": "2025-01-15T10:42:00Z",
    "idempotent": false
  }
}

Validation or business-rule failures return the standard error envelope with HTTP 422 and a details object listing the failing fields.

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

integer

required

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}"

import requests

sale_id = 10421
url = f"https://api.smartpyme.site/api/external/v1/sales/{sale_id}"
headers = {"Authorization": "Bearer {api_key}"}

response = requests.get(url, headers=headers)
print(response.json())

const saleId = 10421;
const response = await fetch(
  `https://api.smartpyme.site/api/external/v1/sales/${saleId}`,
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

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.

PUT /sales/{id}

Updates an existing sale or quotation that has not yet been finalized. Use this endpoint to adjust line items, change the customer, switch the branch or warehouse, or transition a quotation into a confirmed sale.

When to use it

Edit a Pendiente, Cotizacion, or Pre-venta record before it is finalized — for example, to add or remove items, fix the customer, or update the payment method.
Convert a quotation into a sale by sending estado: "Pagada" or "Completada" together with the final line items.

Restrictions

Only sales in state Pendiente, Cotizacion, or Pre-venta can be updated. Attempting to update a sale in any other state returns HTTP 422.
Sales that already have a fiscal document emitted cannot be updated and return HTTP 422.
Annulled sales (Anulada) cannot be updated and return HTTP 422.
The same 100-line maximum applies to the detalles array.

Path parameter

integer

required

The numeric identifier of the sale to update.

Body parameters

All body fields are optional. Send only the fields you want to change; omitted fields keep their current value. If detalles is omitted, the existing line items are preserved.

string

Sale date, in Y-m-d format.

string

New state for the sale. Accepted values: Pagada, Completada, Pendiente, Cotizacion, Pre-venta.

integer

Branch identifier.

string

Branch name. Resolved server-side to the matching id_sucursal.

integer

Warehouse identifier.

integer

Sales document type identifier.

integer

Sales channel identifier.

integer

Customer identifier. Required when transitioning the sale to Pendiente.

string

Payment method.

number

Amount tendered by the customer.

number

Change returned to the customer.

string

Expiration date, in Y-m-d format.

string

Free-text notes. Maximum 1000 characters.

boolean

Marks the sale as a quotation.

array

Replacement line items. When provided, must contain between 1 and 100 entries. Pass an existing line’s id to update it in place; omit the id to add a new line. Lines not included in the new array are removed.

Show detalles entry

integer

Existing line item identifier. Include to update the matching line; omit to create a new one.

integer

Product identifier. Required if codigo_producto is not provided.

string

Product SKU or code. Required if id_producto is not provided.

number

Quantity sold. Required when detalles is provided. Must be at least 0.0001.

number

Unit price (tax-inclusive).

number

Discount amount applied to this line.

integer

Product presentation identifier.

number

Tax percentage applied to the line. Range 0–100.

curl --request PUT \
  --url "https://api.smartpyme.site/api/external/v1/sales/10422" \
  --header "Authorization: Bearer {api_key}" \
  --header "Content-Type: application/json" \
  --data '{
    "estado": "Pagada",
    "forma_pago": "Tarjeta",
    "detalles": [
      { "id_producto": 312, "cantidad": 2, "precio": 163.75 }
    ]
  }'

import requests

sale_id = 10422
url = f"https://api.smartpyme.site/api/external/v1/sales/{sale_id}"
headers = {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
}
payload = {
    "estado": "Pagada",
    "forma_pago": "Tarjeta",
    "detalles": [
        {"id_producto": 312, "cantidad": 2, "precio": 163.75},
    ],
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

const saleId = 10422;
const response = await fetch(
  `https://api.smartpyme.site/api/external/v1/sales/${saleId}`,
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      estado: "Pagada",
      forma_pago: "Tarjeta",
      detalles: [{ id_producto: 312, cantidad: 2, precio: 163.75 }],
    }),
  }
);
const data = await response.json();
console.log(data);

On success, the endpoint returns HTTP 200 and the updated Sale object under data, using the same structure as GET /sales.

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}"

import requests

url = "https://api.smartpyme.site/api/external/v1/sales/summary"
headers = {"Authorization": "Bearer {api_key}"}
params = {
    "fecha_inicio": "2025-01-01",
    "fecha_fin": "2025-01-31",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const response = await fetch(
  "https://api.smartpyme.site/api/external/v1/sales/summary" +
    "?fecha_inicio=2025-01-01&fecha_fin=2025-01-31",
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

Query parameters

string

Start date for the summary period, in Y-m-d format. Omit to include all records from the beginning.

string

End date for the summary period, in Y-m-d format. Omit to include all records up to the current date.

string

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

integer

Total number of sale records within the requested period.

number

Gross revenue across all sales in the period.

number

Total tax collected across all sales in the period.

number

Total discount amount applied across all sales in the period.

number

Average sale value for the period, calculated as total_ventas / cantidad_ventas.

array

Breakdown of sales count and total revenue grouped by status.

Show ventas_por_estado fields

string

The sale status group (e.g. Completada, Pendiente, Anulada, Cotizacion).

integer

Number of sales in this status group.

number

Combined total value of sales in this status group.

string

Display name of the company associated with your API key.

string

ISO 8601 timestamp indicating when the summary was generated.

object

Echo of the filters used to compute the summary, useful for confirming the request parameters.

Overview

Endpoints

SmartPyme Sales API: Query, Create, and Update Sales

GET /sales

Query parameters

Response example

Response fields

POST /sales

When to use it

Idempotency

Body parameters

Response

GET /sales/{id}

Path parameter

PUT /sales/{id}

When to use it

Restrictions

Path parameter

Body parameters

GET /sales/summary

Query parameters

Response example

Response fields

​GET /sales

​Query parameters

​Response example

​Response fields

​POST /sales

​When to use it

​Idempotency

​Body parameters

​Response

​GET /sales/{id}

​Path parameter

​PUT /sales/{id}

​When to use it

​Restrictions

​Path parameter

​Body parameters

​GET /sales/summary

​Query parameters

​Response example

​Response fields

GET /sales

Query parameters

Response example

Response fields

POST /sales

When to use it

Idempotency

Body parameters

Response

GET /sales/{id}

Path parameter

PUT /sales/{id}

When to use it

Restrictions

Path parameter

Body parameters

GET /sales/summary

Query parameters

Response example

Response fields