La API de Skypunch permite integrar una boleta electoral por completo en otro sitio web o utilizar únicamente el inicio de sesión único (SSO) durante la autenticación. Ambos modelos, además de la opción de alojar todo en el sitio web de Skypunch, se describen en los diagramas de flujo de los modelos electorales.

Autenticación

La API utiliza un token de API para la autenticación. Los clientes pueden obtenerlo siguiendo estos pasos:

  1. Inicie sesión en My Account.
  2. Haga clic en la pestaña My Info de la pantalla de bienvenida.
  3. Click My account profile .
  4. Busque el token de API en la parte superior del perfil.

Cómo agregar los encabezados necesarios

Cada solicitud debe incluir los dos encabezados siguientes:

  1. User-Agent
    El valor del encabezado User-Agent no importa; puede utilizar el que prefiera. Sin embargo, es obligatorio porque las listas de verificación de ciberseguridad utilizadas para auditar el sistema de Skypunch exigen que cada solicitud REST incluya este encabezado.
  2. Content-Type

    El valor del encabezado Content-Type debe ser uno de los siguientes:

    1. application/json
    2. application/x-www-form-urlencoded

    Por lo general, los encabezados Content-Type indican a un endpoint RESTful el formato de los datos que debe devolver en la respuesta. Esto no ocurre con los endpoints de Skypunch. Por lo tanto, el valor específico de Content-Type no es determinante, siempre que sea uno de los valores permitidos que aparecen arriba. No obstante, los marcos de ciberseguridad exigen que cada endpoint REST reciba un valor aceptable para este encabezado, por lo que debe incluirse.

Consejos para desarrolladores

Las herramientas de documentación populares, como Swagger, no son las más adecuadas para la API de Skypunch Technology porque, a diferencia de muchas API, estos servicios —o, al menos, los tres servicios de boletas— no están diseñados principalmente para realizar operaciones CRUD (crear, leer, actualizar y eliminar datos). En cambio, el recurso ballot de la API y sus tres subrecursos (step_one, step_two y step_three) implementan la lógica de la aplicación y el flujo del usuario durante el proceso de:

  1. visualizar una boleta electoral.
  2. confirmar las selecciones realizadas por el votante en esa boleta.
  3. guardar la boleta en el sistema.

Por este motivo, las representaciones step_one y step_two del recurso ballot devuelven HTML como respuesta. Este HTML está listo para mostrarse en un navegador web y se le pueden aplicar estilos para que coincida con la apariencia del sitio que lo integra, como se explica en la sección Cómo dar estilo a la boleta.

Cómo dar estilo a la boleta

Si integra una boleta en su propio sitio web mediante los métodos Get Ballot step one y Get Ballot step two que se describen a continuación, esta no tendrá estilos aplicados de forma predeterminada y, por lo tanto, su apariencia será básica. Para aplicar los mismos estilos que se utilizan cuando la boleta está alojada en el sitio de Skypunch Technology, siga estos pasos:

  1. Inicie sesión en My Account.
  2. Haga clic en la pestaña Preview ballot button associated with your election. (If that button does not display, you may also click the Submit a paper ballot .)
  3. Cuando aparezca la boleta, consulte el código fuente de esa página.
  4. Copie la hoja de estilos de la sección HEAD de esa página y péguela en cada una de las páginas de sus boletas.

Al copiar la hoja de estilos de una boleta vigente del sitio de Skypunch Technology, se asegura de utilizar los estilos más recientes disponibles. Después de copiarla en las páginas de sus boletas, puede dejarla tal como está o modificar los estilos para que la boleta se integre perfectamente con la apariencia de su sitio.

Cómo evitar conflictos de estilos

Algunos estilos pueden entrar en conflicto con los que ya utiliza su sitio. Sin embargo, como la salida de los métodos step_one y step_two debe incluirse dentro de una etiqueta <FORM>, se recomienda agregar a esa etiqueta un atributo id con un valor como ballot. Por ejemplo:

<form method="post" id="ballot">

