Datos para agentes

Listados

Cinco listados del negocio, fila a fila, con los mismos permisos y sucursales que tendría una persona con el acceso del agente. Solo para claves de agente: una clave de integración recibe 403 agent_required.

Los listados

Endpoint	Qué trae	Módulo · nivel
`GET /expenses`	Gastos con su categoría, estado de aprobación e importe	`gastos` · Ver
`GET /purchase-invoices`	Facturas de proveedor con su proveedor, estado, saldo por pagar y moneda	`compras.facturas` · Ver
`GET /contacts`	Clientes y proveedores	`contactos` · Ver
`GET /products`	Catálogo con precio, impuesto y existencias. Costos solo con `costos.ver`	`catalogo.productos` · Ver
`GET /quotes`	Cotizaciones con su estado, cliente e importe	`ventas.cotizaciones` · Ver

Las facturas de venta y los demás comprobantes tienen sus propios listados, de siempre: GET /invoices, GET /credit-notes… Ver Límites y paginación.

Filtros

Endpoint	Parámetro	Valores
Todos	`desde`, `hasta`	`AAAA-MM-DD`. Opcionales: sin ellos, no se filtra por fecha. En gastos, por fecha del gasto; en facturas de proveedor, por fecha de emisión; en cotizaciones, por fecha de creación. Contactos y productos no se filtran por fecha
`/expenses`	`estado`	`pending`, `approved`, `rejected`, `reimbursed`. Varios, separados por comas
	`categoria`	Id de la categoría de gasto
`/purchase-invoices`	`estado`	`draft`, `registered`, `cancelled`. Varios, separados por comas
	`estado_pago`	`pending`, `partial`, `paid`. Varios, separados por comas
	`proveedor`	Id del proveedor. Varios, separados por comas
	`buscar`	Texto en el nombre o la identificación del proveedor, o en el número de su factura
`/contacts`	`tipo`	`customer`, `supplier` o `both`. Varios, separados por comas
	`buscar`	Texto en el nombre, la razón social y los datos de contacto
`/products`	`buscar`	Texto en el producto
	`con_stock`	`true`: quita los bienes agotados. Los servicios y los bienes sin control de stock se quedan
	`stock_bajo`	`true`: solo los que tienen mínimo y están en él o por debajo
`/quotes`	`estado`	`draft`, `sent`, `accepted`, `rejected`, `converted`, `expired`, `cancelled`. Varios, separados por comas
	`buscar`	Texto en el número de la cotización o en los datos del cliente

A diferencia de los KPIs, los listados no tienen periodo por defecto ni límite de 366 días: filtran solo por las fechas que envíes, y la paginación acota cada respuesta. El parámetro sucursal no se aplica a los listados: un agente limitado a sus sucursales recibe solo las filas de sus sucursales.

Paginación

Parámetro	Por defecto	Máximo
`pagina`	1	—
`por_pagina`	50	100

La respuesta trae meta, como los KPIs, y en datos las filas con su página:

{
  "meta": {
    "moneda": "USD",
    "sucursal": null,
    "generado_en": "2026-10-12T15:40:22.903117+00:00",
    "definiciones": "/api/v1/kpis",
    "periodo": null,
    "datos_personales": "enmascarados"
  },
  "datos": {
    "filas": [
      {
        "id": "5a7c9e1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b",
        "contact_type": "customer",
        "legal_name": "COMERCIAL ANDINA S.A.",
        "trade_name": "Andina",
        "tax_id": "**********001",
        "email": "f***@andina.ec",
        "phone": "*******567",
        "address": "***********************253"
      }
    ],
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "hay_mas": false,
    "recortadas_por_tope": 0
  }
}

Campo	Qué es
`filas`	Las filas de esta página. Cada una con los campos del recurso en Olympus, en `snake_case`
`pagina`	La página devuelta
`por_pagina`	Filas por página, la que pediste. Las páginas se cuentan siempre con ella
`total`	Filas en total con esos filtros
`hay_mas`	`true` si hay otra página después de esta
`recortadas_por_tope`	Filas de esta página que no se devolvieron porque el agente llegó a su tope de registros leídos del día. `0` casi siempre

Recorre un listado pidiendo pagina + 1 mientras hay_mas sea true:

POR_PAGINA = 100


class TopeDiarioAlcanzado(Exception):
    """El agente leyó hoy todo lo que tiene permitido; la página indica dónde retomar."""


def todos_los_contactos(olympus, **filtros):
    pagina = 1
    while True:
        respuesta = olympus.get("/contacts", params={**filtros, "pagina": pagina, "por_pagina": POR_PAGINA})
        respuesta.raise_for_status()
        datos = respuesta.json()["datos"]
        yield from datos["filas"]
        if datos["recortadas_por_tope"]:
            # Se acabaron los registros del día. Mañana, vuelve a pedir esta página: llegará completa.
            raise TopeDiarioAlcanzado(pagina)
        if not datos["hay_mas"]:
            break
        pagina += 1

Una petición nunca devuelve más filas de las que le quedan hoy al agente. Si le quedan menos que por_pagina, la página llega recortada y recortadas_por_tope dice cuántas filas faltan. Las páginas se siguen contando con el por_pagina que pediste, así que la siguiente empieza donde debe; pero si recortadas_por_tope es mayor que 0, el agente agotó su tope del día y la siguiente petición responderá 429 agent_limit_exceeded. Retoma al día siguiente pidiendo esa misma página, que llegará completa.

En los listados, meta.periodo es null: no hay periodo por defecto.

Datos personales

Sin el permiso datos.personales, los correos, teléfonos, direcciones e identificaciones de cada fila llegan enmascarados, como en el ejemplo. Las razones sociales y los nombres se ven completos. Con el permiso, meta.datos_personales es "visibles" y todo llega en claro. Ver Permisos.

Consumo

Cada fila devuelta cuenta como un registro leído para el tope diario del agente (max_daily_rows_read, 20 000 por defecto). Un listado nunca devuelve más de los que le quedan.
Las respuestas se guardan 60 segundos por agente, permisos y parámetros, como los KPIs.

Lo siguiente

Reportes contables.
KPIs: las cifras agregadas, sin bajar a cada fila.