Skip to main content

Convenciones

Reglas que aplican de forma transversal a los endpoints de listado y a los formatos de datos.

Paginación

Los listados usan paginación por desplazamiento (limit / offset).
integer
default:"25"
Cuántos elementos devolver. Mínimo 1, máximo 100.
integer
default:"0"
Cuántos elementos omitir desde el inicio. Mínimo 0.
Un valor fuera de rango o no numérico devuelve 400 INVALID_INPUT.
GET /v1/notifications usa 100 como valor por omisión de limit cuando no lo especificas. El resto de los listados usa 25.

Totales

Los listados de pases, escaneos y notificaciones devuelven el conteo en encabezados de respuesta:
Estos encabezados no están expuestos por CORS, por lo que un navegador no puede leerlos. Es una razón más para llamar a la API desde tu servidor y no desde el navegador.

Recorrer todas las páginas


Forma de las respuestas de listado

No todos los listados usan la misma envoltura. Tenlo presente al escribir tu cliente:

Filtros

string
Búsqueda de texto libre. Disponible en pases, escaneos y notificaciones. Lo que busca depende del recurso: identificadores, valores de campos visibles, nombres de lector o el texto del mensaje.
string
Filtra por estado. Es repetible: ?status=active&status=issued devuelve los pases en cualquiera de los dos estados.
Los valores repetidos de un mismo parámetro se combinan con O; parámetros distintos se combinan con Y.

Ordenamiento

string
Campo por el cual ordenar. Los valores permitidos dependen del recurso y se documentan en cada endpoint.
string
default:"desc"
Dirección: asc o desc.

Rangos de fechas

Los listados aceptan pares de límites temporales. Todos usan RFC 3339:
El límite inferior es inclusivo y el superior exclusivo. Si from es posterior a to, la API responde 400 INVALID_INPUT.

Formatos de fecha en las respuestas

Los formatos de fecha no son uniformes en toda la API. Al parsear, usa la tabla siguiente en lugar de asumir RFC 3339 en todas partes.

Valores booleanos en parámetros

Los parámetros booleanos (include_deleted, include_history, include_archived, pass_info) aceptan true, false, 1, 0, t, f. Un valor no reconocido devuelve 400 INVALID_INPUT.

Tamaño de las peticiones

La API no impone un límite explícito al tamaño del cuerpo en /v1. Aun así, mantén las cargas dentro de lo razonable: para altas masivas de pases, usa la importación por archivo del Dashboard en lugar de una única petición gigante.