Documentación oficial

Manual API oficinaPro.co

Esta API expone datos de negocio en modo solo lectura sobre https://data.oficinapro-mail.com. La autenticación es por token Bearer y la ruta pública es única: GET /api/v1/tables/{table_name}.

Acceso transaccional para ventas, compras, inventario, pagos y tablas auxiliares.

Descarga la guia.md para IA Agentes

Archivo Markdown para descarga directa y consumo por asistentes, automatizaciones o flujos LLM.

1. Conceptos base

Ruta pública única

Todo se consulta con GET /api/v1/tables/{table_name}.

Algunas tablas también soportan agrupación explícita, por ejemplo GET /api/v1/tables/inventory_transfers?group_by=batch_id.

Fila puntual

Para traer una fila específica se usa row_id.

GET /api/v1/tables/invoices?row_id=787816&created_at_from=2026-02-11&created_at_to=2026-02-11

Relaciones

Se piden con include cuando la API las soporta.

GET /api/v1/tables/invoices?include=items&...

Paginación

La paginación es fija de 1000 filas por página.

2. Autenticación

La autenticación es por encabezado Bearer:

Authorization: Bearer dummy-token

Ejemplo completo:

curl -H "Authorization: Bearer dummy-token" \
  "https://data.oficinapro-mail.com/api/v1/tables/accounts?page=1"

3. Contrato HTTP y formato de respuesta

La respuesta de lista sigue este orden fijo:

{
  "pagination": { "page": 1, "page_size": 1000, "total": 52, "total_pages": 1 },
  "request": {
    "table": "accounts",
    "sort": "id",
    "order": "desc",
    "returned_records": 0,
    "applied_filters": {}
  },
  "data": [ ... ]
}

Use siempre filtros por query string y lea los resultados en data, con metadatos de consulta en request y paginación en pagination.

El campo request.returned_records indica cuántos registros se incluyen realmente en data.

4. Reglas de filtros y ordenamiento

campo=valor: filtro exacto
campo_contains=texto: búsqueda textual
campo_gte=valor y campo_lte=valor: rangos numéricos
created_at_from y created_at_to: rangos de fecha
updated_at_from / updated_at_to y deposited_at_from / deposited_at_to cuando la tabla lo soporta
sort y order=asc|desc: ordenamiento por columnas soportadas

Normalización de fechas: si se envía solo fecha, la API expande el rango a día completo. Por ejemplo: created_at_from=2026-02-11 se interpreta como 2026-02-11 00:00:00 y created_at_to=2026-02-11 como 2026-02-11 23:59:59.

Tablas con rango obligatorio de created_at: inventory_movements, invoice_items, invoice_expenses, invoices, credit_notes, outgoing_payments, payments, provider_invoice_items, provider_invoices, quotations y quotation_items.

5. Relaciones soportadas por la API

Tabla base	Parámetro	Qué devuelve	Ejemplo
`credit_notes`	`type=1\|2\|3&include=items`	Nota de crédito con factura relacionada; anulación incluye las líneas de la factura y devolución/ajuste las líneas del `payload`	`/api/v1/tables/credit_notes?type=2&include=items&created_at_from=2026-02-01&created_at_to=2026-02-28`
`invoices`	`include=items`	Cabecera de factura con sus `invoice_items`	`/api/v1/tables/invoices?include=items&created_at_from=2026-02-11&created_at_to=2026-02-11`
`remissions`	`include=items`	Cabecera de remisión con sus `invoice_items`	`/api/v1/tables/remissions?include=items&created_at_from=2026-02-11&created_at_to=2026-02-11`
`quotations`	`include=items`	Líneas de `quotation_items` ligadas por `quotation_id`	`/api/v1/tables/quotations?include=items&created_at_from=2026-09-01&created_at_to=2026-09-02`
`provider_invoices`	`include=details`	Cabecera de proveedor con `provider_invoice_items` si `is_invoice=1` o `invoice_expenses` si `is_invoice=5`	`/api/v1/tables/provider_invoices?include=details&created_at_from=2026-02-01&created_at_to=2026-02-28`
`new_products`	`include=inventory`	Producto con inventario actual por SKU y por oficina	`/api/v1/tables/new_products?include=inventory&row_id=2550`

