Paginación

Qué se manda

En un recurso que se pide con GET van en la dirección, como parámetros de consulta. Si llamás la operación por su nombre, van en el cuerpo JSON junto con los demás campos.

curl "https://panel.kaptativa.app/api/v1/gestion/clientes?limite=25" \
  -H "Authorization: Bearer TU_TOKEN"

Qué vuelve

{
  "datos": [
    {
      "id": "c0a8012e-7b1f-4c3a-9d2e-5f6a7b8c9d0e",
      "nombre": "Ana García"
    },
    {
      "id": "5d1c9a70-3e4b-4f8a-a2c6-9b0d1e2f3a4b",
      "nombre": "Bruno Díaz"
    }
  ],
  "paginacion": {
    "siguiente": "eyJwIjoyNX0",
    "total": 132
  }
}

Por su recurso, el listado es el cuerpo de la respuesta, sin envoltorio. Si llamás la misma operación por su nombre (POST /v1/herramientas/<nombre>), viene igual pero dentro de resultado.

• datos es la lista de la página. Los campos de cada registro dependen de la operación, y algunos listados suman contadores al lado de datos.
• paginacion.siguiente es el cursor de la página que sigue, o null cuando no hay más.
• paginacion.total es cuántos registros hay en total con esos filtros, no cuántos vinieron.

Recorrer todo

Repetí el pedido con el cursor que vino hasta que siguiente sea null. Los filtros tienen que ser los mismos en todas las páginas.

async function todos() {
  const registros = [];
  let cursor = null;
  do {
    const direccion = new URL("https://panel.kaptativa.app/api/v1/gestion/clientes");
    direccion.searchParams.set("limite", "100");
    if (cursor) direccion.searchParams.set("cursor", cursor);
    const respuesta = await fetch(direccion, {
      headers: { Authorization: `Bearer ${process.env.KAPTATIVA_TOKEN}` },
    });
    if (!respuesta.ok) throw new Error(`La API respondió ${respuesta.status}`);
    const { datos, paginacion } = await respuesta.json();
    registros.push(...datos);
    cursor = paginacion.siguiente;
  } while (cursor);
  return registros;
}

Cada página cuenta como un pedido para los límites de uso. Con limite=100 hacés menos pedidos.

Reglas del cursor

• Es opaco: mandalo tal como vino, sin armarlo ni modificarlo. Lo que lleva adentro puede cambiar sin aviso.
• Vale para la misma operación con los mismos filtros. No lo guardes para otro día.
• Un cursor que no se entiende responde 422 con el código entrada y el detalle en el campo cursor. Lo mismo un limite fuera de 1 a 100, con el detalle en limite.
• Un cursor que apunta más allá del final no es un error: responde una página vacía con siguiente en null.

Operaciones que paginan

