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:

success: boolean
form: json Contiene una lista de Form Data Objects
responses: json Contiene una lista de Form Response Data Objects

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.