6. Facturas de ventas

Tabla principal

/api/v1/tables/invoices

Qué contiene: cabecera de documentos de venta: cliente, oficina, totales, impuestos, estado, datos de despacho, metadatos de factura electrónica y referencias contables.

Sentido de negocio: es la tabla maestra de ventas legales y POS. Las remisiones se documentan por separado en el alias público remissions.

Reglas de negocio clave: status=2 significa anulada y se excluye por defecto. is_pos=1 identifica ventas POS.

Campo opcional: payment_history solo aparece si el request incluye show_payments=1.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios. Rango principal de consulta.
`id`, `invoice_number`, `cdc`	Búsqueda exacta por identificador o número documental.
`code`, `code_contains`	Prefijo documental o consecutivo visible.
`status`, `is_pos`, `office_id`, `user_id`, `account_id`	Clasificación y segmentación operativa.
`total_gte/lte`	Rangos de valor total.
`updated_at_from/to`, `deposited_at_from/to`	Auditoría o depósito.

Caso de negocio: finanzas quiere consultar las facturas del día, ordenadas de la más reciente a la más antigua, para revisar el cierre de ventas.

GET /api/v1/tables/invoices?created_at_from=2026-02-11&created_at_to=2026-02-11&sort=created_at&order=desc

Relación disponible: include=items devuelve la factura junto con sus líneas de venta.

GET /api/v1/tables/invoices?include=items&created_at_from=2026-02-11&created_at_to=2026-02-11

6A. Remisiones

Alias público

/api/v1/tables/remissions

Qué contiene: cabecera de remisiones comerciales expuesta desde la misma tabla física invoices.

Sentido de negocio: separa remisiones del flujo de facturas legales para que el usuario no mezcle tipos documentales en reportes de venta.

Reglas de negocio clave: por defecto no muestra remisiones que ya fueron convertidas a factura. Si el request incluye converted_to_invoice=1, devuelve esas remisiones convertidas. status=2 se excluye por defecto.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios. Rango principal de consulta.
`id`, `invoice_number`, `cdc`	Búsqueda exacta por identificador o número documental.
`code`, `code_contains`	Prefijo documental o consecutivo visible.
`status`, `is_pos`, `office_id`, `user_id`, `account_id`	Clasificación y segmentación operativa.
`converted_to_invoice`	Si vale `1`, devuelve remisiones que ya fueron convertidas a factura.
`total_gte/lte`	Rangos de valor total.
`updated_at_from/to`, `deposited_at_from/to`	Auditoría o depósito.

Caso de negocio: operaciones quiere consultar remisiones del día sin mezclar facturas legales.

GET /api/v1/tables/remissions?created_at_from=2026-02-11&created_at_to=2026-02-11

Remisiones convertidas:

GET /api/v1/tables/remissions?created_at_from=2026-02-11&created_at_to=2026-02-11&converted_to_invoice=1

Relación disponible: include=items devuelve la remisión junto con sus líneas de venta.

GET /api/v1/tables/remissions?include=items&created_at_from=2026-02-11&created_at_to=2026-02-11

6B. Notas de crédito

Ventas

/api/v1/tables/credit_notes?type={1|2|3}

Qué contiene: notas de crédito de venta. El parámetro type es obligatorio y separa los tres flujos para evitar mezclarlos.

type	Tipo	Factura relacionada	Detalle
`1`	Devolución	`is_return_for_invoice`	`items` se obtiene del JSON `payload` de la nota.
`2`	Anulación	`invoice_id`	`items` contiene las líneas actuales de la factura asociada.
`3`	Ajuste de precio	`is_price_adjustment`	`items` se obtiene del JSON `payload`.