Luego, anteponga #ballot a las reglas CSS que generen conflictos. Por ejemplo:

#ballot header > div > img:first-child {width:570px; height:95px; vertical-align:text-bottom;}

Esto convierte el selector de esa regla en un selector descendiente, lo que garantiza que la regla se aplique únicamente a la boleta y no a otros elementos.

Los métodos de la API

  • Los valores entre llaves son variables proporcionadas por la aplicación que utiliza la API.
  • El ID de elección es el identificador que Skypunch Technology genera para cada elección. Este valor aparece en su cuenta de Skypunch Technology, junto a la elección correspondiente, o puede obtenerse mediante programación desde el endpoint /elections.

Descripción: Obtiene datos generales de las elecciones, útiles para mostrar un anuncio sobre una próxima elección o la fecha límite para votar en una elección en curso. También incluye los ID de elección necesarios para crear endpoints de otros recursos.

Método HTTP: GET

Endpoint
https://www.skypunch.tech/rest/v3/elections
Notas
Agregue ?startdate=yyyy/mm/dd al endpoint para seleccionar únicamente las elecciones que comiencen después de la fecha especificada.
Ejemplo de solicitud
GET /rest/v3/elections
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Ejemplo de respuesta
[
  {
    "ID": 1549,
    "UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "PUBLISHRESULTS": 1,
    "ELECTIONNAME": "Sample Election",
    "STARTDATE": "June, 06 2016 00:00:00",
    "ENDDATE": "June, 13 2016 23:59:00",
    "BIODEADLINE": "June, 03 2016 23:59:00"
  },
  {
    "ID": 1562,
    "UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "PUBLISHRESULTS": 0,
    "ELECTIONNAME": "Demonstration Election",
    "STARTDATE": "June, 29 2016 00:00:00",
    "ENDDATE": "June, 29 2016 00:00:00",
    "BIODEADLINE": "June, 29 2016 00:00:00"
  }
]

Descripción: Obtiene datos generales de una elección específica.

Método HTTP: GET

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}
Ejemplo de solicitud
GET /rest/v3/elections/{electionID}
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Ejemplo de respuesta
[
  {
    "ID": 1549,
    "UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "PUBLISHRESULTS": 1,
    "ELECTIONNAME": "Sample Election",
    "STARTDATE": "June, 06 2016 00:00:00",
    "ENDDATE": "June, 13 2016 23:59:00",
    "BIODEADLINE": "June, 03 2016 23:59:00"
  }
]

Descripción: Muestra la boleta en un sitio web externo y permite adaptar su apariencia a la de ese sitio. Una vez que el votante realiza sus selecciones en esta representación de la boleta, pasa a la representación step_two para confirmarlas.

Método HTTP: POST

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/ballot/step_one
Notas

El cuerpo de la solicitud es una colección de pares clave-valor. La forma más sencilla de crearla es tratar los parámetros que se indican a continuación como campos de formulario.

  • VoterID es un identificador numérico único para cada votante.
  • Voted es un valor booleano que indica el estado de votación de los votantes. False for those who have not voted, true para quienes sí han votado.
  • VoterGroup debe ser una cadena vacía cuando la elección no utilice grupos de votantes. Si se utilizan, el parámetro debe coincidir con el código del grupo de votantes definido en la configuración de la elección para el grupo correspondiente.
  • SIGs, al igual que voterGroup, debe ser una cadena vacía si no se utiliza. Si se utiliza, debe coincidir con el código SIG asociado a los cargos que deben aparecer en la boleta del votante.
  • Weight debe tener el valor predeterminado 1, pero puede ser cualquier número entero para reflejar el peso de la boleta cuando algunas boletas tienen más peso que otras.
  • js es un parámetro booleano: true para navegadores compatibles con JavaScript y false para los que no lo admiten. Esto afecta el comportamiento de las biografías de los candidatos.
Ejemplo de solicitud
POST /rest/v3/elections/{electionID}/ballot/step_one
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

