API

La API está basada en REST y usa HTTP response codes para indicar errores. Todas las respuestas de la API serán en formato JSON, incluyendo los errores.

La API funcionará con cualquier programa que tenga una librería HTTP, como cURL. También puede ser utilizada directamente desde cualquier browser.

Los clientes pueden enviar peticiones a través de HTTPS protegiendo así aún más el flujo de información.

API Endpoint

Las llamadas a la API siempre deberán ser apuntadas al siguiente endpoint. A partir de ese punto variarán por versión y recurso a consumir.

https://api.surveykiwi.com

Auth

Antes de poder hacer uso de la API deberás autenticarte con tus llaves de acceso (API_KEY y API_SECRET) que encontrarás o podrás generar en la sección "Mi Cuenta". Si ya las generaste aparecerán en los ejemplos pero sólo tú podrás verlas.

Como resultado obtendrás un access_token que te servirá para realizar llamadas a la API. Puedes utilizar este token mientras sea válido y no haya expirado, caso contrario deberás solicitar otro.

Estas llaves son privadas y únicas y no deben ser compartidas con nadie ni expuestas en códigos client-side.

Returns

Devuelve un objeto con el tipo de token, el token en sí y un valor numérico que indica, en segundos, la vida útil del token.

curl -X POST https://api.surveykiwi.com/oAuth2/token \
    -d grant_type=Client_Credentials \
    -d client_id=API_KEY \
    -d client_secret=API_SECRET
{
    "token_type": "Bearer",
    "expires_in": 900,
    "access_token": "[ACCESS_TOKEN]",
    "refresh_token": "[REFRESH_TOKEN]"
}

Errores

Utilizamos códigos de respuesta HTTP para indicar que una petición a la API fue exitosa o no.

Por lo general códigos en el rango de 2xx indican éxito en la consulta, mientras que códigos en el rango de 4xx indican que algo falló con la información requerida (por ejemplo: falta de algún parámetro, parámetros incorrectos, etc.), y finalmente códigos del tipo 5xx refieren a fallas en el servidor.

Atributos
  • error

    El tipo de error. Puede ser: invalid_token, method_exception, validation_exception, Unauthorized, not_found, internal_server_error, service_unavailable,

  • error_description

    Es la descripción del error en formato amigable

Códigos de respuesta HTTP

200 - OK Todo funcionó de acuerdo a lo esperado.
400 - Bad Request La petición no fue aceptada, posiblemente por fallas en la validación de los parámetros enviados (falta de datos o datos equivocados).
401 - Unauthorized Las llaves de acceso no son correctas o estás queriendo acceder a información restringida.
404 - Not Found El recurso no existe.
405 - Method Not Allowed El método (GET, POST, PUT, DELETE) no está permitido para esta petición.
500, 502, 503, 504 - Server Errors Algo funcionó mal en los servidores.

Errores

Tipos
invalid_token The access token provided is expired, revoked, malformed, or invalid for other reasons.
method_exception El método utilizado no está permitido
validation_exception Esta [pregunta|campaña|etc] no te pertenece, Parámetro desconocido, etc.
Unauthorized No estás autorizado para realizar esta acción.
not_found Recurso no econtrado.
internal_server_error Hubo un problema en el servidor
service_unavailable El servicio no está disponible por el momento.

Paginado

Todos los recursos que devuelven una lista de objetos pueden ser paginados.

Utiliza dos parámetros, offset y limit, para dar la posibilidad de paginar resultados.

Argumentos
  • limit opcional, default es 10

    Límite en el número de objetos a ser devueltos, entre 1 y 100.

  • offset opcional, default es 0

    Número que representa a partir de qué posición van a ser devueltos los resultados.

curl -G https://api.surveykiwi.com/v1.0/campaign/list \
    -d access_token=[ACCESS_TOKEN] \
    -d offset=0 \
    -d limit=2
[
         
]

Campaign

Con este recurso podrás hacer consultas para obtener una lista de tus encuestas disponibles y también la lista de respuestas de cada encuesta.

Lista de encuestas