Filtros: type (obligatorio), created_at_from y created_at_to (obligatorios), id, user_id, office_id, invoice_id, status, number, amount_gte/lte, total_gte/lte y updated_at_from/to.

Relación disponible: include=items agrega invoice en los tres tipos. Para tipo 2, items son las líneas de invoice_items de la factura asociada por invoice_id. Para tipos 1 y 3, items se decodifica desde payload de la nota y la propiedad cruda payload se omite.

GET /api/v1/tables/credit_notes?type=2&include=items&created_at_from=2026-02-01&created_at_to=2026-02-28

7. Ítems de facturas de venta

Detalle

/api/v1/tables/invoice_items

Qué contiene: líneas de venta por factura: producto, cantidad, descuentos, impuestos, costo, comisión, vendedor, cliente, oficina, serial y SKU.

Sentido de negocio: permite análisis finos de ventas por línea, por producto, por vendedor y por oficina.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`id`, `invoice_id`, `product_id`, `category_id`, `sold_by`, `user_id`, `office`, `sold_in`	Filtros exactos por documento, categoría, vendedor o sede.
`flaid`, `flaid_contains`	SKU o referencia del producto.
`name`, `name_contains`, `brand`, `brand_contains`	Texto descriptivo de producto o marca.
`nulled`	Distinguir líneas anuladas.
`updated_at_from/to`	Auditoría.

Caso de negocio: ventas quiere saber qué artículos vendió un asesor en una sede específica durante un día.

GET /api/v1/tables/invoice_items?created_at_from=2026-02-11&created_at_to=2026-02-11&sold_by=30275&sold_in=3

Filtro por categoría: category_id se resuelve internamente hacia flaid, incluyendo variaciones cuando el producto base no tiene SKU propio.

GET /api/v1/tables/invoice_items?created_at_from=2026-02-11&created_at_to=2026-02-11&category_id=12

Relación disponible: normalmente se consume embebida desde /api/v1/tables/invoices?include=items.

8. Facturas de compra

Proveedor

/api/v1/tables/provider_invoices?is_invoice=1

Qué contiene: cabecera de cuentas por pagar de proveedor cuando el documento representa compra de inventario o mercancía.

Sentido de negocio: concentra proveedor, moneda, totales, impuestos, estado del documento y trazabilidad de carga a inventario.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`is_invoice=1`	Restringe el resultado a compras.
`id`, `user_id`, `office_id`, `updated_by`, `cdc`	Identificación del documento.
`number`, `invoice_number`, `invoice_number_contains`	Número interno o del proveedor.
`status`, `pushed`, `currency`	Estado administrativo.
`total_gte/lte`, `updated_at_from/to`	Montos y auditoría.

Caso de negocio: compras quiere revisar facturas de proveedor registradas en el mes para validar qué documentos deben entrar a inventario.

GET /api/v1/tables/provider_invoices?is_invoice=1&created_at_from=2026-02-01&created_at_to=2026-02-28&status=0

Relación disponible: include=details trae los productos comprados como provider_invoice_items.

GET /api/v1/tables/provider_invoices?is_invoice=1&include=details&created_at_from=2026-02-01&created_at_to=2026-02-28

9. Productos en facturas de compra

Detalle compra

/api/v1/tables/provider_invoice_items

Qué contiene: líneas de compra de facturas de proveedor cuando provider_invoices.is_invoice=1.

Sentido de negocio: permite analizar cantidades, costos, impuestos y SKU recibidos en cada compra.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`id`, `invoice_id`, `provider_id`, `category_id`, `updated_by`	Documento, proveedor o categoría exacta.
`flaid`, `flaid_contains`	SKU o referencia.
`name`, `name_contains`	Descripción del producto.
`invoice_canceled`	Estado de cancelación del documento.
`updated_at_from/to`	Auditoría.

Caso de negocio: compras necesita ver qué SKUs llegaron en una factura de proveedor concreta.

GET /api/v1/tables/provider_invoice_items?created_at_from=2026-02-01&created_at_to=2026-02-28&invoice_id=12345

