Paginación y formato de respuestas

Listados

Todos los endpoints GET que devuelven colecciones soportan paginación con los siguientes parámetros:

Parámetro	Tipo	Default	Descripción
page	integer	1	Número de página, 1-indexed
count	integer	20	Cantidad de items por página, máximo 200

Los listados devuelven el array directo (sin envelope), y la información de paginación viaja en headers:

Header	Descripción
X-Total-Count	Total de items que matchean los filtros (no solo los de esta página)

Códigos de estado

Status	Cuándo
200 OK	Respuesta exitosa. Incluye tanto páginas con items como listados vacíos (200 [] si el filtro no devuelve resultados).

Ejemplo

GET /v1/clients?taxId=30999999999&page=1&count=20

200 OK
Content-Type: application/json
X-Total-Count: 47

[
  { "id": 1001, "businessName": "Kiosco Central", "taxId": "30999999999", ... },
  { "id": 1002, "businessName": "Kiosco Central", "taxId": "30999999999", "branch": { "externalCode": "02" }, ... },
  ...
]

Para iterar todas las páginas:

let page = 1;
const count = 100;
let total = Infinity;

while ((page - 1) * count < total) {
  const res = await fetch(`/v1/clients?page=${page}&count=${count}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  total = parseInt(res.headers.get('X-Total-Count'), 10);
  const items = await res.json();
  for (const item of items) {
    // procesar
  }
  page++;
}

Ordenamiento

Los listados ordenan por defecto por creationDate descendente. Algunos endpoints aceptan un parámetro sort con campos específicos documentados en cada recurso (ej. sort=-movementDate para movimientos).

Respuestas individuales

Los endpoints que devuelven un único recurso responden con el objeto directo, sin envelope:

GET /v1/clients/1001

200 OK
{
  "id": 1001,
  "businessName": "Kiosco Central",
  "taxId": "30999999999",
  ...
}

Convenciones de campos

• Identificadores (id, clientId, receivableAccountId, etc.): enteros int64.
• Identificación fiscal (taxId): siempre 11 dígitos sin guiones. La API canoniza el valor al recibirlo (acepta guiones y espacios) y lo devuelve siempre en este formato.
• Códigos de moneda: ISO 4217. Hoy solo ARS.
• Timestamps (creationDate, modificationDate, movementDate): ISO 8601 con offset. Ej: 2026-05-14T10:30:00-03:00.
• Fechas sin hora (issueDate, dueDate): YYYY-MM-DD.
• Montos: número decimal sin separadores de miles, punto como separador decimal. Ej: 45000.50.
• Booleanos opcionales: por defecto false cuando se omiten en POST/PUT.
• Campos derivados (calculados por el sistema): se devuelven en GET pero se ignoran si se mandan en POST/PUT.
• status en lugar de disabled: los recursos exponen estados como enums (ACTIVE, DISABLED, etc.) en lugar de flags booleanas para facilitar evolución futura.

Filtros estándar

Cuando un recurso lo soporta, los filtros más usados siguen este patrón:

Parámetro	Tipo	Descripción
ids	array de int	Lista de IDs específicos. Ej: ?ids=1,2,3
fromDate	ISO 8601	Filtra por fecha de creación >=
toDate	ISO 8601	Filtra por fecha de creación <= (inclusive)
status	enum	Estado específico
externalId	string	ID externo del integrador