Ir al contenido
docs

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

CampoTipoRequeridoDescripción
errorobjectSí—
error.codestringSíCódigo estable para ramificar tu integración. Obsoletos (se conservan en el catálogo hasta una nueva versión de la API): VARIANT_STOCK_UNSUPPORTED — obsoleto, ya no se emite: las variantes mueven su propio stock. Valores: 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, INSUFFICIENT_STOCK, STOCK_MODE_LEGACY, RATE_LIMITED, INTERNAL_ERROR.
error.messagestringSíExplicación en español, con el siguiente paso.
error.paramstringNoCampo que causó el error, si aplica.
error.request_idstringSí—

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

CampoTipoRequeridoDescripción
object"account"Sí—
idstring (uuid)SíId de la cuenta (tenant).
businessobject | nullSí—
business.namestringNo—
business.currencystringNo—
planstringSíValores: free, plus, plus_nofe, pro, pro_nofe.
api_keyobject | nullSí—
api_key.idstring (uuid)No—
api_key.namestringNo—
api_key.environmentstringNoValores: live, test.
api_key.scopesarreglo de ScopeNo—
api_key.expires_atstring (date-time) | nullNo—
data_freshnessobjectSíLa API lee lo que las cajas ya subieron. last_sync_at es el último cambio que cada caja subió de verdad (null si nunca subió nada): si una caja lleva horas sin subir, sus ventas recientes todavía no aparecen.
data_freshness.last_device_sync_atstring (date-time) | nullNo—
data_freshness.devicesarreglo de objectNo—
data_freshness.devices[].namestring | nullNo—
data_freshness.devices[].kindstringNoValores: primary, satellite, kitchen.
data_freshness.devices[].platformstring | nullNo—
data_freshness.devices[].last_sync_atstring (date-time) | nullNo—

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.

CampoTipoRequeridoDescripción
object"product_variant"Sí—
idstring (uuid)Sí—
product_idstring (uuid)Sí—
labelstringSíNombre de la variante ("Talla M / Rojo").
skustring | nullSí—
base_priceintegerSíPrecio de lista, antes del descuento propio del producto.
final_priceintegerSíPrecio al que el POS vende esta variante. Si es 0 en la variante, el POS usa el del producto.
percent_discountnumberSíDescuento del producto sobre base_price, en porcentaje (0-100, puede tener decimales).
imagesarreglo de string (uri)Sí—
is_defaultbooleanSí—
activebooleanSí—
stocknumber | nullSíStock oficial de la variante (suma de sus bodegas). null mientras la cuenta no lleve el stock en la nube.
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

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.

CampoTipoRequeridoDescripción
object"product"Sí—
idstring (uuid)Sí—
namestringSí—
descriptionstringSí—
description_shortstringSí—
skustring | nullSíSKU del producto (null si no tiene).
category_idstring (uuid) | nullSí—
kindstringSícomposite = se arma desde una receta y no descuenta su propio stock. Valores: simple, composite.
sellablebooleanSífalse = insumo que no se vende por sí solo.
activebooleanSí—
tax_classstringSíClase fiscal del ítem. standard hereda del perfil fiscal del negocio. Valores: standard, reduced_5, excluded, exempt, service_19, event_package, bag, passthrough.
base_priceintegerSíPrecio de lista, antes del descuento propio del producto.
final_priceintegerSíPrecio al que el POS vende. Si el producto no tiene descuento es igual a base_price.
percent_discountnumberSíDescuento del producto sobre base_price, en porcentaje (0-100, puede tener decimales).
base_unitstringSíUnidad base (und, g, kg, lb, oz, ml, l, doc). Stock y costo se expresan en ella.
sold_by_weightbooleanSíSe vende por peso: la cantidad de la línea es un peso en base_unit.
stocknumber | nullSíStock oficial en base_unit (suma de todas sus bodegas y variantes; puede tener decimales en productos por peso y ser negativo si una venta ganó la carrera). Es null mientras la cuenta no lleve el stock en la nube (sus cajas aún en una versión anterior), en productos sin control de stock y en los que se arman con receta. Por bodega: GET /inventory/levels. Para moverlo: POST /inventory/movements o POST /inventory/counts.
unit_costnumberSíCosto promedio ponderado por unidad base (informativo).
image_urlstring (uri) | nullSí—
imagesarreglo de string (uri)Sí—
has_variantsbooleanSí—
variantsarreglo de ProductVariantSíVariantes vigentes (no eliminadas).
deleted_atstring (date-time) | nullSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

