Integración

Consultas

Leer es el 90 % de lo que hace una integración. Hay dos formas: traer registros tal cual y buscar con condiciones.

Traer registros de un recurso#

GET {BASE}/layouts/{recurso}/records?_limit=100&_offset=1
Authorization: Bearer {token}

Parámetro	Qué hace
`_limit`	Cuántos registros devuelve
`_offset`	Desde cuál empieza. Empieza en 1, no en 0

La respuesta trae los datos en response.data, y cada elemento lleva:

{
  "fieldData": { "CODIGO": "1", "NOMBRE": "Cliente de ejemplo" },
  "recordId": "1234",
  "modId": "7"
}

recordId no es el identificador del registro

recordId es un número interno de la sesión y puede cambiar. El identificador estable de cada registro es su campo ID, que es el que debes guardar en tu sistema para volver a encontrarlo. recordId solo se usa como dirección inmediata para modificar el registro que acabas de leer.

Buscar con condiciones#

POST {BASE}/layouts/{recurso}/_find
Authorization: Bearer {token}
Content-Type: application/json

{
  "query": [ { "ID_EMPRESA": "==5B7C…", "VIGENTE": "1" } ],
  "limit": 200,
  "offset": 1,
  "sort": [ { "fieldName": "CODIGO", "sortOrder": "ascend" } ]
}

Cada objeto dentro de query es un conjunto de condiciones que se cumplen a la vez (Y). Varios objetos en la lista se combinan como O:

"query": [
  { "ID_EMPRESA": "==5B7C…", "ID_ESTADO": "==A1…" },
  { "ID_EMPRESA": "==5B7C…", "ID_ESTADO": "==B2…" }
]

Operadores#

Escribes	Encuentra
`==valor`	Exactamente ese valor
`valor`	Que empiece por ese valor
`valor`	Que lo contenga
`>`, `>=`, `<`, `<=`	Comparaciones, también con fechas
`01/01/2026...31/03/2026`	Un rango
`=`	El campo vacío
`*`	El campo con cualquier contenido

Para excluir, se añade "omit": "true" a ese bloque de condiciones.

Las fechas van en MM/DD/YYYY

Aunque tu solución esté en español y las pantallas muestren día/mes/año, la API espera y devuelve mes/día/año. Es el error más frecuente al integrar: 03/04 se interpreta como 4 de marzo, no como 3 de abril, y el resultado parece correcto hasta que alguien revisa un informe.

Filtrar siempre por empresa#

Tu solución puede tener varias empresas, y casi todos los recursos llevan ID_EMPRESA.

Sin ese filtro, tu integración mezcla empresas

Una consulta sin ID_EMPRESA devuelve registros de todas. Filtrar es responsabilidad de quien llama, no del servidor. Es el fallo más caro de una integración multiempresa, y no da ningún error: simplemente devuelve de más.

El identificador de cada empresa se obtiene del recurso API_EMPRESAS.

Contar sin descargar#

Para saber cuántos registros cumplen una condición sin traértelos:

{ "query": [ { "ID_EMPRESA": "==5B7C…" } ], "limit": 1 }

y lees response.dataInfo.foundCount.

Con ficheros adjuntos, contar así no es una optimización: es la diferencia

Si el recurso incluye documentos o imágenes, descargar el conjunto entero para contarlo puede significar cientos de megas. Pedir limit: 1 y leer el contador cuesta una llamada.

Leer un registro concreto#

GET {BASE}/layouts/{recurso}/records/{recordId}

Si lo que tienes es el ID estable, búscalo con _find y {"ID": "==…"}.

Paginar#

Con _limit y _offset, o con limit y offset dentro del _find. El patrón habitual: pedir de 100 en 100 hasta que la respuesta traiga menos registros que el límite.

No pidas diez mil de golpe

Una petición enorme es más frágil que diez pequeñas: si se corta, se pierde entera, y mientras tanto tiene ocupado al servidor.

Saber qué campos tiene un recurso#

GET {BASE}/layouts/{recurso}

Devuelve la lista de campos con su tipo. Es lo que conviene consultar antes de escribir, y no dar por hecho lo que había el año pasado.

Si la lista de campos viene vacía, no es un recurso de datos

Algunos nombres corresponden a recursos internos sin campos publicados. Escribir contra ellos no da error: crea registros vacíos e inservibles. Comprueba siempre que el recurso expone campos antes de usarlo.

Listar los recursos disponibles#

GET {BASE}/layouts

Devuelve los nombres publicados para tu solución. La lista comentada por familias está en Catálogo de recursos.

Qué viene después#

Cuando ya sabes leer, toca escribir —con sus reglas— y conocer cómo se informan los errores.