# 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](https://developers.posdata.so/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](https://developers.posdata.so/sincronizacion/#dinero-impuestos-y-cantidades). 36 objetos en el contrato Posdata API 1.0.0: ## Error | Campo | Tipo | Requerido | Descripción | | ------------------ | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error` | object | Sí | — | | `error.code` | string | Sí | 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.message` | string | Sí | Explicación en español, con el siguiente paso. | | `error.param` | string | No | Campo que causó el error, si aplica. | | `error.request_id` | string | Sí | — | ## 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 | Campo | Tipo | Requerido | Descripción | | --------------------------------------- | ------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `object` | `"account"` | Sí | — | | `id` | string (uuid) | Sí | Id de la cuenta (tenant). | | `business` | object \| null | Sí | — | | `business.name` | string | No | — | | `business.currency` | string | No | — | | `plan` | string | Sí | Valores: `free`, `plus`, `plus_nofe`, `pro`, `pro_nofe`. | | `api_key` | object \| null | Sí | — | | `api_key.id` | string (uuid) | No | — | | `api_key.name` | string | No | — | | `api_key.environment` | string | No | Valores: `live`, `test`. | | `api_key.scopes` | arreglo de [Scope](https://developers.posdata.so/referencia/objetos/#obj-scope) | No | — | | `api_key.expires_at` | string (date-time) \| null | No | — | | `data_freshness` | object | Sí | 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_at` | string (date-time) \| null | No | — | | `data_freshness.devices` | arreglo de object | No | — | | `data_freshness.devices[].name` | string \| null | No | — | | `data_freshness.devices[].kind` | string | No | Valores: `primary`, `satellite`, `kitchen`. | | `data_freshness.devices[].platform` | string \| null | No | — | | `data_freshness.devices[].last_sync_at` | string (date-time) \| null | No | — | ## 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. | Campo | Tipo | Requerido | Descripción | | ------------------ | ----------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | | `object` | `"product_variant"` | Sí | — | | `id` | string (uuid) | Sí | — | | `product_id` | string (uuid) | Sí | — | | `label` | string | Sí | Nombre de la variante ("Talla M / Rojo"). | | `sku` | string \| null | Sí | — | | `base_price` | integer | Sí | Precio de lista, antes del descuento propio del producto. | | `final_price` | integer | Sí | Precio al que el POS vende esta variante. Si es 0 en la variante, el POS usa el del producto. | | `percent_discount` | number | Sí | Descuento del producto sobre `base_price`, en porcentaje (0-100, puede tener decimales). | | `images` | arreglo de string (uri) | Sí | — | | `is_default` | boolean | Sí | — | | `active` | boolean | Sí | — | | `stock` | number \| null | Sí | Stock oficial de la variante (suma de sus bodegas). `null` mientras la cuenta no lleve el stock en la nube. | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (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. | Campo | Tipo | Requerido | Descripción | | ------------------- | ------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `object` | `"product"` | Sí | — | | `id` | string (uuid) | Sí | — | | `name` | string | Sí | — | | `description` | string | Sí | — | | `description_short` | string | Sí | — | | `sku` | string \| null | Sí | SKU del producto (null si no tiene). | | `category_id` | string (uuid) \| null | Sí | — | | `kind` | string | Sí | `composite` = se arma desde una receta y no descuenta su propio stock. Valores: `simple`, `composite`. | | `sellable` | boolean | Sí | `false` = insumo que no se vende por sí solo. | | `active` | boolean | Sí | — | | `tax_class` | string | Sí | Clase fiscal del ítem. `standard` hereda del perfil fiscal del negocio. Valores: `standard`, `reduced_5`, `excluded`, `exempt`, `service_19`, `event_package`, `bag`, `passthrough`. | | `base_price` | integer | Sí | Precio de lista, antes del descuento propio del producto. | | `final_price` | integer | Sí | Precio al que el POS vende. Si el producto no tiene descuento es igual a `base_price`. | | `percent_discount` | number | Sí | Descuento del producto sobre `base_price`, en porcentaje (0-100, puede tener decimales). | | `base_unit` | string | Sí | Unidad base (und, g, kg, lb, oz, ml, l, doc). Stock y costo se expresan en ella. | | `sold_by_weight` | boolean | Sí | Se vende por peso: la cantidad de la línea es un peso en `base_unit`. | | `stock` | number \| null | Sí | 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_cost` | number | Sí | Costo promedio ponderado por unidad base (informativo). | | `image_url` | string (uri) \| null | Sí | — | | `images` | arreglo de string (uri) | Sí | — | | `has_variants` | boolean | Sí | — | | `variants` | arreglo de [ProductVariant](https://developers.posdata.so/referencia/objetos/#obj-productvariant) | Sí | Variantes vigentes (no eliminadas). | | `deleted_at` | string (date-time) \| null | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## Category Categoría del catálogo. | Campo | Tipo | Requerido | Descripción | | ------------- | -------------------------- | --------- | ----------- | | `object` | `"category"` | Sí | — | | `id` | string (uuid) | Sí | — | | `name` | string | Sí | — | | `description` | string \| null | Sí | — | | `image_url` | string (uri) \| null | Sí | — | | `sort_order` | integer | Sí | — | | `deleted_at` | string (date-time) \| null | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## Customer Cliente del negocio. | Campo | Tipo | Requerido | Descripción | | ----------------- | -------------------------- | --------- | --------------------------------------------------------------------------- | | `object` | `"customer"` | Sí | — | | `id` | string (uuid) | Sí | — | | `name` | string | Sí | — | | `last_name` | string \| null | Sí | — | | `email` | string \| null | Sí | — | | `phone` | string \| null | Sí | — | | `person_type` | string | Sí | `person` (persona natural) o `company` (persona jurídica). | | `document_type` | string | Sí | Tipo de identificación: CC, TI, NIT, CE, PASAPORTE. | | `document_number` | string \| null | Sí | — | | `contact_channel` | string \| null | Sí | Cómo llegó el cliente: none, store, whatsapp, instagram, website, referral. | | `deleted_at` | string (date-time) \| null | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## Warehouse Bodega del negocio. | Campo | Tipo | Requerido | Descripción | | ------------ | ------------------ | --------- | ----------- | | `object` | `"warehouse"` | Sí | — | | `id` | string (uuid) | Sí | — | | `name` | string | Sí | — | | `address` | string \| null | Sí | — | | `city` | string \| null | Sí | — | | `is_default` | boolean | Sí | — | | `active` | boolean | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## StockMovement Movimiento del libro de inventario (solo se agregan, nunca se editan). | Campo | Tipo | Requerido | Descripción | | -------------- | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"stock_movement"` | Sí | — | | `id` | string (uuid) | Sí | — | | `product_id` | string (uuid) | Sí | — | | `variant_id` | string (uuid) \| null | Sí | — | | `warehouse_id` | string (uuid) \| null | Sí | null si el movimiento llegó antes que su bodega. | | `type` | string | Sí | Tipo de movimiento tal como lo registró la caja. | | `quantity` | number | Sí | Cantidad en la unidad base del producto (puede ser fraccionaria). | | `reason` | string \| null | Sí | — | | `reference` | string \| null | Sí | Referencia libre del movimiento. | | `unit_cost` | number \| null | Sí | Costo por unidad base al momento del movimiento. | | `reason_code` | string \| null | No | Motivo 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_type` | string \| null | Sí | 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_id` | string (uuid) \| null | Sí | La venta que causó el movimiento, si aplica. | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## StockLevel Stock oficial de un producto (o variante) en una bodega. | Campo | Tipo | Requerido | Descripción | | --------------------- | -------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"stock_level"` | Sí | — | | `id` | string (uuid) | Sí | — | | `warehouse_id` | string (uuid) | Sí | — | | `product_id` | string (uuid) | Sí | — | | `variant_id` | string (uuid) \| null | Sí | — | | `quantity` | number | Sí | 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. | | `available` | number | Sí | Lo que la API puede comprometer: `quantity` menos el margen de la API (nunca menor que 0). | | `baseline_quantity` | number \| null | Sí | Cantidad del último conteo (null si nunca se ha contado). | | `baseline_at` | string (date-time) \| null | Sí | Cuándo se hizo el último conteo. | | `baseline_estimated` | boolean | Sí | `true` si el último conteo es una estimación de la migración y conviene contar. | | `baseline_source` | string \| null | Sí | count, count_sheet, initial, upgrade, migration o api. | | `negative_alert_open` | boolean | Sí | Hay una alerta de stock negativo abierta en este nivel. | | `updated_at` | string (date-time) | Sí | — | ## StockCount Conteo físico de inventario. | Campo | Tipo | Requerido | Descripción | | ------------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `object` | `"stock_count"` | Sí | — | | `id` | string (uuid) | Sí | — | | `warehouse_id` | string (uuid) | Sí | — | | `product_id` | string (uuid) | Sí | — | | `variant_id` | string (uuid) \| null | Sí | — | | `counted_quantity` | number | Sí | Lo que había físicamente. | | `counted_at` | string (date-time) | Sí | Cuándo se contó. | | `source` | string | Sí | count, count_sheet, initial, upgrade, migration o api. | | `status` | string | Sí | `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`. | | `estimated` | boolean | Sí | — | | `expected_quantity` | number \| null | Sí | Lo que el sistema creía en el instante del conteo. | | `difference` | number \| null | Sí | `counted_quantity − expected_quantity`. | | `note` | string \| null | Sí | — | | `created_at` | string (date-time) | Sí | — | ## LineTax Impuesto cobrado en una línea, congelado al momento de la venta. | Campo | Tipo | Requerido | Descripción | | ---------- | --------------- | --------- | ----------------------------------------------------------------------------------------- | | `code` | string | Sí | Código DIAN del tributo: 01 IVA, 03 ICA, 04 INC, 22 INC bolsas. | | `name` | string \| null | Sí | — | | `rate` | number \| null | Sí | Tarifa en PORCENTAJE entero (19 = 19 %), tal como se cobró. null en impuestos por unidad. | | `per_unit` | integer \| null | Sí | Valor fijo por unidad (bolsas). null en impuestos por porcentaje. | | `base` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `amount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | ## TaxBreakdownEntry Total de un tributo en el documento, agrupado por (código, tarifa). | Campo | Tipo | Requerido | Descripción | | ---------- | --------------- | --------- | ---------------------------------------------- | | `code` | string | Sí | — | | `rate` | number \| null | Sí | Porcentaje entero. | | `per_unit` | integer \| null | Sí | — | | `base` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `amount` | integer | Sí | 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}. | Campo | Tipo | Requerido | Descripción | | --------------- | ---------------------------------------------------------------------------------- | --------- | -------------------------------------- | | `id` | string (uuid) | Sí | — | | `document_type` | [DocumentType](https://developers.posdata.so/referencia/objetos/#obj-documenttype) | Sí | — | | `status` | string | Sí | — | | `cufe` | string \| null | Sí | CUFE (factura) o CUDE (documento POS). | | `prefix` | string \| null | Sí | — | | `number` | integer | Sí | — | ## SaleItem Línea de una venta. | Campo | Tipo | Requerido | Descripción | | ------------- | ------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------- | | `object` | `"sale_item"` | Sí | — | | `id` | string (uuid) | Sí | — | | `product_id` | string (uuid) \| null | Sí | null en líneas libres o si el producto ya no existe. | | `variant_id` | string (uuid) \| null | Sí | — | | `item_kind` | string | Sí | `product` o una línea libre. | | `description` | string \| null | Sí | — | | `quantity` | number | Sí | Puede ser fraccionaria (ventas por peso). | | `unit_price` | integer | Sí | Precio unitario con los impuestos porcentuales incluidos. | | `subtotal` | integer | Sí | Total de la línea con impuestos incluidos. | | `unit_cost` | number \| null | Sí | Costo unitario congelado al vender. | | `tax_class` | string | Sí | — | | `taxes` | arreglo de [LineTax](https://developers.posdata.so/referencia/objetos/#obj-linetax) \| null | Sí | null en líneas antiguas sin impuestos congelados. | ## Sale Venta. Ingreso neto = total - tax - tip_amount. | Campo | Tipo | Requerido | Descripción | | ------------------ | --------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"sale"` | Sí | — | | `id` | string (uuid) | Sí | — | | `status` | string | Sí | Estado tal como lo registró el POS (completed, cancelled, open, pending…). | | `document_kind` | string | Sí | Documento que pidió el POS al cobrar. Valores: `pos`, `invoice`. | | `payment_method` | string | Sí | Medio de pago tal como lo registró el POS (CASH, CARD, NEQUI…). | | `customer_id` | string (uuid) \| null | Sí | — | | `cash_session_id` | string (uuid) \| null | Sí | — | | `subtotal` | integer | Sí | Suma de las líneas, impuestos incluidos. | | `discount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `discount_percent` | number | Sí | — | | `tax` | integer | Sí | Parte del total que es impuesto. | | `tip_amount` | integer | Sí | Propina. Nunca es base gravable. | | `total` | integer | Sí | subtotal - discount + tip_amount. | | `tax_breakdown` | arreglo de [TaxBreakdownEntry](https://developers.posdata.so/referencia/objetos/#obj-taxbreakdownentry) \| null | Sí | — | | `notes` | string \| null | Sí | — | | `table_label` | string \| null | Sí | — | | `items` | arreglo de [SaleItem](https://developers.posdata.so/referencia/objetos/#obj-saleitem) | Sí | — | | `invoices` | arreglo de [InvoiceSummary](https://developers.posdata.so/referencia/objetos/#obj-invoicesummary) | Sí | — | | `occurred_at` | string (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_at` | string (date-time) | Sí | Cuando la venta llegó al servidor (una caja sin conexión la sube después). | | `updated_at` | string (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. | Campo | Tipo | Requerido | Descripción | | ------------------ | ---------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------- | | `object` | `"invoice"` | Sí | — | | `id` | string (uuid) | Sí | — | | `sale_id` | string (uuid) \| null | Sí | — | | `document_type` | [DocumentType](https://developers.posdata.so/referencia/objetos/#obj-documenttype) | Sí | — | | `type_document_id` | integer \| null | Sí | Código del tipo de documento DIAN (1, 15, 26). | | `status` | string | Sí | pending, issued, rejected, emission_failed, annulled. | | `dian_status` | string \| null | Sí | — | | `dian_message` | string \| null | Sí | Mensaje de la DIAN; solo cuando el documento fue emitido o rechazado. | | `document_reason` | string \| null | Sí | Por qué se eligió este tipo de documento. | | `prefix` | string \| null | Sí | — | | `number` | integer | Sí | — | | `cufe` | string \| null | Sí | CUFE (factura) o CUDE (documento POS). | | `subtotal` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tax` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `total` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `issued_at` | string (date-time) | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## QuoteItem Línea de una cotización. | Campo | Tipo | Requerido | Descripción | | ------------- | ------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------- | | `object` | `"quote_item"` | Sí | — | | `id` | string (uuid) | Sí | — | | `product_id` | string (uuid) \| null | Sí | — | | `variant_id` | string (uuid) \| null | Sí | — | | `item_kind` | string | Sí | — | | `description` | string \| null | Sí | — | | `quantity` | number | Sí | — | | `unit_price` | integer | Sí | Con impuestos porcentuales incluidos. | | `subtotal` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tax_class` | string | Sí | — | | `taxes` | arreglo de [LineTax](https://developers.posdata.so/referencia/objetos/#obj-linetax) \| null | Sí | — | | `note` | string \| null | Sí | — | ## Quote Cotización. | Campo | Tipo | Requerido | Descripción | | ------------------- | --------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | | `object` | `"quote"` | Sí | — | | `id` | string (uuid) | Sí | — | | `number` | string \| null | Sí | COT-XXXX; solo existe cuando la cotización se envió. | | `status` | string | Sí | draft, sent, accepted, rejected, expired, converted. El vencimiento lo aplica la app al leer: compara con `expires_at`. | | `customer_id` | string (uuid) \| null | Sí | — | | `converted_sale_id` | string (uuid) \| null | Sí | — | | `subtotal` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `discount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tax` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `total` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tax_breakdown` | arreglo de [TaxBreakdownEntry](https://developers.posdata.so/referencia/objetos/#obj-taxbreakdownentry) \| null | Sí | — | | `notes` | string \| null | Sí | — | | `payment_link` | string \| null | Sí | — | | `expires_at` | string (date-time) \| null | Sí | — | | `sent_at` | string (date-time) \| null | Sí | — | | `items` | arreglo de [QuoteItem](https://developers.posdata.so/referencia/objetos/#obj-quoteitem) | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## CashMovement Entrada o salida manual de efectivo del cajón. | Campo | Tipo | Requerido | Descripción | | ------------ | ------------------ | --------- | ---------------------------------------------- | | `object` | `"cash_movement"` | Sí | — | | `id` | string (uuid) | Sí | — | | `type` | string | Sí | Valores: `in`, `out`. | | `amount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `reason` | string \| null | Sí | — | | `created_at` | string (date-time) | Sí | — | ## CashSession Turno de caja con sus movimientos de efectivo. | Campo | Tipo | Requerido | Descripción | | --------------- | --------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ | | `object` | `"cash_session"` | Sí | — | | `id` | string (uuid) | Sí | — | | `status` | string | Sí | open, closed, suspended. | | `terminal_name` | string | Sí | Nombre de la caja ("Caja 01"). | | `opening_cash` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `expected_cash` | integer \| null | Sí | Lo que la app calculó que debía haber al cerrar. | | `closing_cash` | integer \| null | Sí | Lo que se contó al cerrar. | | `opened_at` | string (date-time) | Sí | — | | `closed_at` | string (date-time) \| null | Sí | — | | `movements` | arreglo de [CashMovement](https://developers.posdata.so/referencia/objetos/#obj-cashmovement) | Sí | — | | `created_at` | string (date-time) | Sí | — | | `updated_at` | string (date-time) | Sí | — | ## DailySalesDay Totales de un día (hora de Bogotá). | Campo | Tipo | Requerido | Descripción | | ------------- | ------------- | --------- | ---------------------------------------------- | | `date` | string (date) | Sí | — | | `sales_count` | integer | Sí | Número de ventas completadas. | | `subtotal` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `discount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tax` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `tip_amount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `total` | integer | Sí | 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. | Campo | Tipo | Requerido | Descripción | | -------------------- | ----------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------- | | `object` | `"daily_sales_report"` | Sí | — | | `timezone` | `"America/Bogota"` | Sí | — | | `currency` | `"COP"` | Sí | — | | `from` | string (date) | Sí | — | | `to` | string (date) | Sí | — | | `days` | arreglo de [DailySalesDay](https://developers.posdata.so/referencia/objetos/#obj-dailysalesday) | Sí | Un elemento por día del rango, incluidos los días sin ventas (en cero). | | `totals` | object | Sí | — | | `totals.sales_count` | integer | Sí | Número de ventas completadas. | | `totals.subtotal` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `totals.discount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `totals.tax` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `totals.tip_amount` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | | `totals.total` | integer | Sí | Pesos colombianos (COP), entero sin decimales. | ## Event Evento del registro de webhooks. Sirve para reconciliar entregas perdidas. | Campo | Tipo | Requerido | Descripción | | ------------- | ------------------ | --------- | ------------------------------------------------------------------- | | `object` | `"event"` | Sí | — | | `id` | string (uuid) | Sí | — | | `type` | string | Sí | Tipo de evento, por ejemplo `sale.completed`. | | `created_at` | string (date-time) | Sí | — | | `data` | object | Sí | — | | `data.object` | object | Sí | 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`. | Campo | Tipo | Requerido | Descripción | | ------------- | ------- | --------- | -------------------------- | | `name` | string | Sí | Máximo 120 caracteres. | | `description` | string | No | Máximo 1000 caracteres. | | `sort_order` | integer | No | Mí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`. | Campo | Tipo | Requerido | Descripción | | ------------- | ------- | --------- | -------------------------- | | `name` | string | No | Máximo 120 caracteres. | | `description` | string | No | Máximo 1000 caracteres. | | `sort_order` | integer | No | Mínimo: 0. Máximo: 100000. | ## ProductCreate Un campo que no esté en la lista se rechaza con `VALIDATION_ERROR`. | Campo | Tipo | Requerido | Descripción | | ------------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sí | Máximo 200 caracteres. | | `description` | string | No | Máximo 5000 caracteres. | | `description_short` | string | No | Máximo 300 caracteres. | | `sku` | string | No | Máximo 60 caracteres. | | `category_id` | string (uuid) \| null | No | — | | `base_price` | integer | Sí | Precio base en pesos. Mínimo: 0. Máximo: 10000000000. | | `final_price` | integer | No | Precio al que vende la caja. Si no se envía, es igual a base_price. Mínimo: 0. Máximo: 10000000000. | | `percent_discount` | number | No | Mínimo: 0. Máximo: 100. | | `tax_class` | string | No | Clase 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`. | | `active` | boolean | No | Por defecto: `true`. | | `sellable` | boolean | No | `false` = insumo que no se vende solo. Por defecto: `true`. | | `base_unit` | string | No | Valores: `und`, `g`, `kg`, `lb`, `oz`, `ml`, `l`, `doc`. Por defecto: `und`. | | `sold_by_weight` | boolean | No | Requiere base_unit g, kg o lb. Por defecto: `false`. | | `initial_stock` | integer | No | Crea además un movimiento de entrada con este stock. Mínimo: 1. Máximo: 1000000000. | | `warehouse_id` | string (uuid) | No | Bodega 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`. | Campo | Tipo | Requerido | Descripción | | ------------------- | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `name` | string | No | Máximo 200 caracteres. | | `description` | string | No | Máximo 5000 caracteres. | | `description_short` | string | No | Máximo 300 caracteres. | | `sku` | string | No | Máximo 60 caracteres. | | `category_id` | string (uuid) \| null | No | — | | `base_price` | integer | No | Si cambias base_price sin enviar final_price, final_price toma el mismo valor. Mínimo: 0. Máximo: 10000000000. | | `final_price` | integer | No | Precio al que vende la caja. Mínimo: 0. Máximo: 10000000000. | | `percent_discount` | number | No | Mínimo: 0. Máximo: 100. | | `tax_class` | string | No | Valores: `standard`, `reduced_5`, `excluded`, `exempt`, `service_19`, `event_package`, `bag`, `passthrough`. | | `active` | boolean | No | — | | `sellable` | boolean | No | — | ## VariantUpdate Envía al menos 1 campo. Un campo que no esté en la lista se rechaza con `VALIDATION_ERROR`. | Campo | Tipo | Requerido | Descripción | | ------------------ | ------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `label` | string | No | Máximo 120 caracteres. | | `sku` | string | No | Único por cuenta. Máximo 60 caracteres. | | `base_price` | integer | No | Si cambias base_price sin enviar final_price, final_price toma el mismo valor. Mínimo: 0. Máximo: 10000000000. | | `final_price` | integer | No | Precio al que vende la caja. Mínimo: 0. Máximo: 10000000000. | | `percent_discount` | number | No | Mínimo: 0. Máximo: 100. | | `active` | boolean | No | — | ## CustomerCreate Un campo que no esté en la lista se rechaza con `VALIDATION_ERROR`. | Campo | Tipo | Requerido | Descripción | | ----------------- | ---------------------- | --------- | ---------------------------------------------------------------------------------------------- | | `name` | string | Sí | Máximo 120 caracteres. | | `last_name` | string | No | Máximo 120 caracteres. | | `phone` | string | No | Máximo 30 caracteres. | | `email` | string (email) \| null | No | Máximo 200 caracteres. | | `person_type` | string | No | Valores: `person`, `company`. Por defecto: `person`. | | `document_type` | string | No | Valores: `CC`, `TI`, `NIT`, `CE`, `PASAPORTE`. Por defecto: `CC`. | | `document_number` | string | No | Máximo 30 caracteres. | | `contact_channel` | string | No | Valores: `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`. | Campo | Tipo | Requerido | Descripción | | ----------------- | ---------------------- | --------- | ---------------------------------------------------------------------------------------------- | | `name` | string | No | Máximo 120 caracteres. | | `last_name` | string | No | Máximo 120 caracteres. | | `phone` | string | No | Máximo 30 caracteres. | | `email` | string (email) \| null | No | Máximo 200 caracteres. | | `person_type` | string | No | Valores: `person`, `company`. Por defecto: `person`. | | `document_type` | string | No | Valores: `CC`, `TI`, `NIT`, `CE`, `PASAPORTE`. Por defecto: `CC`. | | `document_number` | string | No | Máximo 30 caracteres. | | `contact_channel` | string | No | Valores: `none`, `store`, `whatsapp`, `instagram`, `website`, `referral`. Por defecto: `none`. | ## StockMovementCreate Un campo que no esté en la lista se rechaza con `VALIDATION_ERROR`. | Campo | Tipo | Requerido | Descripción | | -------------- | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `product_id` | string (uuid) | Sí | — | | `variant_id` | string (uuid) | No | Obligatorio si el producto tiene variantes: el movimiento es de esa variante. | | `warehouse_id` | string (uuid) | No | Por defecto, la bodega predeterminada (o la única bodega activa). | | `type` | string | Sí | `in` suma, `out` resta. Valores: `in`, `out`. | | `quantity` | number | Sí | 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. | | `reason` | string | No | Motivo visible en el historial. Por defecto "Movimiento vía API". Máximo 200 caracteres. | | `reference` | string | No | Tu referencia (orden de compra, pedido…). Máximo 100 caracteres. | | `unit_cost` | number | No | Solo 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`. | Campo | Tipo | Requerido | Descripción | | ------------------ | ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `product_id` | string (uuid) | Sí | — | | `variant_id` | string (uuid) | No | Obligatorio si el producto tiene variantes. | | `warehouse_id` | string (uuid) | No | Por defecto, la bodega predeterminada (o la única bodega activa). | | `counted_quantity` | number | Sí | 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_at` | string (date-time) | No | CUÁ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. | | `note` | string | No | Nota 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. | Campo | Tipo | Requerido | Descripción | | ----------------------- | --------------------- | --------- | ---------------------------------------------------------------------------------------- | | `object` | `"kardex"` | No | — | | `product` | object | No | — | | `product.id` | string (uuid) | No | — | | `product.local_id` | string | No | — | | `product.name` | string | No | — | | `rows` | arreglo de object | No | — | | `meta` | object | No | — | | `meta.page` | integer | No | — | | `meta.page_size` | integer | No | — | | `meta.total` | integer | No | — | | `meta.total_pages` | integer | No | — | | `levels` | arreglo de object | No | — | | `levels[].warehouse_id` | string (uuid) | No | — | | `levels[].variant_id` | string (uuid) \| null | No | — | | `levels[].quantity` | number | No | — | | `total_qty` | number | No | Existencia total del producto al final de lo consultado. | | `avg_cost` | number \| null | No | Costo promedio ponderado al final; `null` si se desconoce o no tienes `inventory:costs`. | | `warehouses` | arreglo de object | No | — | | `warehouses[].id` | string (uuid) | No | — | | `warehouses[].name` | string | No | — | | `costs_hidden` | boolean | No | `true` 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. | Campo | Tipo | Requerido | Descripción | | ----------------------------- | ----------------------- | --------- | -------------- | | `object` | `"inventory_valuation"` | No | — | | `at` | string (date-time) | No | — | | `computed_at` | string (date-time) | No | — | | `total_value` | integer | No | Pesos enteros. | | `by_warehouse` | arreglo de object | No | — | | `by_warehouse[].warehouse_id` | string (uuid) | No | — | | `by_warehouse[].name` | string | No | — | | `by_warehouse[].value` | integer | No | — | | `lines` | arreglo de object | No | — | | `lines[].product_id` | string (uuid) | No | — | | `lines[].product_name` | string | No | — | | `lines[].warehouse_id` | string (uuid) | No | — | | `lines[].warehouse_name` | string | No | — | | `lines[].variant_id` | string (uuid) \| null | No | — | | `lines[].quantity` | number | No | — | | `lines[].avg_cost` | number \| null | No | — | | `lines[].value` | integer \| null | No | — | | `meta` | object | No | — | | `meta.page` | integer | No | — | | `meta.page_size` | integer | No | — | | `meta.total` | integer | No | — | | `meta.total_pages` | integer | No | — | | `negatives` | arreglo de object | No | — | | `missing_cost` | arreglo de object | No | — | | `in_transit_value` | integer | No | — | | `costs_hidden` | boolean | No | — | --- Fuente: https://developers.posdata.so/referencia/objetos/ · Índice para agentes: https://developers.posdata.so/llms.txt