Introducción

Esta documentación entrega toda la información de referencia para interactuar con esta plataforma desde cualquier otro ambiente que soporte la invocación de servicios web seguros (SSL) en modalidad REST (Representational State Transfer).

La documentación indicará:

Endpoint (Método y URI)

Método y URI del servicio a invocar.

Los métodos son los verbos HTTP soportados por REST, tales como GET, POST, PUT, etc.

La URI indica la dirección universal única del servicio, como:

api.blizwork.com/accion/lKAMtO2GZfw4bO2x4w2FZSe3qdToei

Normalmente, para mejor entendimiento, agregamos el protocolo:

https://api.blizwork.com/accion/lKAMtO2GZfw4bO2x4w2FZSe3qdToei

Dado lo anterior, cada método y URI se documenta de la siguiente manera:

POST https://api.blizwork.com/exec/<token>

Donde <token> indica el testimonio válido que debes agregar a la URI para que la llamada sea exitosa.

Seguridad

Nótese que todas las URIs incluyen un código especial, al final. Este elemento corresponde al “testimonio” (token) de seguridad que deben incluir todas las llamadas.

Este token se obtiene en la aplicación web de BlizWork o se puede solicitar al administrador en el correo electrónico usersupport at blizwork dot com.

Cada token tiene una duración máxima de un año, por lo que, para asegurar la continuidad de tu servicio, debes preocuparte de actualizar tus programas e interfaces antes de que venza la validez del token que utilizas.

El token sólo permite interactuar con los procesos, casos, usuarios y recursos de una y solo una organización. Por este motivo, si tu servicio interactúa con los recursos de varias organizaciones, debes asegurarte de disponer de un token válido para cada una de ellas y utilizar el que corresponda a cada caso.

Parámetros de la llamada

Todas las llamadas reciben sus parámetros como un objeto JSON en el contenido (body) del requerimiento (request). Los parámetros varían de acuerdo a la llamada. A continuación un ejemplo de parámetros válidos:

{
   "userId": "<Id. del usuario autorizado>",
   "workflowId": "<Identificador del proceso>",
   "caseNumber": <Número de caso>,
   "formId": "<Identificación del formulario>",
   "nextFormId": "<Id. formulario seleccionado>",
   "formData": [
      {
         "fieldId1": "fieldValue1",
         "fieldId2": 0,
         "fieldIdn": "fieldValuen"
      }
   ]
}

Como convención, se utilizan los signos “menor que” (<) y “mayor que” (>) para indicar un dato que debe proporcionar el desarrollador. Tratamos de que la descripción del valor sea lo más auto-explicativa posible.

Cuando un parámetro espera un número, normalmente utilizamos el número 0.

Cuando se esperan múltiples elementos de un tipo o forma, de manera dinámica, siempre incluimos varias ocurrencias del mismo, con los sufijos 1, 2 y n.

Además de la estructura de los parámetros, se incluye una breve explicación para cada uno de ellos.

Tipo de Contenido

La API sólo es capaz de interpretar los datos como un objeto JSON cuando el tipo de contenido (“content type“) de la llamada (request) se ha definido como application/json. Esto debe definirse como un parámetro en la cabecera (header) HTTP, de la siguiente forma:

Content-Type=application/json

Respuesta

Todos los servicios responden de manera homogénea:

• En caso de un error, se recibirá una respuesta (response) con estado (status) HTTP distinto de 200. En estos casos, puede o no venir un objeto JSON como parte de la respuesta, dependiendo de la naturaleza del error o falla.
• En caso de éxito, se recibirá una respuesta (response) con estado (status) 200 y siempre vendrá un objeto JSON en el cuerpo (body) de la respuesta.

El objeto JSON, en caso que se reciba uno, siempre tendrá la siguiente estructura:

{
   "resultCode": 0,
   "resultMessage": "<Mensaje>"
}

Cuando la operación ha tenido éxito, la propiedad resultCode tendrá el valor 0. En caso de cualquier falla, este valor será distinto de 0.

En caso de éxito, en la propiedad resultMessage podrá haber un mensaje o no. Cuando hay una falla, esta propiedad contendrá un mensaje de error.

El mensaje de error es siempre en idioma español.

Adicionalmente, se incluye una breve explicación de todos los mensajes de error, para ayudar en su diagnóstico y solución.

Algunos métodos pueden incluir información adicional en otras propiedad. Cuando esto ocurre, está documentado.

Notas

Para cada método incluimos algunas notas explicando consideraciones a tener en cuenta para el llamado, de manera de ayudar a su uso. Si descubre situaciones no previstas, positivas o negativas, te invitamos a compartirlo en los comentarios.

Límites de Uso

Dado que cada llamada implica el uso de recursos computacionales de alto costo, se imponen límites al uso de ellos. Para evitar un abuso de estos recursos, se imponen límites al uso de esta API.

Estos límites dependen de cada plan de la organización involucrada en la llamada. Nótese que para esta limitación no se considera el plan del desarrollador que realiza la llamada. Incluso, el desarrollador podría no tener un plan.

Si necesitas realizar pruebas de un desarrollo, contáctanos para que podamos ayudarte a usersupport at blizwork dot com (evaluaremos cada caso de forma independiente).

Ejemplo

A continuación se muestra un ejemplo de llamado en JavaScript, el cual se puede ejecutar en cualquier navegador compatible, dentro de un tag de <script>…</script>:

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"userId":"usuario@empresa.com","workflowId":"mesa-ayuda"});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("api.blizwork.com/init/OeZhg4oqPgV11MHRb3OOJyTrNpY5D3/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));