Category

Categoría del catálogo.

CampoTipoRequeridoDescripción
object"category"Sí—
idstring (uuid)Sí—
namestringSí—
descriptionstring | nullSí—
image_urlstring (uri) | nullSí—
sort_orderintegerSí—
deleted_atstring (date-time) | nullSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

Customer

Cliente del negocio.

CampoTipoRequeridoDescripción
object"customer"Sí—
idstring (uuid)Sí—
namestringSí—
last_namestring | nullSí—
emailstring | nullSí—
phonestring | nullSí—
person_typestringSíperson (persona natural) o company (persona jurídica).
document_typestringSíTipo de identificación: CC, TI, NIT, CE, PASAPORTE.
document_numberstring | nullSí—
contact_channelstring | nullSíCómo llegó el cliente: none, store, whatsapp, instagram, website, referral.
deleted_atstring (date-time) | nullSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

Warehouse

Bodega del negocio.

CampoTipoRequeridoDescripción
object"warehouse"Sí—
idstring (uuid)Sí—
namestringSí—
addressstring | nullSí—
citystring | nullSí—
is_defaultbooleanSí—
activebooleanSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

StockMovement

Movimiento del libro de inventario (solo se agregan, nunca se editan).

CampoTipoRequeridoDescripción
object"stock_movement"Sí—
idstring (uuid)Sí—
product_idstring (uuid)Sí—
variant_idstring (uuid) | nullSí—
warehouse_idstring (uuid) | nullSínull si el movimiento llegó antes que su bodega.
typestringSíTipo de movimiento tal como lo registró la caja.
quantitynumberSíCantidad en la unidad base del producto (puede ser fraccionaria).
reasonstring | nullSí—
referencestring | nullSíReferencia libre del movimiento.
unit_costnumber | nullSíCosto por unidad base al momento del movimiento.
reason_codestring | nullNoMotivo catalogado de un ajuste: shrinkage, damage, expired, theft, internal_use, supplier_return, found, correction, other o transfer_shortage. null si el movimiento no es un ajuste con motivo.
origin_typestring | nullSísale, purchase, purchase_return (goods given back to a supplier), adjustment, recipe_explosion, reversal (a voided purchase or the restock of an annulled sale), transfer (goods moving between two warehouses of the same business: an out at the origin when it is dispatched, an in at the destination when it is received or at the origin when it is returned; it never changes the cost).
sale_idstring (uuid) | nullSíLa venta que causó el movimiento, si aplica.
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

StockLevel

Stock oficial de un producto (o variante) en una bodega.

CampoTipoRequeridoDescripción
object"stock_level"Sí—
idstring (uuid)Sí—
warehouse_idstring (uuid)Sí—
product_idstring (uuid)Sí—
variant_idstring (uuid) | nullSí—
quantitynumberSíStock oficial en la unidad base: el último conteo más los movimientos posteriores. Puede ser negativo (una venta ganó la carrera): el negocio debe contar.
availablenumberSíLo que la API puede comprometer: quantity menos el margen de la API (nunca menor que 0).
baseline_quantitynumber | nullSíCantidad del último conteo (null si nunca se ha contado).
baseline_atstring (date-time) | nullSíCuándo se hizo el último conteo.
baseline_estimatedbooleanSítrue si el último conteo es una estimación de la migración y conviene contar.
baseline_sourcestring | nullSícount, count_sheet, initial, upgrade, migration o api.
negative_alert_openbooleanSíHay una alerta de stock negativo abierta en este nivel.
updated_atstring (date-time)Sí—

StockCount

Conteo físico de inventario.