Filtro por categoría: category_id se resuelve internamente hacia flaid, incluyendo variaciones desde product_extensions cuando aplica.

GET /api/v1/tables/provider_invoice_items?created_at_from=2026-02-01&created_at_to=2026-02-28&category_id=12

Relación disponible: normalmente se consume mediante /api/v1/tables/provider_invoices?is_invoice=1&include=details.

10. Productos

Maestro

/api/v1/tables/new_products

Qué contiene: catálogo maestro de productos y servicios con impuestos, precios, comportamiento de inventario, serialización, proveedor y datos de clasificación.

Sentido de negocio: define cómo se vende, compra y controla cada ítem del catálogo.

Variaciones: cuando new_products.flaid viene vacío, la API agrega variations con registros de product_extensions ligados por product_id, siempre que esas variaciones sí tengan flaid. Esto ocurre incluso sin usar include.

Búsqueda por SKU de variación: si flaid no encuentra un registro en new_products, la API lo busca en product_extensions. Los resultados de variación incluyen unit_measure tomado de su producto padre; este campo guarda la ubicación del producto. Su name empieza con el nombre del producto padre y continúa con el nombre de la variación.

Inventario en variaciones: si la consulta usa include=inventory, cada registro dentro de variations también recibe su propio bloque inventory resuelto por el flaid de la variación.

Campo opcional: description no se devuelve por defecto en new_products. Solo aparece si el request incluye show_description=1.

Filtros	Uso
`id`, `provider_id`, `category_id`, `extension_id`, `created_by`, `updated_by`	Identificación exacta o filtrado por categoría.
`flaid`, `flaid_contains`	SKU.
`name`, `name_contains`	Nombre o descripción.
`barcode`, `barcode_contains`	Código de barras.
`status`, `is_service`, `saleable`, `adds_to_inventory`, `with_serial`, `check_inventory`	Clasificación funcional.
`created_at_from/to`, `updated_at_from/to`	Auditoría.

Caso de negocio: catálogo quiere listar productos activos que afectan inventario y manejan serial.

GET /api/v1/tables/new_products?status=1&adds_to_inventory=1&with_serial=1

Filtro por categoría: category_id se resuelve internamente usando la relación producto-categoría y devuelve solo los productos asociados.

GET /api/v1/tables/new_products?category_id=12&status=1

Ejemplo con variaciones: si el producto padre no tiene flaid, la respuesta incluirá variations con los SKUs reales definidos en product_extensions.

GET /api/v1/tables/new_products?row_id=69

GET /api/v1/tables/new_products?row_id=69&show_description=1

Relación disponible: include=inventory agrega el saldo actual por oficinas usando flaid.

GET /api/v1/tables/new_products?include=inventory&row_id=2550

GET /api/v1/tables/new_products?include=inventory&row_id=69

11. Cotizaciones

Comercial

/api/v1/tables/quotations

Qué contiene: cabeceras de cotizaciones comerciales, con cliente, sede, vencimiento, impuestos, descuentos y total.

Líneas: include=items agrega las filas de quotation_items en items, igual que las facturas.

Filtros disponibles: id, user_id, office, updated_by, status, expires_on, total_gte, total_lte, subtotal_gte, subtotal_lte, created_at_from, created_at_to, updated_at_from, updated_at_to.

Rango obligatorio: las consultas de lista requieren created_at_from y created_at_to.

GET /api/v1/tables/quotations?include=items&created_at_from=2026-09-01&created_at_to=2026-09-02

Ítems por separado: /api/v1/tables/quotation_items expone cantidad, SKU, precios, descuentos, IVA e importes netos y brutos; también requiere rango de creación.

12. Inventario actual

Stock

/api/v1/tables/inventories

Qué contiene: saldo de inventario actual por SKU (flaid), costo estándar y columnas dinámicas por oficina.

Sentido de negocio: responde cuánto stock hay hoy por referencia y en qué sedes se encuentra.

