Saltar a contenido

API: Form Responses

M: Listar respuestas de formularios

Límite de Tasa de Peticiones

Máximo de 10 peticiones por IP en 5 minutos

HTTP GET:
https://<hostname>/api/form-responses
URL PARAMETERS:
Nombre Tipo Requerido Descripción
start_date Fecha de inicio Texto si Fecha en formato YYYY-MM-DD
end_date Fecha de fin Texto si Fecha en formato YYYY-MM-DD
form_id Id de formulario Numérico si Id del formulario del que se quiere obtener las respuestas.
start_time Hora de inicio Texto no Hora en formato HH:MM:SS
end_time Hora de fin Texto no Hora en formato HH:MM:SS
user_ids Lista de usuarios Lista de números no Listado de ids de usuarios para filtrar las respuestas
job_id Id de tarea Numérico no Permite filtrar las respuestas relacionadas a una tarea
job_remote_id Id personalizado de tarea Texto no Permite filtrar las respuestas relacionadas a una tarea usando el id que le dio el cliente a la tarea
OUTPUT:

Json con los campos:

EJEMPLO CON CURL:
$ curl -u <api_key>:<password>
     -X GET
     https://<hostname>/api/form-responses?start_date=2021-01-01&end_date=2021-01-15&form_id=1483
RESPUESTA:
{
  "success": true,
  "form": {
    "title": "Revisión semanal",
    "questions": [
      {
        "id": 1,
        "label": "Nombre del supervisor de turno",
        "type": "textbox"
      },
      {
        "id": 2,
        "label": "Hora de última limpieza diaria",
        "type": "timeOfDay"
      },
      {
        "id": 3,
        "label": "Tipo de comercio",
        "type": "picker",
        "options": [
          {
            "id": "alimentos",
            "index": 0,
            "label": "Alimentos"
          },
          {
            "id": "bebidas",
            "index": 1,
            "label": "Bebidas"
          }
        ]
      },
      {
        "id": 4,
        "label": "Artículos promocionales a la vista",
        "type": "checkbox",
        "options": [
                  {
                    "id": "banner-con-logo",
                    "index": 0,
                    "label": "Banner con logo"
                  },
                  {
                    "id": "muestras-de-producto",
                    "index": 1,
                    "label": "Muestras de producto"
                  }
                ]
      },
      {
        "id": 5,
        "label": "Foto del área revisada",
        "type": "takepicture"
      },
      {
        "id": 6,
        "label": "Múltiples fotos de los defectos encontrados",
        "type": "takepicture"
      },
      {
        "id": 7,
        "label": "Firma del supervisor",
        "type": "signature"
      },
      {
        "id": 8,
        "label": "Aspecto visual",
        "type": "rating"
      }
    ]
  },
  "responses": [
    {
      "id": 3759,
      "user_id": "214",
      "date": 1583432858,
      "server_date": 1583432918,
      "gps_epoch": 1583432825,
      "address": "5ta calle, 1ra avenida, Zona 6, Ciudad de Guatemala",
      "lat": "14.6212927",
      "lon": "-90.5146818",
      "driver_id": null,
      "vehicle_id": null,
      "seq": 3,
      "event": {
        "reason": {
          "id": 16809984,
          "label": "Check-in"
        },
        "comment": "Comentario",
        "checkin_guid": "777601d0-e690-4629-beff-7fff89ed1e6d"
      },
      "poi": {
        "id": 522,
        "color": "#00796b",
        "name": "Taco Bell"
      },
      "1": "José García",
      "2": 44820,
      "3": "alimentos",
      "4": [
        "banner-con-logo",
        "muestras-de-producto"
      ],
      "5": [
        {
          "from_gallery": true,
          "epoch_taken": 1583432618,
          "url": "https://gps.example.com/images/photo-1.jpg"
        }
      ],
      "6": [
        {
          "from_gallery": false,
          "epoch_taken": 0,
          "url": "https://gps.example.com/images/photo-2.jpg"
        },
        {
          "from_gallery": false,
          "epoch_taken": 0,
          "url": "https://gps.example.com/images/photo-3.jpg"
        }
      ],
      "7": {
        "url": "https://gps.example.com/images/signature-image.jpg"
      },
      "8": 4
    }
  ]
}

O: Form Data Object

Cada objeto de formulario tiene estos campos:

Campo Descripción
title Nombre del formulario.
questions Contiene una lista de Form Question Data Objects.

O: Form Question Data Object

Cada objeto de pregunta de formulario tiene estos campos:

Campo Descripción
id Id de la pregunta de formulario.
label Texto de la pregunta de formulario.
type Tipo de pregunta. Ver tabla.
options (opcional) Contiene una lista de Form Question Option Data Objects.

type: Tipo de Pregunta

  • takepicture: Foto
  • signature: Firma
  • checkbox: Opción múltiple
  • picker: Opción simple
  • date: Fecha
  • dateTime: Fecha y Hora
  • timeOfDay: Hora
  • rating: Calificación
  • textbox: Texto
  • money: Cantidad de dinero

O: Form Question Option Data Object

Cada objeto de opciones de pregunta de formulario tiene estos campos:

Campo Descripción
id Id de la opción.
index Correlativo.
label Texto de la opción.

O: Form Response Data Object

Cada objeto de respuesta de formulario tiene estos campos:

Campo Descripción
id Id de la respuesta de formulario.
user_id Id del usuario que respondió el formulario.
date Fecha y hora de la respuesta en formato Unix time.
server_date Fecha y hora a la que se recibió la respuesta en el servidor en formato Unix time.
gps_epoch Fecha y hora a la que se obtuvo la posición de GPS reportada en la respuesta en formato Unix time.
address Lugar en el que se respondió el formulario.
lat Latitud en grados decimales.
lon Longitud en grados decimales.
driver_id Id del conductor asociado al usuario que respondió el formulario.
vehicle_id Id del vehículo al que está asignado el conductor o id del celular en el que está registrado el usuario que respondió el formulario.
seq Correlativo de las respuestas de este formulario.
job Objeto con los campos id, title y remote_id de la tarea en la que se respondió el formulario.
event Información del evento que se reportó al llenar este formulario.
poi Objeto con los campos id, color y name (nombre) de la geocerca en la que se respondió el formulario.

Además, para cada pregunta del formulario, habrá un elemento que tenga como nombre, el id de la pregunta y como valor, la respuesta a esa pregunta con formato según el tipo de pregunta de acuerdo a la siguiente tabla:

Tipo de pregunta Tipo o formato de la respuesta
takepicture Objeto con Response Image Data Objects.
signature Objeto con url de la imagen.
checkbox Lista (JSON Array) con los ids de las opciones marcadas.
picker Id de la opción marcada.
date, dateTime, timeOfDay Numérico. En formato Unix time.
rating Numérico. Puntuación elegida de 1 a 5
textbox Texto.
money Numérico.

O: Response Image Data Object

Cada objeto de imagen de respuesta tiene estos campos:

Campo Descripción
url URL de la imagen.
epoch_taken Fecha y hora en la que se tomó la foto en formato Unix time.
from_gallery true si la foto se obtuvo de la galería, false si fue capturada con la cámara al llenar el formulario.