Podrás consultar todas tus encuestas filtrando por diferentes parámetros.

Argumentos
  • access_token obligatorio

    Token obtenido en /oAuth2/token

  • show_questions opcional, default es 0

    Define si quieres que la respuesta incluya la lista de preguntas asociadas a la encuesta. 0 o 1

  • show_options opcional, default es 0

    Define si quieres que la respuesta incluya la lista de opciones asociadas a cada pregunta de la encuesta. 0 o 1

  • offset opcional, default es 0

    EL número de la primer respuesta que deseas.

  • limit opcional, default es 10

    Limita la cantidad de respuestas, entre 1 y 100.

  • order_by[] opcional, default es null

    Regla para ordenar los resultados. Variable+ASC|DESC separados por coma.

  • where[] opcional, default es null

    Regla para filtrar resultados. Formato JSON. Las variables del JSON son type, var, operator y val. La variable type admite como valores posibles default y sirve para definir dentro de qué entorno buscar el valor de val. La variable var admite como valores posibles la mayoría de las variables del objeto dentro del entorno definido por type. La variable operator admite como valores posibles operadores de comparación como "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. La variable val admite como valores cualquier dato que quieras.

Returns

Devuelve una lista con objetos. Cada uno contiene la información de una encuesta, sus preguntas y opciones.

GET https://api.surveykiwi.com/v1.0/campaign/list
curl -G https://api.surveykiwi.com/v1.0/campaign/list \
    -d access_token=[ACCESS_TOKEN] \
    -d show_questions=1 \
    -d show_options=1 \
    -d offset=0 \
    -d limit=2 \
    -d order_by[]=created_at,DESC \
    -d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2020-12-05T14:50:28-0300"}'
[
    
]

Respuestas de una encuesta

Podrás consultar las respuestas de una campaña en particular.

Argumentos
  • access_token obligatorio

    Token obtenido en /oAuth2/token

  • campaign_url obligatorio

    "URL name" única de la campaña. ej: satisfaccion

  • status opcional, default es "all"

    Permite active, pending, all. Elige si quieres filtrar las respuestas de usuarios que terminaron la encuesta o no.

  • answers opcional, default es "show"

    Permite hide show. Elige si quieres mostras las respuestas de un encuestado.

  • offset opcional, default es 0

    EL número de la primer respuesta que deseas.

  • limit opcional, default es 10

    Limita la cantidad de respuestas, entre 1 y 100.

  • order_by[] opcional, default es null

    Regla para ordenar los resultados. Variable+ASC|DESC separados por coma.

  • where[] opcional, default es null

    Regla para filtrar resultados. Formato JSON. Las variables del JSON son type, var, operator y val. La variable type admite como valores posibles hiddenfields, participant y default y sirve para definir dentro de qué entorno buscar el valor de val. La variable var admite como valores posibles la mayoría de las variables del objeto dentro del entorno definido por type. La variable operator admite como valores posibles operadores de comparación como "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. La variable val admite como valores cualquier dato que quieras.

Returns

Devuelve una lista con objetos. Cada uno contiene la información recolectada cuando un usuario responde una encuesta. Datos del encuestado, hiddenfields, lista de preguntas con las respuestas elegidas, etc.

GET https://api.surveykiwi.com/v1.0/campaign/answers
curl -G https://api.surveykiwi.com/v1.0/campaign/answers \
    -d access_token=[ACCESS_TOKEN] \
    -d campaign_url= \
    -d status=active \
    -d offset=0 \
    -d limit=2 \
    -d order_by[]=created_at,DESC \
    -d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2020-12-05T14:50:28-0300"}'
[
]

Question

Con este recurso podrás obtener un objeto único con la información de una pregunta específica.

Detalles de una pregunta

Obtendrás los detalles de una pregunta específica pasando como parámetro el ID.

Argumentos
  • access_token obligatorio

    Token obtenido en /oAuth2/token

  • id obligatorio

    ID único de la pregunta

Returns

Devuelve un objeto con toda la información disponible de una pregunta en particular y sus opciones.