Filtros	Uso
`id`	Registro exacto.
`flaid`, `flaid_contains`	SKU o referencia.
`cost_gte`, `cost_lte`	Rangos de costo.
`is_service`, `updated_by`	Clasificación o auditoría.
`created_at_from/to`, `updated_at_from/to`	Rangos de auditoría.

Caso de negocio: operaciones quiere revisar el costo y el saldo actual de un SKU específico.

GET /api/v1/tables/inventories?flaid=2059

Relación disponible: también puede obtenerse desde /api/v1/tables/new_products?include=inventory.

12. Movimientos de inventario

Histórico

/api/v1/tables/inventory_movements

Qué contiene: libro mayor de movimientos de inventario con SKU, cantidad movida, oficina, saldo posterior, documento origen y origen operativo.

Sentido de negocio: sirve para auditar entradas, salidas, ajustes y transferencias de stock.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios. Rango de consulta.
`id`, `office_id`, `updated_by`, `inventory_adjustment_id`	Filtros exactos.
`flaid`, `flaid_contains`	SKU.
`reference`, `reference_contains`	Documento origen.
`type`, `qty_gte`, `qty_lte`	Tipo y cantidad del movimiento.
`updated_at_from/to`	Auditoría.

Caso de negocio: inventarios necesita revisar qué movimientos tuvo un SKU en un día y en qué oficina.

GET /api/v1/tables/inventory_movements?created_at_from=2026-02-11&created_at_to=2026-02-11&flaid=0297&office_id=3

13. Traslados de inventario

Trazabilidad entre sedes

/api/v1/tables/inventory_transfers

Qué contiene: líneas de traslados de inventario entre oficinas. Cada fila representa un SKU o referencia dentro de un traslado, y batch_id agrupa todas las líneas del mismo movimiento.

Costos calculados: cada línea incluye cost, tomado de inventories.cost para el mismo flaid, y total_cost, calculado como cost * qty. Son costos estándar actuales, no una instantánea histórica; ambos valores son null si no existe inventario o costo para la referencia.

Sentido de negocio: permite auditar solicitudes, aprobaciones, tránsito y consolidación de stock entre sedes.

Agrupación disponible: si el request incluye group_by=batch_id, la API devuelve un registro por traslado en vez de una fila por SKU. La cabecera se genera con la primera línea del lote, incluye total_cost como la suma del costo total de todas las líneas, y items contiene todas las líneas individuales, incluida la primera. El total agrupado es null si alguna línea no tiene costo calculable.

Significado de estados:

0: borrador. Traslado en preparación; no mueve inventario.
1: solicitado. La sede destino lo solicitó; todavía no mueve inventario.
2: aprobado y en tránsito. El inventario ya salió de la sede origen, pero aún no entra a la sede destino.
3: consolidado. La sede destino recibió el traslado; el inventario ya quedó sumado en destino.
4: reversado. Revierte un traslado consolidado y deshace su efecto en inventario.

Filtros disponibles: id, batch_id, user_id, from_office_id, to_office_id, updated_by, approved_by, flaid, flaid_contains, status, qty_gte, qty_lte, suggested_gte, suggested_lte, created_at_from, created_at_to, updated_at_from, updated_at_to.

Caso de negocio: operaciones quiere revisar todas las líneas del traslado 1847 y validar si ya fue aprobado y consolidado.

GET /api/v1/tables/inventory_transfers?batch_id=1847&sort=created_at&order=asc

GET /api/v1/tables/inventory_transfers?group_by=batch_id&sort=created_at&order=desc

Ejemplo para traer todos los traslados en tránsito:

GET /api/v1/tables/inventory_transfers?status=2&group_by=batch_id&sort=created_at&order=desc

13. Pagos salientes

Egresos

/api/v1/tables/outgoing_payments

Qué contiene: pagos realizados por la empresa a proveedores, nómina u otros documentos. Incluye monto, cuenta usada, aprobaciones, confirmaciones y banderas de transferencia.