voterID=10&voted=false&voterGroup=&sigs=&weight=1&js=true
Respuesta
La respuesta será una cadena HTML. Muestre esa cadena en la ubicación deseada de la página web y aplique los estilos descritos en la sección anterior Cómo dar estilo a la boleta.

Descripción: Muestra la página de confirmación con las selecciones que el votante realizó en la página anterior (step_one). Desde esta página, el votante pasa a la representación step_three de la boleta, donde sus selecciones se guardan en el sistema.

Método HTTP: POST

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/ballot/step_two
Notas

El cuerpo de la solicitud es una colección de pares clave-valor. La forma más sencilla de crearla es tratar los parámetros que se indican a continuación como campos de formulario.

  • Ballot es diferente porque consiste en un fragmento XML que debe crear a partir de las selecciones realizadas por el votante en la página anterior. El siguiente ejemplo muestra el formato XML requerido. Para fines ilustrativos, se supone que:

    1. La boleta contiene los cargos de presidente (id = 8812) y tesorero (id = 8813).
    2. El votante seleccionó a Robert Harrison para presidente y a Terry McAllister para tesorero.
    3. El votante no agregó comentarios o los comentarios están deshabilitados para ambos cargos.

    Para crear este XML, debe analizar el ámbito FORM que se genera cuando el votante envía la boleta en step_one. Busque la variable positions del ámbito FORM. Puede recorrer esta lista de cargos separados por comas y crear los distintos nodos XML en cada iteración.

    ‹positions›
   ‹position›
      ‹positionID›pos8812‹/positionID›
      ‹candidates›Robert Harrison‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
      ‹position›
      ‹positionID›pos8813‹/positionID›
      ‹candidates›Terry McAllister‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
‹/positions›
  • VoterID es un identificador numérico único para cada votante.
  • Weight debe tener el valor predeterminado 1, pero puede ser cualquier número entero para reflejar el peso de la boleta cuando algunas boletas tienen más peso que otras.
  • Languages es una cadena de códigos de idioma separados por comas que admite el sistema (en para inglés, es para español, de para alemán, fr para francés, it para italiano, ch para chino y br para portugués).
Ejemplo de solicitud
POST /rest/v3/elections/{electionID}/ballot/step_two
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

ballot=‹positions›‹position›‹positionID›pos8812‹/positionID›‹candidates›Robert Harrison‹/candidates›‹comments›‹/comments›‹/position›
‹position›‹positionID›pos8813‹/positionID›‹candidates›Terry McAllister
‹/candidates›‹comments›‹/comments›‹/position›‹/positions›&voterID=123&weight=1&languages=en
Respuesta
La respuesta será una cadena HTML. Muestre esa cadena en la ubicación deseada de la página web y aplique los estilos descritos en la sección anterior Cómo dar estilo a la boleta.

Descripción: Inserta la boleta en el sistema inmediatamente después de que el votante confirma sus selecciones en la representación step_two del recurso ballot. Todos los parámetros son obligatorios, excepto los cuatro parámetros custom.

Método HTTP: POST

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/ballot/step_three
Notas

El cuerpo de la solicitud es una colección de pares clave-valor. La forma más sencilla de crearla es tratar los parámetros que se indican a continuación como campos de formulario.

  • Ballot 
    ‹positions›
‹position›
‹positionID›pos8812‹/positionID›
‹candidates›Robert Harrison‹/candidates›
‹comments›‹/comments›
‹/position›
‹position›
‹positionID›pos8813‹/positionID›
‹candidates›Terry McAllister‹/candidates›
‹comments›‹/comments›
‹/position›
‹/positions›
  • VoterID es un identificador numérico único para cada votante.
  • Weight debe tener el valor predeterminado 1, pero puede ser cualquier número entero para reflejar el peso de la boleta cuando algunas boletas tienen más peso que otras.
  • VoterGroup es la misma variable que se utiliza en la representación step_one de la boleta.
  • SIGs, es la misma variable que se utiliza en la representación step_one de la boleta.
  • custom1 es un parámetro opcional que se utiliza para transmitir datos demográficos específicos del votante.
  • custom2 es un parámetro opcional que se utiliza para transmitir datos demográficos específicos del votante.
  • custom3 es un parámetro opcional que se utiliza para transmitir datos demográficos específicos del votante.
  • custom4 es un parámetro opcional que se utiliza para transmitir datos demográficos específicos del votante.
  • Languages es una cadena de códigos de idioma separados por comas que admite el sistema (en para inglés, es para español, de para alemán, fr para francés, it para italiano, ch para chino y br para portugués).