CampoTipoRequeridoDescripción
object"stock_count"Sí—
idstring (uuid)Sí—
warehouse_idstring (uuid)Sí—
product_idstring (uuid)Sí—
variant_idstring (uuid) | nullSí—
counted_quantitynumberSíLo que había físicamente.
counted_atstring (date-time)SíCuándo se contó.
sourcestringSícount, count_sheet, initial, upgrade, migration o api.
statusstringSíapplied: es la base del stock oficial desde su counted_at. historical: se guardó solo como historial (ya había un conteo más reciente). pending: la cuenta todavía no lleva el stock en la nube (una caja lo registró antes del cambio); se tendrá en cuenta cuando la cuenta pase al stock en la nube. Valores: applied, historical, pending.
estimatedbooleanSí—
expected_quantitynumber | nullSíLo que el sistema creía en el instante del conteo.
differencenumber | nullSícounted_quantity − expected_quantity.
notestring | nullSí—
created_atstring (date-time)Sí—

LineTax

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

CampoTipoRequeridoDescripción
codestringSíCódigo DIAN del tributo: 01 IVA, 03 ICA, 04 INC, 22 INC bolsas.
namestring | nullSí—
ratenumber | nullSíTarifa en PORCENTAJE entero (19 = 19 %), tal como se cobró. null en impuestos por unidad.
per_unitinteger | nullSíValor fijo por unidad (bolsas). null en impuestos por porcentaje.
baseintegerSíPesos colombianos (COP), entero sin decimales.
amountintegerSíPesos colombianos (COP), entero sin decimales.

TaxBreakdownEntry

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

CampoTipoRequeridoDescripción
codestringSí—
ratenumber | nullSíPorcentaje entero.
per_unitinteger | nullSí—
baseintegerSíPesos colombianos (COP), entero sin decimales.
amountintegerSíPesos colombianos (COP), entero sin decimales.

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

CampoTipoRequeridoDescripción
idstring (uuid)Sí—
document_typeDocumentTypeSí—
statusstringSí—
cufestring | nullSíCUFE (factura) o CUDE (documento POS).
prefixstring | nullSí—
numberintegerSí—

SaleItem

Línea de una venta.

CampoTipoRequeridoDescripción
object"sale_item"Sí—
idstring (uuid)Sí—
product_idstring (uuid) | nullSínull en líneas libres o si el producto ya no existe.
variant_idstring (uuid) | nullSí—
item_kindstringSíproduct o una línea libre.
descriptionstring | nullSí—
quantitynumberSíPuede ser fraccionaria (ventas por peso).
unit_priceintegerSíPrecio unitario con los impuestos porcentuales incluidos.
subtotalintegerSíTotal de la línea con impuestos incluidos.
unit_costnumber | nullSíCosto unitario congelado al vender.
tax_classstringSí—
taxesarreglo de LineTax | nullSínull en líneas antiguas sin impuestos congelados.

Sale

Venta. Ingreso neto = total - tax - tip_amount.

CampoTipoRequeridoDescripción
object"sale"Sí—
idstring (uuid)Sí—
statusstringSíEstado tal como lo registró el POS (completed, cancelled, open, pending…).
document_kindstringSíDocumento que pidió el POS al cobrar. Valores: pos, invoice.
payment_methodstringSíMedio de pago tal como lo registró el POS (CASH, CARD, NEQUI…).
customer_idstring (uuid) | nullSí—
cash_session_idstring (uuid) | nullSí—
subtotalintegerSíSuma de las líneas, impuestos incluidos.
discountintegerSíPesos colombianos (COP), entero sin decimales.
discount_percentnumberSí—
taxintegerSíParte del total que es impuesto.
tip_amountintegerSíPropina. Nunca es base gravable.
totalintegerSísubtotal - discount + tip_amount.
tax_breakdownarreglo de TaxBreakdownEntry | nullSí—
notesstring | nullSí—
table_labelstring | nullSí—
itemsarreglo de SaleItemSí—
invoicesarreglo de InvoiceSummarySí—
occurred_atstring (date-time)Sí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.
created_atstring (date-time)SíCuando la venta llegó al servidor (una caja sin conexión la sube después).
updated_atstring (date-time)Sí—

Invoice

Documento de una venta (electrónico ante la DIAN o interno). El PDF/XML no se publican por la API en v1.