Sentido de negocio: es la tabla central de egresos monetarios.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`id`, `user_id`, `office_id`, `account_id`, `created_by`, `updated_by`, `approved_by`, `confirmed_by`	Seguimiento exacto por responsable o cuenta.
`number`, `status`, `currency`	Control administrativo.
`is_transfer`, `is_wage`	Tipo de egreso.
`amount_gte/lte`, `updated_at_from/to`, `deposited_at_from/to`	Montos y ejecución.

Caso de negocio: tesorería quiere ver pagos salientes de nómina realizados en un rango de fechas.

GET /api/v1/tables/outgoing_payments?created_at_from=2026-02-01&created_at_to=2026-02-28&is_wage=1

14. Pagos recibidos

Recaudo

/api/v1/tables/payments

Qué contiene: pagos recibidos o aplicados a facturas y notas crédito. Incluye cliente, oficina, cuenta receptora, referencia y estado.

Sentido de negocio: es la fuente transaccional de recaudo.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`id`, `user_id`, `office_id`, `account_id`, `created_by`, `updated_by`, `confirmed_by`	Exactos.
`number`, `status`, `is_transfer`, `un_identified`	Seguimiento operativo.
`voucher_ref`, `voucher_ref_contains`	Comprobante o referencia bancaria.
`amount_gte/lte`, `updated_at_from/to`, `deposited_at_from/to`	Montos y depósito.

Caso de negocio: cartera quiere revisar pagos confirmados depositados durante un período.

GET /api/v1/tables/payments?created_at_from=2026-02-01&created_at_to=2026-02-28&status=1

15. Gastos

Proveedor

/api/v1/tables/provider_invoices?is_invoice=5

Qué contiene: cabecera de documentos de proveedor cuando el registro representa un gasto y no una compra de inventario.

Sentido de negocio: permite controlar cuentas por pagar por servicios, honorarios, arrendamientos, impuestos u otros egresos operativos.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`is_invoice=5`	Restringe el resultado a gastos.
`id`, `user_id`, `office_id`, `updated_by`, `cdc`	Identificación exacta.
`number`, `invoice_number`, `invoice_number_contains`	Número interno o del soporte.
`status`, `pushed`, `currency`	Estado y moneda.
`total_gte/lte`, `updated_at_from/to`	Montos y auditoría.

Caso de negocio: contabilidad quiere revisar los gastos de proveedor causados en el mes para conciliación de cuentas por pagar.

GET /api/v1/tables/provider_invoices?is_invoice=5&created_at_from=2026-02-01&created_at_to=2026-02-28&status=0

Relación disponible: include=details trae el detalle como invoice_expenses.

GET /api/v1/tables/provider_invoices?is_invoice=5&include=details&created_at_from=2026-02-01&created_at_to=2026-02-28

16. Detalles de gastos

Detalle gasto

/api/v1/tables/invoice_expenses

Qué contiene: líneas de gasto asociadas a documentos de proveedor cuando provider_invoices.is_invoice=5.

Sentido de negocio: descompone gastos de proveedor en subtotal, impuestos, retenciones y total final por línea.

Filtros	Uso
`created_at_from` y `created_at_to`	Obligatorios.
`id`, `invoice_id`, `expense_id`, `updated_by`	Identificación del gasto.
`name`, `name_contains`	Descripción del concepto.
`subtotal_gte/lte`, `total_gte/lte`	Montos.
`updated_at_from/to`	Auditoría.

Caso de negocio: contabilidad quiere revisar los conceptos que componen una cuenta por pagar de tipo gasto.

GET /api/v1/tables/invoice_expenses?created_at_from=2026-02-01&created_at_to=2026-02-28&invoice_id=50362

Relación disponible: normalmente se consume desde /api/v1/tables/provider_invoices?is_invoice=5&include=details.

Tablas auxiliares

Referencia

Las siguientes tablas complementan ventas, compras, pagos e inventario. Sirven para resolver nombres, clasificaciones, sedes y terceros relacionados con los documentos transaccionales.

17. Cuentas

Auxiliar

/api/v1/tables/accounts

