Objetos
Todos los objetos y esquemas de la API pública de Posdata, campo por campo.
Esta página lista cada objeto del contrato de la API, generada desde el mismo archivo OpenAPI que publica el servidor. En cada endpoint de la referencia verás estos objetos en contexto.
- En los objetos que devuelve la API, Requerido: Sí significa que el campo siempre viene en la
respuesta (aunque su valor pueda ser
null). - En los objetos que envías (
…Create,…Update), Requerido: Sí significa que debes enviarlo. - Los montos son pesos colombianos (COP) enteros y las tarifas de impuesto, porcentajes enteros. Mira Cómo se sincroniza con las cajas.
36 objetos en el contrato Posdata API 1.0.0:
Error
Scope
- products:read: Leer productos, variantes y categorías
- products:write: Crear y editar productos, editar variantes, crear y editar categorías
- customers:read: Leer clientes
- customers:write: Crear y editar clientes
- inventory:read: Leer bodegas, stock por bodega y movimientos de inventario
- inventory:write: Registrar movimientos y conteos de inventario
- sales:read: Leer ventas
- invoices:read: Leer documentos electrónicos (DIAN)
- quotes:read: Leer cotizaciones
- cash:read: Leer turnos y movimientos de caja
- reports:read: Leer reportes agregados
- events:read: Leer el registro de eventos
- inventory:costs: Ver costos y valores del inventario (kardex valorizado y valor del inventario)
Valores posibles: products:read, products:write, customers:read, customers:write, inventory:read, inventory:write, sales:read, invoices:read, quotes:read, cash:read, reports:read, events:read, inventory:costs
Account
ProductVariant
Variante de un producto. Precios en pesos enteros, digitados como los digita el negocio: con impuestos incluidos cuando su perfil fiscal dice pricesIncludeTax (lo normal), antes de impuestos si no.
Product
Producto del catálogo. Precios en pesos enteros, digitados como los digita el negocio: con impuestos incluidos cuando su perfil fiscal dice pricesIncludeTax (lo normal), antes de impuestos si no.
Category
Categoría del catálogo.
Customer
Cliente del negocio.
Warehouse
Bodega del negocio.
StockMovement
Movimiento del libro de inventario (solo se agregan, nunca se editan).
StockLevel
Stock oficial de un producto (o variante) en una bodega.
StockCount
Conteo físico de inventario.
LineTax
Impuesto cobrado en una línea, congelado al momento de la venta.
TaxBreakdownEntry
Total de un tributo en el documento, agrupado por (código, tarifa).
DocumentType
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.
Valores posibles: electronic_invoice, pos_document, pos_adjustment_note, internal_invoice, other
InvoiceSummary
Resumen de un documento de la venta. El detalle está en GET /invoices/{id}.
SaleItem
Línea de una venta.
Sale
Venta. Ingreso neto = total - tax - tip_amount.
Invoice
Documento de una venta (electrónico ante la DIAN o interno). El PDF/XML no se publican por la API en v1.
QuoteItem
Línea de una cotización.
Quote
Cotización.
CashMovement
Entrada o salida manual de efectivo del cajón.
CashSession
Turno de caja con sus movimientos de efectivo.
DailySalesDay
Totales de un día (hora de Bogotá).
DailySalesReport
Ventas completadas por día calendario de Bogotá. Una venta cuenta en el día en que se registró en la caja (occurred_at); las sincronizadas antes del 28-sep-2026 cuentan en el día en que llegaron al servidor.
Event
Evento del registro de webhooks. Sirve para reconciliar entregas perdidas.
CategoryCreate
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
CategoryUpdate
Envía al menos 1 campo.
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
ProductCreate
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
ProductUpdate
El stock no se edita aquí: usa POST /inventory/movements. La unidad, la venta por peso y el tipo de producto tampoco (cambian el significado del stock existente).
Envía al menos 1 campo.
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
VariantUpdate
Envía al menos 1 campo.
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
CustomerCreate
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
CustomerUpdate
Envía al menos 1 campo.
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
StockMovementCreate
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
StockCountCreate
Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.
InventoryKardex
El kardex de un producto: cada movimiento, conteo y ajuste de costo en orden, con el saldo y (con el permiso inventory:costs) el costo promedio corrido. Sin ese permiso, unit_cost, value_delta, avg_cost y total_value vienen en null y costs_hidden es true. Un costo desconocido es null (con missing_cost: true), nunca 0.
InventoryValuation
El valor del inventario hoy o a una fecha (at): existencia × costo promedio del producto en ese instante. Los niveles negativos no suman (van en negatives: "cuéntalos") y los productos sin costo van en missing_cost sin valor — nunca valorados en 0. Siempre dice cuándo se calculó (computed_at): información tardía (una caja sin conexión) puede cambiar un corte ya consultado.