Listar ventas

GET

/sales

curl --request GET \
  --url 'https://api.posdata.so/public/v1/sales?limit=25&document_kind=pos' \
  --header 'Authorization: Bearer <token>'

• Producción (keys pdk_live_)
• Pruebas (keys pdk_test_, datos de prueba, puede reiniciarse)

Permiso requerido: sales:read.

Autorización

• bearerAuth

Parámetros

Parámetros de consulta

limit

integer

por defecto: 25 >= 1 <= 100

starting_after

string

El next_cursor de la página anterior, tal cual.

created_since

string formato: date-time

ISO 8601 con zona horaria. Incluye.

created_until

string formato: date-time

ISO 8601 con zona horaria. Excluye.

updated_since

string formato: date-time

ISO 8601 con zona horaria. Para sincronización incremental.

status

string

<= 40 caracteres

Estado exacto, por ejemplo completed.

customer_id

string formato: uuid

Ventas de ese cliente.

document_kind

string

Valores permitidos: pos invoice

Tipo de documento pedido.

occurred_since

string formato: date-time

Ventas registradas en la caja desde este instante (incluye). ISO 8601 con zona horaria.

occurred_until

string formato: date-time

Ventas registradas en la caja antes de este instante (excluye).

Respuestas

200

OK

Tipo de contenidoapplication/json

object

object

obligatorio

Valor permitido: list

data

obligatorio

Array<object>

Venta. Ingreso neto = total - tax - tip_amount.

object

object

obligatorio

Valor permitido: sale

id

obligatorio

string formato: uuid

status

obligatorio

Estado tal como lo registró el POS (completed, cancelled, open, pending…).

string

document_kind

obligatorio

Documento que pidió el POS al cobrar.

string

Valores permitidos: pos invoice

payment_method

obligatorio

Medio de pago tal como lo registró el POS (CASH, CARD, NEQUI…).

string

customer_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

cash_session_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

subtotal

obligatorio

Suma de las líneas, impuestos incluidos.

integer

discount

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

discount_percent

obligatorio

number

tax

obligatorio

Parte del total que es impuesto.

integer

tip_amount

obligatorio

Propina. Nunca es base gravable.

integer

total

obligatorio

Subtotal - discount + tip_amount.

integer

tax_breakdown

obligatorio

Cualquiera de:

Array<object>

Array<object>

Total de un tributo en el documento, agrupado por (código, tarifa).

object

code

obligatorio

string

rate

obligatorio

Cualquiera de:

number

number

null

null

per_unit

obligatorio

Cualquiera de:

integer

integer

null

null

base

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

amount

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

null

null

notes

obligatorio

Cualquiera de:

string

string

null

null

table_label

obligatorio

Cualquiera de:

string

string

null

null

items

obligatorio

Array<object>

Línea de una venta.

object

object

obligatorio

Valor permitido: sale_item

id

obligatorio

string formato: uuid

product_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

variant_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

item_kind

obligatorio

product o una línea libre.

string

description

obligatorio

Cualquiera de:

string

string

null

null

quantity

obligatorio

Puede ser fraccionaria (ventas por peso).

number

unit_price

obligatorio

Precio unitario con los impuestos porcentuales incluidos.

integer

subtotal

obligatorio

Total de la línea con impuestos incluidos.

integer

unit_cost

obligatorio

Cualquiera de:

number

Costo unitario congelado al vender.

number

null

null

tax_class

obligatorio

string

taxes

obligatorio

Cualquiera de:

Array<object>

Array<object>

Impuesto cobrado en una línea, congelado al momento de la venta.

object

code

obligatorio

Código DIAN del tributo: 01 IVA, 03 ICA, 04 INC, 22 INC bolsas.

string

name

obligatorio

Cualquiera de:

string

string

null

null

rate

obligatorio

Cualquiera de:

number

number

null

null

per_unit

obligatorio

Cualquiera de:

integer

integer

null

null

base

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

amount

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

null

null

invoices

obligatorio

Array<object>

Resumen de un documento de la venta. El detalle está en GET /invoices/{id}.

object

id

obligatorio

string formato: uuid

document_type

obligatorio

electronic_invoice = factura electrónica (DIAN 1, CUFE) · pos_document = documento equivalente POS electrónico (DIAN 15, CUDE) · pos_adjustment_note = nota de ajuste del documento POS (DIAN 26) · internal_invoice = factura no electrónica.

string

Valores permitidos: electronic_invoice pos_document pos_adjustment_note internal_invoice other

status

obligatorio

string

cufe

obligatorio

Cualquiera de:

string

string

null

null

prefix

obligatorio

Cualquiera de:

string

string

null

null

number

obligatorio

integer

occurred_at

obligatorio

Cuando se registró la venta en la caja (reloj de la caja). En ventas sincronizadas antes del 28-sep-2026 es la hora de llegada.

string formato: date-time

created_at

obligatorio

Cuando la venta llegó al servidor (una caja sin conexión la sube después).

string formato: date-time

updated_at

obligatorio

string formato: date-time

has_more

obligatorio

boolean

next_cursor

obligatorio

Cualquiera de:

string

string

null

null

Ejemplo

{
  "object": "list",
  "data": [
    {
      "object": "sale",
      "document_kind": "pos",
      "items": [
        {
          "object": "sale_item"
        }
      ],
      "invoices": [
        {
          "document_type": "electronic_invoice"
        }
      ]
    }
  ]
}

400

Petición inválida (VALIDATION_ERROR, INVALID_JSON, INVALID_CURSOR).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

401

Sin API key válida (UNAUTHENTICATED, INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED, API_KEY_WRONG_ENVIRONMENT, ACCOUNT_INACTIVE).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

403

Sin permiso (PLAN_REQUIRED, INSUFFICIENT_SCOPE, BROWSER_REQUESTS_NOT_ALLOWED).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

Límite de peticiones (RATE_LIMITED). Respeta Retry-After.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

500

Error interno (INTERNAL_ERROR). Reintenta y comparte el request_id si persiste.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}