Qué contiene: catálogo de cuentas usado para traducir account_id a un nombre legible en ventas, cobros y pagos.

Sentido de negocio: permite saber qué cuenta bancaria o caja está asociada a una operación financiera.

Filtros	Uso
`id`	Cuenta exacta por identificador.
`name`, `name_contains`	Búsqueda por nombre visible.

Caso de negocio: tesorería quiere encontrar el nombre exacto de la cuenta usada en cobros y pagos.

GET /api/v1/tables/accounts?name_contains=Banco

18. Categorías

Auxiliar

/api/v1/tables/categories

Qué contiene: catálogo maestro de categorías para clasificar productos y otras entidades relacionadas por category_id.

Sentido de negocio: sirve para etiquetar y agrupar el portafolio.

Filtros	Uso
`id`	Categoría exacta.
`name`, `name_contains`	Búsqueda por nombre.

Caso de negocio: un usuario comercial quiere localizar la categoría “Brazaletes” para asociar productos.

GET /api/v1/tables/categories?name_contains=Brazal

20. Oficinas

Auxiliar

/api/v1/tables/offices

Qué contiene: catálogo de sedes, sucursales o ubicaciones. También interpreta las columnas dinámicas de inventario por oficina.

Sentido de negocio: traduce ids de oficina a nombres legibles en ventas, compras e inventario.

Filtros	Uso
`id`	Oficina exacta.
`name`, `name_contains`	Búsqueda por sede.

Caso de negocio: operaciones necesita saber el nombre exacto de la oficina asociada a una venta o a un saldo de inventario.

GET /api/v1/tables/offices?name_contains=Carta

21. Usuarios, clientes y proveedores

Auxiliar

/api/v1/tables/users

Qué contiene: catálogo maestro de personas y entidades. No representa solo usuarios del sistema: también clientes, proveedores, empleados y contactos.

Sentido de negocio: centraliza identidad comercial, contacto, datos tributarios y políticas de crédito.

Token de verificación: la respuesta incluye verified_token, asociado a la verificación de la entidad. Es un campo de solo lectura y no admite filtro ni ordenamiento.

Filtros	Uso
`id`, `created_by`, `updated_by`	Exactos.
`name`, `name_contains`	Nombre o razón social.
`email`, `email_contains`	Correo.
`personal_id`, `personal_id_contains`	Documento o NIT.
`admin`, `admin_gte`, `has_credit`	Clasificación de acceso o crédito.
`created_at_from/to`, `updated_at_from/to`	Auditoría.

Caso de negocio: cartera quiere identificar clientes con crédito habilitado y documento conocido.

GET /api/v1/tables/users?has_credit=1&personal_id_contains=900

22. Garantías

Regla funcional

Cómo funciona:

new_products.warranty guarda la configuración de garantía del producto en el catálogo maestro.
Cuando se factura, ese valor queda copiado en invoice_items.warranty.
Esto permite conservar los días de garantía exactamente como estaban al momento de la venta, aunque después cambie la configuración del producto.

Sentido de negocio:

new_products responde la garantía vigente hoy en el catálogo.
invoice_items responde la garantía histórica con la que realmente se vendió el producto.

Ejemplo práctico:

Si un producto tenía warranty = 365 cuando se emitió la factura, esa línea queda grabada con invoice_items.warranty = 365.
Si después el producto cambia a warranty = 180 en new_products, la factura anterior sigue conservando invoice_items.warranty = 365.

Consultas útiles:

GET /api/v1/tables/new_products?row_id=2550

GET /api/v1/tables/invoice_items?created_at_from=2026-02-11&created_at_to=2026-02-11&invoice_id=787816

Resumen operativo

La forma práctica de usar la API es esta:

GET https://data.oficinapro-mail.com/api/v1/tables/{table_name}

use Authorization: Bearer <token>
envíe filtros simples y documentados por query string
use row_id para una fila puntual
use include solo cuando la tabla lo soporte
para invoices, agregue show_payments=1 solo si necesita payment_history