Obtener una venta

Autorización

bearerAuth

Parámetros de ruta

id

obligatorio

string formato: uuid

200

OK

application/json

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
null

string formato: uuid

cash_session_id

obligatorio

Cualquiera de:

string
null

string formato: uuid

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>
null

Array<object>

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

object

code

obligatorio

string

rate

obligatorio

Cualquiera de:

number
null

number

per_unit

obligatorio

Cualquiera de:

integer
null

integer

base

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

amount

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

notes

obligatorio

Cualquiera de:

string
null

string

table_label

obligatorio

Cualquiera de:

string
null

string

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
null

string formato: uuid

variant_id

obligatorio

Cualquiera de:

string
null

string formato: uuid

item_kind

obligatorio

product o una línea libre.

string

description

obligatorio

Cualquiera de:

string
null

string

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
null

Costo unitario congelado al vender.

number

tax_class

obligatorio

string

taxes

obligatorio

Cualquiera de:

Array<object>
null

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
null

string

rate

obligatorio

Cualquiera de:

number
null

number

per_unit

obligatorio

Cualquiera de:

integer
null

integer

base

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

amount

obligatorio

Pesos colombianos (COP), entero sin decimales.

integer

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
null

string

prefix

obligatorio

Cualquiera de:

string
null

string

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

Ejemplo

{
  "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).

application/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).

application/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).

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

404

No existe en esta cuenta (NOT_FOUND).

application/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.

application/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.

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

Obtener una venta

Autorización

Parámetros

Parámetros de ruta

Respuestas

200

Ejemplo

400

Ejemplo

401

Ejemplo

403

Ejemplo

404

Ejemplo

429

Ejemplo

500

Ejemplo