Las colecciones (GET /customers, GET /documents, etc.) aceptan parámetros en la query string para filtrar y, cuando aplica, paginar resultados.
Filtros de ámbito (obligatorios)
La mayoría de las colecciones operan en el contexto de un negocio (multi-tenant). Por eso casi todas requieren al menos uno de estos parámetros:
| Parámetro | Endpoints donde aplica | Descripción |
|---|---|---|
businessId | /customers, /providers, /carriers, /items, /establishments, /emission-points, /sequences, /documents | Restringe la consulta al negocio indicado. |
userId | /businesses | Restringe a los negocios del usuario indicado. |
Paginación
Cuando el endpoint soporta paginación, acepta los parámetros estándar:
| Parámetro | Tipo | Por defecto | Descripción |
|---|---|---|---|
page | int | 1 | Número de página. |
perPage / limit | int | 25 | Tamaño de página. Máximo: 100 (por encima devuelve 422). |
La respuesta de una colección paginable siempre incluye metadatos de paginación:
{
"data": [ /* ... items ... */ ],
"meta": {
"currentPage": 1,
"perPage": 25,
"total": 132,
"lastPage": 6
}
}Recorrer una colección completa se ve así:
page=1
while :; do
body=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE/documents?businessId=$BUSINESS_ID&page=$page&perPage=100")
echo "$body" | jq -c '.data[]'
last=$(echo "$body" | jq '.meta.lastPage')
[ "$page" -ge "$last" ] && break
page=$((page + 1))
doneFiltros por recurso
| Endpoint | Parámetros |
|---|---|
/documents | search, number, accessKey, documentTypeCode, documentStateAcronym, establishmentId, emissionPointId, entityId, dateFrom, dateTo (formato Y-m-d) |
/customers, /providers, /carriers | search, identificationTypeId, ids |
/items | search, itemTypeId, ids |
search es una búsqueda parcial: en comprobantes cubre número, clave de acceso, razón social e identificación del cliente; en contactos cubre identificación, razón social y correo; en productos cubre nombre, código y código auxiliar. ids acepta una lista separada por comas y devuelve únicamente esos registros.
Ordenamiento
Donde está soportado, usa los parámetros:
| Parámetro | Valores | Ejemplo |
|---|---|---|
sortBy | Uno de los campos permitidos para el recurso (ver tabla siguiente). | ?sortBy=date |
sortDir | asc | desc | ?sortDir=desc |
| Endpoint | Valores admitidos en sortBy | Por defecto |
|---|---|---|
/documents | id, date, number, subtotal, total, createdAt, documentType, documentState, entity | date desc |
/customers, /providers, /carriers | id, identification, businessName, email, cellphone, address, createdAt | businessName asc |
/items | id, code, auxCode, name, unitPrice, itemType, tax, createdAt | name asc |
Búsqueda por identificación
Para clientes, proveedores y transportistas existe un endpoint dedicado de búsqueda por número de identificación:
GET /customers/search/{identification}GET /providers/search/{identification}GET /carriers/search/{identification}
Devuelve la primera coincidencia que exista para tu cuenta — útil para autocompletar datos al emitir un comprobante.