CampoTipoRequeridoDescripción
object"invoice"Sí—
idstring (uuid)Sí—
sale_idstring (uuid) | nullSí—
document_typeDocumentTypeSí—
type_document_idinteger | nullSíCódigo del tipo de documento DIAN (1, 15, 26).
statusstringSípending, issued, rejected, emission_failed, annulled.
dian_statusstring | nullSí—
dian_messagestring | nullSíMensaje de la DIAN; solo cuando el documento fue emitido o rechazado.
document_reasonstring | nullSíPor qué se eligió este tipo de documento.
prefixstring | nullSí—
numberintegerSí—
cufestring | nullSíCUFE (factura) o CUDE (documento POS).
subtotalintegerSíPesos colombianos (COP), entero sin decimales.
taxintegerSíPesos colombianos (COP), entero sin decimales.
totalintegerSíPesos colombianos (COP), entero sin decimales.
issued_atstring (date-time)Sí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

QuoteItem

Línea de una cotización.

CampoTipoRequeridoDescripción
object"quote_item"Sí—
idstring (uuid)Sí—
product_idstring (uuid) | nullSí—
variant_idstring (uuid) | nullSí—
item_kindstringSí—
descriptionstring | nullSí—
quantitynumberSí—
unit_priceintegerSíCon impuestos porcentuales incluidos.
subtotalintegerSíPesos colombianos (COP), entero sin decimales.
tax_classstringSí—
taxesarreglo de LineTax | nullSí—
notestring | nullSí—

Quote

Cotización.

CampoTipoRequeridoDescripción
object"quote"Sí—
idstring (uuid)Sí—
numberstring | nullSíCOT-XXXX; solo existe cuando la cotización se envió.
statusstringSídraft, sent, accepted, rejected, expired, converted. El vencimiento lo aplica la app al leer: compara con expires_at.
customer_idstring (uuid) | nullSí—
converted_sale_idstring (uuid) | nullSí—
subtotalintegerSíPesos colombianos (COP), entero sin decimales.
discountintegerSíPesos colombianos (COP), entero sin decimales.
taxintegerSíPesos colombianos (COP), entero sin decimales.
totalintegerSíPesos colombianos (COP), entero sin decimales.
tax_breakdownarreglo de TaxBreakdownEntry | nullSí—
notesstring | nullSí—
payment_linkstring | nullSí—
expires_atstring (date-time) | nullSí—
sent_atstring (date-time) | nullSí—
itemsarreglo de QuoteItemSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

CashMovement

Entrada o salida manual de efectivo del cajón.

CampoTipoRequeridoDescripción
object"cash_movement"Sí—
idstring (uuid)Sí—
typestringSíValores: in, out.
amountintegerSíPesos colombianos (COP), entero sin decimales.
reasonstring | nullSí—
created_atstring (date-time)Sí—

CashSession

Turno de caja con sus movimientos de efectivo.

CampoTipoRequeridoDescripción
object"cash_session"Sí—
idstring (uuid)Sí—
statusstringSíopen, closed, suspended.
terminal_namestringSíNombre de la caja ("Caja 01").
opening_cashintegerSíPesos colombianos (COP), entero sin decimales.
expected_cashinteger | nullSíLo que la app calculó que debía haber al cerrar.
closing_cashinteger | nullSíLo que se contó al cerrar.
opened_atstring (date-time)Sí—
closed_atstring (date-time) | nullSí—
movementsarreglo de CashMovementSí—
created_atstring (date-time)Sí—
updated_atstring (date-time)Sí—

DailySalesDay

Totales de un día (hora de Bogotá).

CampoTipoRequeridoDescripción
datestring (date)Sí—
sales_countintegerSíNúmero de ventas completadas.
subtotalintegerSíPesos colombianos (COP), entero sin decimales.
discountintegerSíPesos colombianos (COP), entero sin decimales.
taxintegerSíPesos colombianos (COP), entero sin decimales.
tip_amountintegerSíPesos colombianos (COP), entero sin decimales.
totalintegerSíPesos colombianos (COP), entero sin decimales.

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.

CampoTipoRequeridoDescripción
object"daily_sales_report"Sí—
timezone"America/Bogota"Sí—
currency"COP"Sí—
fromstring (date)Sí—
tostring (date)Sí—
daysarreglo de DailySalesDaySíUn elemento por día del rango, incluidos los días sin ventas (en cero).
totalsobjectSí—
totals.sales_countintegerSíNúmero de ventas completadas.
totals.subtotalintegerSíPesos colombianos (COP), entero sin decimales.
totals.discountintegerSíPesos colombianos (COP), entero sin decimales.
totals.taxintegerSíPesos colombianos (COP), entero sin decimales.
totals.tip_amountintegerSíPesos colombianos (COP), entero sin decimales.
totals.totalintegerSíPesos colombianos (COP), entero sin decimales.