Ejemplo de solicitud
POST /rest/v3/elections/{electionID}/ballot/step_three
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

ballot=‹positions›‹position›‹positionID›pos8812‹/positionID›‹candidates›Robert Harrison‹/candidates›‹comments›‹/comments›‹/position›‹position›‹positionID›pos8813‹/positionID›‹candidates›Terry McAllister‹/candidates›‹comments›‹/comments›‹ /position›‹/positions›&voterID=123&weight=1&voterGroup=&sigs=&custom1=&custom2=&custom3=&custom4=&languages=en
Respuesta
{
    "heading": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkJhbGxvdCBhY2NlcHRlZDwvc3Bhbj4=",
    "message": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPlRoYW5rIHlvdS4gWW91ciBiYWxsb3Q
      gaGFzIGJlZW4gYWNjZXB0ZWQuPC9zcGFuPg==",
    "status": "1",
    "ballot_id": "DSSYjuoBdDkJi2fjq3C1WL",
    "verify_heading": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkJhbGxvdCB2ZXJpZmljYXRpb
      248L3NwYW4+",
    "verify_message": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPihPcHRpb25hbCkgVmVyaWZ5a
      W5nIHRoaXMgYmFsbG90IGxhdGVyIHJlcXVpcmVzIHNhdmluZyBkYXRhIGFib3V0IGl0IHJpZ
        2h0IG5vdy48L3NwYW4+",
    "verify_button": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkdldCB2ZXJpZmljYXRpb24g
      ZGF0YTwvc3Bhbj4="
}

Descripción: Obtiene el total de boletas emitidas en una elección. Puede ayudar a aumentar la participación electoral, como se explica en La prueba social para aumentar la participación electoral.

Método HTTP: GET

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/ballot/count
Notas
Observe que, en el ejemplo de solicitud, no es necesario enviar un parámetro key en el encabezado de la solicitud, a diferencia de lo que ocurre con otros servicios.
Ejemplo de solicitud
GET /rest/v3/elections/2206/ballot/count
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Respuesta
La respuesta será un único número entero.

Descripción: Obtiene todos los votantes de las elecciones alojadas por completo en Skypunch. No se aplica a las elecciones con autenticación delegada o integración completa, en las que el padrón de votantes nunca se carga en el sistema de Skypunch Technology. Este servicio puede utilizarse para identificar quiénes ya votaron y enviar recordatorios por correo electrónico solo a quienes aún no lo hicieron, si el cliente utiliza su propio servicio de correo.

Método HTTP: GET

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/voters
Notas
De forma predeterminada, se obtienen todos los votantes, pero la respuesta puede filtrarse para incluir únicamente a quienes votaron o a quienes no lo hicieron. Para aplicar el filtro, agregue ?filter=voted o ?filter=notvoted al URI.
Ejemplo de solicitud
GET /rest/v3/elections/{electionID}/voters
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Respuesta
[
  {
    "ID": 2891481,
    "FIRSTNAME": "Pete",
    "LASTNAME": "Lopez",
    "EMAIL": "lopez@phony-domain.net",
    "WEIGHT": 1.0000,
    "VOTERGROUP": null,
    "SIGS": null,
    "ROLES": "voter",
    "VOTED": 1,
    "CUSTOM1": null,
    "CUSTOM2": null,
    "CUSTOM3": null,
    "CUSTOM4": null,
    "LANGUAGE": null,
    "OTP_TYPE": "s",
    "STATIC_OTP": 109379
  },
  {
    "ID": 2891486,
    "FIRSTNAME": "Jimmy",
    "LASTNAME": "Roberts",
    "EMAIL": "jimmy@phony-domain.tech",
    "WEIGHT": 1.0000,
    "VOTERGROUP": null,
    "SIGS": null,
    "ROLES": "voter",
    "VOTED": 0,
    "CUSTOM1": null,
    "CUSTOM2": null,
    "CUSTOM3": null,
    "CUSTOM4": null,
    "LANGUAGE": null,
    "OTP_TYPE": null,
    "STATIC_OTP": null
  }
]