GET https://api.surveykiwi.com/v1.0/question
curl -G https://api.surveykiwi.com/v1.0/question \
    -d access_token=[ACCESS_TOKEN] \
    -d id=
{
        "id": "",
        "question": "",
        "description": null,
        "type": "",
        "max_length": null,
        "mandatory": null,
        "position": null,
        "picture": null,
        "random": null,
        "range_from": null,
        "range_to": null,
        "other": null,
        "alerts": null,
        "alert_words": null,
        "options": [
        ]
    }

Webhooks

Usa los webhooks para ser notificado cuando un usuario responda una encuesta en tiempo real.

las APIs pueden enviar notificaciones a tu aplicación cuando un usuario responda cualquiera de tus encuestas en el momento en que las responde.

Esto es muy útil para los casos en que necesites alimentar tu propia base de datos con las respuestas de tus usuarios sin la necesidad de recurrir a las APIs para obtener esta información.

Puedes registrar tus URLs a las que se enviarán notificaciones apenas suceda una acción.

Se enviará una notificación a esta URL vía HTTP POST con toda la información obtenida en la respuesta de un usuario.

Cuando usar Webhooks

Los webhooks sólo son necesarios para obtener información detrás de escena en tiempo real.

Puedes utilizar webhooks para:

  • Guardar las respuestas de los usuarios en el momento en que estos responden.
  • Enviar un email a tus usuarios apenas responden una encuesta.
  • Ser notificado mediante PUSH en tu celular a través de aplicaciones de terceros.
  • Generar reportes propios en tu aplicación.

Configuration

Puedes configurar tus webhooks en la sección APIs de tu dashboard.

En el bloque Webhooks haz click en "Crear Webhook". Ingresa la URLs hacia donde quieres que se envien las notificaciones y guarda los cambios.

Puedes enviar notificaciones de prueba para configurar el endpoint de tu lado.

Es posible ingresar cualquier URL que quieras, pero es recomendable que tus endpoints sean dedicados para recibir información de las APIs.

Recibiendo una notificación de Webhook

Crear un webhoook endpoint en tu servidor no es diferente a crear cualquier página de tu sitio web.

Con PHP deberías crear un nuevo archivo .php destinado a recibir la información y proporcionar una respuesta.

Los datos enviados por webhook estarán en formato JSON. Deberás procesarlo y devolver un status 200 para notificar que el mensaje fue recibido con éxito.


Respondiendo al webhook

Para notificarnos de que tu servidor recibió la información enviada, tu endpoint deberá responder un status 200 (HTTP status code)

Todos los status fuera del rango 200, incluyendo los códigos 3xx, indicará que el envío falló y que no recibiste la información enviada.

Esto significa que una redirección o una respuesta del tipo "Not Modified" será interpretada como un fallo.

Se ignorará cualquier otra información enviada en el header o en el body de la respuesta.

En tu dashboard, en la sección APIs podrás obtener información y chequear el historial de eventos enviados a tus endpoints.

Comprobando las firmas del Webhook

Se firmarán los webhooks que se envíen a tus endpoints. Se incluirá una firma en el header SK-Signature por cada envío. Esto te ayudará a validar que el envío de datos haya salido de la plataforma y no por terceros.

Antes de poder validar las firmas deberás tomar nota de ellas en el panel donde se encuentran tus webhooks.

Previniendo ataques de reenvíos.

Un ataque de reenvíos es cuando interceptan un envío válido con su correspondiente firma y la reenvían. Para prevenir estos ataques se agrega un timestamp en el header SK-Signature. De esta manera podrás comprobar si la firma es válida al afirmar que no ha pasado cierto tiempo comparado con el timestamp enviado.

Verificando Firmas.

El header SK-Signature contiene un timestamp y una firma. El timestamp está prefijado por un t=, y la firma está prefijada por un esquema. El esquema comienza con una v seguida por un número entero. Por ahora sólo será válido el número 1, por lo que el esquema válido será v1

SK-Signature: \
    t=1539794213,
    v1=720c0195d5fc0d6dc06accf258d3aaf6165a729efbda7f3628d54803576e2c9e