Event

Evento del registro de webhooks. Sirve para reconciliar entregas perdidas.

CampoTipoRequeridoDescripción
object"event"Sí—
idstring (uuid)Sí—
typestringSíTipo de evento, por ejemplo sale.completed.
created_atstring (date-time)Sí—
dataobjectSí—
data.objectobjectSíEl objeto (venta, producto…) tal como era cuando ocurrió el evento.

CategoryCreate

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
namestringSíMáximo 120 caracteres.
descriptionstringNoMáximo 1000 caracteres.
sort_orderintegerNoMínimo: 0. Máximo: 100000.

CategoryUpdate

Envía al menos 1 campo.

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
namestringNoMáximo 120 caracteres.
descriptionstringNoMáximo 1000 caracteres.
sort_orderintegerNoMínimo: 0. Máximo: 100000.

ProductCreate

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
namestringSíMáximo 200 caracteres.
descriptionstringNoMáximo 5000 caracteres.
description_shortstringNoMáximo 300 caracteres.
skustringNoMáximo 60 caracteres.
category_idstring (uuid) | nullNo—
base_priceintegerSíPrecio base en pesos. Mínimo: 0. Máximo: 10000000000.
final_priceintegerNoPrecio al que vende la caja. Si no se envía, es igual a base_price. Mínimo: 0. Máximo: 10000000000.
percent_discountnumberNoMínimo: 0. Máximo: 100.
tax_classstringNoClase fiscal del ítem. standard hereda del perfil fiscal del negocio. Valores: standard, reduced_5, excluded, exempt, service_19, event_package, bag, passthrough. Por defecto: standard.
activebooleanNoPor defecto: true.
sellablebooleanNofalse = insumo que no se vende solo. Por defecto: true.
base_unitstringNoValores: und, g, kg, lb, oz, ml, l, doc. Por defecto: und.
sold_by_weightbooleanNoRequiere base_unit g, kg o lb. Por defecto: false.
initial_stockintegerNoCrea además un movimiento de entrada con este stock. Mínimo: 1. Máximo: 1000000000.
warehouse_idstring (uuid)NoBodega del stock inicial. Por defecto, la bodega predeterminada.

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.

CampoTipoRequeridoDescripción
namestringNoMáximo 200 caracteres.
descriptionstringNoMáximo 5000 caracteres.
description_shortstringNoMáximo 300 caracteres.
skustringNoMáximo 60 caracteres.
category_idstring (uuid) | nullNo—
base_priceintegerNoSi cambias base_price sin enviar final_price, final_price toma el mismo valor. Mínimo: 0. Máximo: 10000000000.
final_priceintegerNoPrecio al que vende la caja. Mínimo: 0. Máximo: 10000000000.
percent_discountnumberNoMínimo: 0. Máximo: 100.
tax_classstringNoValores: standard, reduced_5, excluded, exempt, service_19, event_package, bag, passthrough.
activebooleanNo—
sellablebooleanNo—

VariantUpdate

Envía al menos 1 campo.

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
labelstringNoMáximo 120 caracteres.
skustringNoÚnico por cuenta. Máximo 60 caracteres.
base_priceintegerNoSi cambias base_price sin enviar final_price, final_price toma el mismo valor. Mínimo: 0. Máximo: 10000000000.
final_priceintegerNoPrecio al que vende la caja. Mínimo: 0. Máximo: 10000000000.
percent_discountnumberNoMínimo: 0. Máximo: 100.
activebooleanNo—

CustomerCreate

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
namestringSíMáximo 120 caracteres.
last_namestringNoMáximo 120 caracteres.
phonestringNoMáximo 30 caracteres.
emailstring (email) | nullNoMáximo 200 caracteres.
person_typestringNoValores: person, company. Por defecto: person.
document_typestringNoValores: CC, TI, NIT, CE, PASAPORTE. Por defecto: CC.
document_numberstringNoMáximo 30 caracteres.
contact_channelstringNoValores: none, store, whatsapp, instagram, website, referral. Por defecto: none.

CustomerUpdate