Descripción: Agrega un votante a un padrón existente.

Método HTTP: POST

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/voters
Notas
otp_type es opcional y solo debe incluirse en solicitudes para elecciones del sector público. Use d para votantes con contraseña de un solo uso dinámica y s para votantes con contraseña de un solo uso estática.
Ejemplo de solicitud
POST /rest/v3/elections/{electionID}/voters
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/json
Cache-Control: no-cache
{
  "first_name":"Terry",
  "last_name":"McMurray",
  "email":"terry@phony-domain.net",
  "weight":1,
  "voter_group":"student",
  "sigs":"",
  "custom1":"",
  "custom2":"",
  "custom3":"", 
  "custom4":"",
  "otp_type":""
}
Respuesta
{
  "sigs": null,
  "email": "terry@phony-domain.net",
  "voted": 0,
  "weight": 1.0000,
  "custom1": null,
  "custom2": null,
  "custom3": null,
  "custom4": null,
  "language": null,
  "otp_type": null,
  "voter_id": 2891501,
  "last_name": "McMurray",
  "first_name": "Terry",
  "voter_group": "student"
}

Descripción: En una elección con autenticación delegada, los votantes inician sesión en un sitio web externo y luego pasan a Skypunch Technology para votar. Durante este proceso, Skypunch almacena el identificador único que cada votante tiene en el sitio de origen. Utilice este servicio para recuperar esos identificadores y actualizar su propia base de datos, marcando a los votantes como participantes para excluirlos de futuros recordatorios por correo electrónico y mantener un registro de quién votó.

Método HTTP: GET

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/voters/passed
Notas
Ninguna
Ejemplo de solicitud
GET /rest/v3/elections/{electionID}/voters/passed
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Respuesta
6103,4982,1085,10876,2374,1984

Descripción: Obtiene un token de autenticación para un votante que inicia sesión en un sitio externo y luego es redirigido al sitio de Skypunch Technology para ver y emitir su voto.

Método HTTP: POST

Endpoint
https://www.skypunch.tech/rest/v3/elections/{electionID}/token
Notas

The response is a JSON object (see Ejemplo de respuesta below) containing three keys. The values associated with those keys depend on the response from this endpoint. When this endpoint issues a token, the token_issued key will equal yes and the token key will equal the token that you may use to authenticaticate the voter and direct them to the ballot. Do that by redirecting the request to the following URL providing the token in the response as the value of the token parameter. For example:

https://www.skypunch.tech/vote/login.cfm?token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx.

En otros casos, por ejemplo si el votante ya emitió su voto, la clave message contendrá un mensaje al respecto y la clave token estará vacía.

En el ejemplo de solicitud que aparece a continuación, los cuatro campos custom al final de la cadena de pares nombre/valor son opcionales. Inclúyalos si desea transmitir al sistema datos demográficos personalizados de los votantes; de lo contrario, puede omitirlos.

Ejemplo de solicitud
POST /rest/v3/elections/{electionID}/token
Host: www.skypunch.tech
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

firstname=Robert&lastname=Royal&email=royal@phony-domain.tech&voterID=1268&weight=1&votergroup=0&sigs=0&custom1=51&custom2=22213&custom3=Male&custom4=Volunteer
Respuesta
{
  "Token": "f3de9ee1-c143-11ee-8cac-74867a213c83",
  "Message": "",
  "token_issued": "yes"
}