• GET /v1/gestion/tickets Lista los tickets de soporte de la cuenta con su estado, por grupo (abiertos, nuevos, resueltos, cerrados) y tipo.
• GET /v1/gestion/clientes Busca clientes por nombre, email o documento y muestra su tipo, contacto y vendedor; sin texto, los más recientes.
• GET /v1/gestion/proveedores Busca proveedores por nombre, razón social o CUIT y muestra su rubro, contacto y horario de atención.
• GET /v1/gestion/tarjetas Busca tarjetas por título o descripción en todos los tableros que la persona ve, con su tablero, columna, estado, prioridad y vencimiento.
• GET /v1/gestion/importaciones Lista las últimas importaciones de clientes y proveedores con su estado y cuántos registros creó, actualizó o tuvieron error.
• GET /v1/administracion/usuarios Lista el equipo de la cuenta: nombre, apodo, tipo de usuario, email y si está habilitado.
• GET /v1/administracion/notificaciones Lista los avisos de quien pregunta en la cuenta: los sin leer o todos.
• GET /v1/administracion/perfiles Lista los tipos de usuario de la cuenta con cuántas personas tiene cada uno y su alcance.
• GET /v1/administracion/actividad Busca en la actividad de la cuenta quién hizo qué, sobre qué y cuándo.
• GET /v1/configuracion/archivos Busca imágenes o documentos subidos a la cuenta por nombre.
• GET /v1/configuracion/dominios Lista los dominios de la cuenta con su estado, cuál es el principal, el certificado y el vencimiento.
• GET /v1/configuracion/casillas Lista las casillas de correo con el dominio de la cuenta, con su responsable, espacio y estado.
• GET /v1/inmobiliaria/ventas Lista las propiedades en venta con código, estado, precio, zona y si están publicadas; filtra por texto, estado y fichas incompletas.
• GET /v1/inmobiliaria/alquileres Lista las propiedades en alquiler con código, estado, precio, zona y si están publicadas; filtra por texto, estado y fichas incompletas.
• GET /v1/inmobiliaria/consultas Lista las consultas por propiedades: las de hoy, las abiertas o por estado, con la persona, la propiedad, el canal, el asesor y si está demorada.
• GET /v1/inmobiliaria/interesados Lista quién busca qué: cada búsqueda activa con la persona, lo que busca y cuántas propiedades nuevas coinciden.
• GET /v1/inmobiliaria/emprendimientos Lista los emprendimientos con su estado de obra, avance, entrega, unidades disponibles y precio desde.
• GET /v1/bandeja/conversaciones/sin-contestar Lista las conversaciones de WhatsApp que esperan respuesta en las líneas que la persona ve, con el contacto, la línea, quién la tiene y el último mensaje.
• GET /v1/bandeja/respuestas Busca entre las respuestas rápidas que la persona ve (las compartidas y las suyas) por atajo, título o texto, para partir de ellas al preparar un borrador.
• GET /v1/tienda/productos Lista los productos del catálogo con su categoría, marca, precio, stock total y si se ven en el sitio; filtra por texto (título, SKU o código de barras), categoría, marca, ocultos y archivados.
• GET /v1/tienda/categorias Lista las categorías y subcategorías del catálogo con su id, su tipo (de productos o de servicios), si están visibles y cuántos productos tienen.
• GET /v1/tienda/marcas Lista las marcas del catálogo con su id, si están visibles y cuántos productos tienen.
• GET /v1/tienda/depositos Lista los depósitos con su id, si están disponibles, cuál es el del sitio y cuántos productos tienen stock ahí.
• GET /v1/tienda/stock/movimientos Lista el libro de stock, del movimiento más nuevo al más viejo: producto, depósito, tipo, cantidad, stock anterior y nuevo, motivo y quién lo hizo; filtra por texto y por fechas.
• GET /v1/tienda/pedidos Lista los pedidos, del más nuevo al más viejo, con su código, cliente, total y los tres estados (pedido, pago y entrega); filtra por texto (código o cliente), por cada estado y por canal.
• GET /v1/alquileres/contratos Lista los contratos de alquiler, del más nuevo al más viejo, con el inmueble, el inquilino titular, el estado, las fechas, el alquiler vigente y la deuda vencida; filtra por estado, por texto y por los que vencen en 60 días.
• GET /v1/alquileres/contratos/{id}/mensualidades Lista las mensualidades de un contrato, de la más vieja a la más nueva, con su vencimiento, total, pagado, saldo, punitorios al día y estado.
• GET /v1/alquileres/mensualidades Lista las mensualidades de un mes de todos los contratos, con el inquilino, el inmueble, el saldo y los punitorios al día; filtra por estado y por texto.
• GET /v1/alquileres/pagos Lista los pagos de alquiler registrados entre dos fechas, del más nuevo al más viejo, con el recibo, el contrato, el inquilino, el medio y el importe.
• GET /v1/alquileres/morosos Lista los contratos con mensualidades vencidas pasados los días de gracia: inquilino, inmueble, cuántos períodos debe y desde cuándo, capital, punitorios al día, último pago y en qué está la gestión.
• GET /v1/turnos/servicios Lista los servicios para los que se puede cargar un turno, con su id y cuántas sesiones trae cada uno.
• GET /v1/turnos/sucursales Lista las sucursales de la cuenta con su id, la principal primero.
• GET /v1/turnos/profesionales Lista los profesionales que atienden turnos, con su id y si están activos.
• GET /v1/turnos/programaciones Lista las programaciones (las agendas): el servicio y la sucursal, entre qué fechas y horas se atiende, qué días, cuánto dura cada turno, el cupo y los profesionales asignados.
• GET /v1/turnos/disponibilidad Consulta los horarios de un servicio en una sucursal y un día: cada uno con su franjaId, la hora, cuántos lugares le quedan y qué profesionales están libres.
• GET /v1/turnos/sesiones Lista las sesiones de los turnos, por horario (las que todavía no tienen horario van primero), con el cliente, el servicio, el profesional, el estado y qué se puede hacer con cada una; filtra por fechas, estado, servicio, sucursal, profesional y texto.