API: movimientos y reportes

Contrato general en Cómo funciona la API. Todos estos endpoints piden reports:read, que la key tiene, y quedan acotados a su cuenta.

Los rangos from y to son obligatorios (ISO 8601) y la paginación es por cursor: pide la página siguiente con cursor=<nextCursor> hasta que llegue null.

Entregas

GET /transactions
GET /transactions/summary
GET /transactions/:id/delivery-evidence

Query de GET /transactions:

Parámetro	Tipo	Notas
from, to	ISO 8601	obligatorios
businessLine	vending | eas	—
isDelivered	boolean	true exitosas, false fallidas
method	string	CASH, CASHLESS, CARD, WALLET, BRE_B, REMOTE
operationId, deviceId, deviceSerial, controllerSerial	string	—
productId, consumerIdentification	string	—
isReturnable	boolean	solo EAS
fields	string	lista de campos separada por coma, para acortar la respuesta
cursor	string	paginación
limit	entero	máx. 1000

curl -G https://api.inssacs.com/transactions \
  -H 'x-api-key: ics_…' \
  --data-urlencode 'from=2026-08-01T00:00:00.000Z' \
  --data-urlencode 'to=2026-08-31T23:59:59.999Z' \
  --data-urlencode 'businessLine=vending' \
  --data-urlencode 'isDelivered=true' \
  --data-urlencode 'limit=500'

Respuesta:

{
  "items": [
    {
      "id": "019fecb9-43e9-7969-aa90-eaf1aaf1f1db",
      "date": "2026-08-11T12:41:03.000Z",
      "businessLine": "vending",
      "isDelivered": true,
      "method": "CASHLESS",
      "failureReason": null,
      "currency": "COP",
      "device": { "serial": "ICS595DDE99B", "name": "Vending Corferias 1" },
      "consumer": { "name": "Juan Pérez", "identification": "1023456789", "codeId": "1023456789" },
      "product": {
        "name": "Chocoramo", "selection": "26", "cost": 2800, "sellValue": 4000,
        "priceWithoutTax": 3361, "tax": 19, "taxValue": 639, "profit": 1200,
        "balancePaid": 4000, "rechargePaid": 0
      }
    }
  ],
  "nextCursor": "eyJkYXRlIjoiMjAyNi0wOC0xMVQxMjo0MTowMy4wMDBaIn0"
}

GET /transactions/summary acepta los mismos filtros y devuelve conteo, valor total y desglose por tipo. GET /transactions/:id/delivery-evidence devuelve una URL temporal del video de la entrega (EAS), con su expiración.

Recargas

GET /transactions/recharges

Query: from, to (obligatorios), operationId, deviceId, consumerIdentification, consumerCode, cursor, limit. Cada ítem trae amount, balanceAfter, el código y el dispositivo.

Devoluciones

GET /transactions/returns
GET /transactions/returns/:id/evidence

Devuelve los pares entrega ↔ devolución de productos retornables, con estado, fechas de entrega y devolución, y las claves de los dos videos. El endpoint de evidencia entrega la URL temporal.

Crédito disponible

GET /consumers/report
POST /consumers/report/exports
GET  /consumers/report/exports/:id

GET /consumers/report da el saldo por código: subsidio, recarga, perfil, acumulable y fechas de último subsidio y última recarga. Query: operationId, search, cursor, limit.

Dashboard

GET /dashboard/summary
GET /dashboard/timeseries
GET /dashboard/products
GET /dashboard/devices
GET /dashboard/heatmap
GET /dashboard/payment-methods

Query común: from, to, accountId (el de la key), operationId opcional y, en timeseries, granularity (hour, day, week). Agregan solo ventas vending.

Exportaciones a Excel

Proceso asíncrono en dos pasos.

POST /transactions/exports   → 202 { "id": "…", "status": "pending" }
GET  /transactions/exports/:id → 200 { "status": "ready", "url": "https://…", "expiresAt": "…" }

Cuerpo del POST:

Campo	Tipo	Obligatorio	Notas
from, to	ISO 8601	sí	rango
columns	string[]	sí	al menos una; las columnas del reporte
businessLine, method, deviceId, productId, consumerIdentification	string	no	mismos filtros que la lista
isDelivered, isReturnable	boolean	no	—
timeZone	string	no	zona IANA para renderizar fechas (America/Bogota)
locale	string	no	idioma de los encabezados

Estados: pending → running → ready | failed. Se sondea el GET hasta ready y se descarga la url (temporal). Una exportación a la vez por actor: si hay otra en curso, 409 transactions.export.already_running.

El mismo patrón aplica a POST /consumers/report/exports.

Auditoría

GET /audit-logs

Query: resourceType, action, search, from, to, page, pageSize. Devuelve quién hizo qué y los valores anterior y nuevo. Útil para replicar la trazabilidad en un sistema propio: las acciones que haga la key aparecen con su etiqueta como autor.

Selectores y recibos

GET /selectors/:key          # catálogos estáticos: currencies, product_types, code_types…
GET /receipts/:frameUuid     # comprobante público de una entrega (no requiere autenticación)

GET /selectors/product_types es el que da los valores válidos del campo type de un producto.