Call API
Call API permite que su encuesta recupere datos de un servicio web externo y use la respuesta para llenar campos o validar respuestas.
La función Call API permite que un campo de la encuesta realice una solicitud HTTP a un servicio externo y use la respuesta para llenar un valor calculado o validar la entrada del usuario. Esto habilita búsquedas en tiempo real, verificación de ID, búsquedas de código de barras y cualquier otra verificación del lado del servidor durante la recopilación de datos.
Hay dos funciones:
callapi()— obtiene un valor de una API y lo almacena en un campocalculateotextcallapi-verify()— llama a una API y bloquea el progreso si la respuesta no coincide con el valor esperado (usado enconstraint)
callapi() — Obtener y almacenar una respuesta de API
Sintaxis
Coloque callapi() en la columna calculation de un campo calculate o text:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parámetros
| # | Parámetro | Descripción |
|---|---|---|
| 1 | method | Método HTTP: 'GET' o 'POST' |
| 2 | url | URL del endpoint de la API |
| 3 | allowed_auto | 1 para llamar automáticamente cuando se llega al campo; 0 para requerir un botón de activación manual |
| 4 | max_retry | Número máximo de intentos de reintento en caso de fallo |
| 5 | no_overwrite | 1 para conservar el valor existente si el campo ya tiene uno; 0 para sobrescribir siempre |
| 6 | extract_expr | Expresión JSONPath para extraer el valor deseado de la respuesta (p. ej., $.data.name) |
| 7 | timeout | Tiempo de espera de la solicitud en milisegundos |
| 8 | lifetime | Cuánto tiempo (ms) permanece válida la respuesta en caché antes de volver a obtenerla |
| 9 | response_q | Nombre de un campo para almacenar el código de respuesta HTTP sin procesar (p. ej., ${response_status}) |
| 10 | call_type | (Opcional) Modo de llamada especial: 'lazy-upload' o 'lazy-upload-multiple' |
| 11 | post_body | (Opcional) Cadena del cuerpo POST. Haga referencia a campos del formulario con ##fieldname## |
Ejemplo: Solicitud GET para buscar un hogar por ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID del hogar | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Hogar: ${hh_name} |
Ejemplo: Solicitud POST con un cuerpo JSON
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
En el post_body, use ##fieldname## para inyectar el valor actual de cualquier campo del formulario.
Apariencia: callapi
Agregue callapi a la columna appearance del campo para habilitar la integración de llamada a API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Cuando allowed_auto es 0, rtSurvey muestra un botón “Obtener” que el encuestador toca manualmente.
callapi-verify() — Validar un valor contra una API
callapi-verify() bloquea el envío de un campo hasta que una API confirme que el valor ingresado es válido. Úselo en la columna constraint.
Sintaxis
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parámetros
| # | Parámetro | Descripción |
|---|---|---|
| 1 | method | Método HTTP: 'GET' o 'POST' |
| 2 | url | Endpoint de la API de verificación |
| 3 | extract_expr | JSONPath para extraer el valor esperado de la respuesta |
| 4 | match_expr | Expresión que compara el valor extraído con el valor del campo (p. ej., $.status = 'valid') |
| 5 | timeout | Tiempo de espera de la solicitud en milisegundos |
| 6 | constraint_mode | 'soft' para solo advertencia; 'hard' para bloquear la progresión |
| 7 | post_body | (Opcional) Cuerpo POST con sustituciones ##fieldname## |
| 8 | message | (Opcional) Mensaje de error. Admite múltiples idiomas: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Ejemplo: Verificar un código de barras contra un registro de activos
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Escanee el código de barras del activo | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Activo no encontrado en el registro |
Apariencia: callapi-verify(...)
La columna appearance en un campo con callapi-verify() en constraint debe contener callapi-verify(params) o callapi-verify(dynamicParams) para indicar a rtSurvey que este campo usa verificación de API.
Uso de datos de la API de la aplicación junto con callapi
Combine callapi() con pulldata('app-api', 'user.token') para inyectar el token del usuario autenticado en su solicitud de API:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Mejores prácticas
- Siempre establezca un
timeoutrazonable (5000–15000 ms) — no use 0 ni valores muy altos. - Establezca
allowed_auto=0para verificaciones que el encuestador debe activar conscientemente (p. ej., verificaciones de ID). - Establezca
no_overwrite=1cuando el campo pueda editarse más tarde y no desee que la nueva obtención sobrescriba las correcciones manuales. - Use
extract_exprcon un JSONPath específico en lugar de depender del texto de respuesta sin procesar. - Pruebe las llamadas a API en modo sin conexión — callapi fallará de forma controlada y mostrará un error, pero el formulario aún debe poder completarse para campos no críticos.
Limitaciones
- Requiere conectividad de red en el momento de la llamada — las llamadas fallarán cuando el dispositivo esté sin conexión.
- Las respuestas de la API deben ser JSON — las respuestas XML o de texto plano requieren análisis adicional.
- Alta frecuencia de llamadas (p. ej., una llamada a API por instancia de repetición) puede ralentizar la navegación del formulario.