Envía al menos 1 campo.

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
namestringNoMáximo 120 caracteres.
last_namestringNoMáximo 120 caracteres.
phonestringNoMáximo 30 caracteres.
emailstring (email) | nullNoMáximo 200 caracteres.
person_typestringNoValores: person, company. Por defecto: person.
document_typestringNoValores: CC, TI, NIT, CE, PASAPORTE. Por defecto: CC.
document_numberstringNoMáximo 30 caracteres.
contact_channelstringNoValores: none, store, whatsapp, instagram, website, referral. Por defecto: none.

StockMovementCreate

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
product_idstring (uuid)Sí—
variant_idstring (uuid)NoObligatorio si el producto tiene variantes: el movimiento es de esa variante.
warehouse_idstring (uuid)NoPor defecto, la bodega predeterminada (o la única bodega activa).
typestringSíin suma, out resta. Valores: in, out.
quantitynumberSíEn la unidad base del producto. Entero, salvo en productos que se venden por peso (sold_by_weight), que aceptan decimales (0.375 kg). Máximo: 1000000000. Mayor que 0.
reasonstringNoMotivo visible en el historial. Por defecto "Movimiento vía API". Máximo 200 caracteres.
referencestringNoTu referencia (orden de compra, pedido…). Máximo 100 caracteres.
unit_costnumberNoSolo en entradas (type: in): lo que costó cada unidad base. Alimenta el costo promedio ponderado de la cuenta. Si no lo conoces, no lo envíes (nunca 0). Una salida sale siempre al costo promedio. Máximo: 1000000000. Mayor que 0.

StockCountCreate

Un campo que no esté en la lista se rechaza con VALIDATION_ERROR.

CampoTipoRequeridoDescripción
product_idstring (uuid)Sí—
variant_idstring (uuid)NoObligatorio si el producto tiene variantes.
warehouse_idstring (uuid)NoPor defecto, la bodega predeterminada (o la única bodega activa).
counted_quantitynumberSíLo que hay físicamente, en la unidad base del producto. Entero, salvo en productos que se venden por peso (sold_by_weight), que aceptan decimales. Mínimo: 0. Máximo: 1000000000.
counted_atstring (date-time)NoCUÁNDO se contó (no cuándo se envía), ISO 8601 con zona. Nunca en el futuro. Por defecto, ahora. Las ventas ocurridas después se suman encima.
notestringNoNota visible en el historial del conteo. Máximo 500 caracteres.

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.

CampoTipoRequeridoDescripción
object"kardex"No—
productobjectNo—
product.idstring (uuid)No—
product.local_idstringNo—
product.namestringNo—
rowsarreglo de objectNo—
metaobjectNo—
meta.pageintegerNo—
meta.page_sizeintegerNo—
meta.totalintegerNo—
meta.total_pagesintegerNo—
levelsarreglo de objectNo—
levels[].warehouse_idstring (uuid)No—
levels[].variant_idstring (uuid) | nullNo—
levels[].quantitynumberNo—
total_qtynumberNoExistencia total del producto al final de lo consultado.
avg_costnumber | nullNoCosto promedio ponderado al final; null si se desconoce o no tienes inventory:costs.
warehousesarreglo de objectNo—
warehouses[].idstring (uuid)No—
warehouses[].namestringNo—
costs_hiddenbooleanNotrue si tu llave no tiene inventory:costs.

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.

CampoTipoRequeridoDescripción
object"inventory_valuation"No—
atstring (date-time)No—
computed_atstring (date-time)No—
total_valueintegerNoPesos enteros.
by_warehousearreglo de objectNo—
by_warehouse[].warehouse_idstring (uuid)No—
by_warehouse[].namestringNo—
by_warehouse[].valueintegerNo—
linesarreglo de objectNo—
lines[].product_idstring (uuid)No—
lines[].product_namestringNo—
lines[].warehouse_idstring (uuid)No—
lines[].warehouse_namestringNo—
lines[].variant_idstring (uuid) | nullNo—
lines[].quantitynumberNo—
lines[].avg_costnumber | nullNo—
lines[].valueinteger | nullNo—
metaobjectNo—
meta.pageintegerNo—
meta.page_sizeintegerNo—
meta.totalintegerNo—
meta.total_pagesintegerNo—
negativesarreglo de objectNo—
missing_costarreglo de objectNo—
in_transit_valueintegerNo—
costs_hiddenbooleanNo—