Pagination and response format

Listings

All GET endpoints that return collections support pagination with the following parameters:

Parameter	Type	Default	Description
page	integer	1	Page number, 1-indexed
count	integer	20	Items per page, max 200

Listings return the direct array (no envelope), and pagination info travels in headers:

Header	Description
X-Total-Count	Total items matching the filters (not just this page)

Status codes

Status	When
200 OK	Successful response. Includes both pages with items and empty listings (200 [] if the filter returns no results).

Example

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" }, ... },
  ...
]

To iterate through all pages:

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) {
    // process
  }
  page++;
}

Sorting

Listings sort by default by creationDate descending. Some endpoints accept a sort parameter with specific fields documented per resource (e.g. sort=-movementDate for movements).

Single-resource responses

Endpoints that return a single resource respond with the object directly, no envelope:

GET /v1/clients/1001

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

Field conventions

• Identifiers (id, clientId, receivableAccountId, etc.): int64 integers.
• Tax ID (taxId): always 11 digits, no dashes. The API canonicalizes the value on receive (it accepts dashes and spaces) and always returns this format.
• Currency codes: ISO 4217. Today only ARS.
• Timestamps (creationDate, modificationDate, movementDate): ISO 8601 with offset. E.g. 2026-05-14T10:30:00-03:00.
• Dates without time (issueDate, dueDate): YYYY-MM-DD.
• Amounts: decimal number without thousand separators, dot as the decimal separator. E.g. 45000.50.
• Optional booleans: default false when omitted in POST/PUT.
• Derived fields (computed by the system): returned in GET but ignored if sent on POST/PUT.
• status instead of disabled: resources expose states as enums (ACTIVE, DISABLED, etc.) instead of boolean flags to ease future evolution.

Standard filters

When a resource supports it, the most common filters follow this pattern:

Parameter	Type	Description
ids	int array	List of specific IDs. E.g. ?ids=1,2,3
fromDate	ISO 8601	Filters by creation date >=
toDate	ISO 8601	Filters by creation date <= (inclusive)
status	enum	Specific status
externalId	string	Integrator's external ID