Introducción | Referencia API WS.WebTV | WebTV Solutions

Imprimir

El API de WS.WebTV ha sido diseñada para permitir la integración/interacción entre otras aplicaciones y la WebTV. Se lanzó con la versión 1.8 de WS.WebTV y poco a poco se han ido añadiendo funciones. Nuestra intención es continuar añadiendo funciones, con el paso del tiempo.

Administrado las Credenciales de API

Antes the utilizar el API lo primero que debe hacer es crear una Credencial en la WebTV. Tenga presente que puede crear cualquier número de Credenciales.

Para crear/editar una Credencial:

1. Ir a API...

2. En la lista de Credenciales...
(A) Para crear una Credencial de API haga click en el botón "Nueva Credencial.
(B) Para editar una Credencial existente haga click en el icono de "lápiz" correspondiente.


Las interfaces de crteación y edición son muy The creation and edition interfaces are very similar, however, when you are editing a Credential you will see additional information.

3. Propiedades...
• Título: Introduzca un título descriptivo para su propia referencia.
• Tiempo expiración solicitudes: Este es el tiempo máximo (en segundos), transcurridos desde la fecha de generación de la solicitud, que una solicitud será aceptada por el sistema.
• Referers Permitidos: (Opcional) Si la credencial se está generando para se utilizada en una página Web (Javascript, por ejemplo), entonces puede especificar los dominios de referencia permitidos (separados por coma). Por favor, tenga presente que si la Credencial está configurada para restringir por referers (referidos) pero el servidor de origen no suministra dicha información entonces la solicitud será descartada a menos que también añada el referer "blank" a la lista.
Ejemplo: Para permitir solicitudes desde "midominio.com" y "blank" debe introducir: midominio.com, www.midominio.com, blank
• Permitir Estadísticas: Cuando se habilita el sistema registrará estadísticas de la Credencial.
4. Permisos... Seleccione los permisos (generales y específicos) que desea otorgar a la Credencial.
Los permisos específicos permiten que algunas secciones del API tengan permisos diferentes a los generales.


Después de guardar (crear) la Credencial, el sistema generará una "ID de Clave" y una "Clave Secreta (Compartida)":
• ID de Clave: Esta ID deberá ser utilizada públicamente para identificar las solicitudes de esta Credencial.
• Clave Secreta (Compartida): Sea cuidadoso con esta Clave porque se utilizará para generar las firmas de validación; por lo tanto nunca debe exponerlas públicamente. Esta Clave sólo deben "conocerla" la WebTV y su aplicación.
NOTA: Estas claves se generarán una única vez (al momento de crear la Credencial).

URL Base del API

La URL del es la URL base de su WebTV seguida de "/api.php".
Ejemplo:
Si la URL de su WebTV es http://www.midominiowebtv.tv
...entonces todas las solicitudes de API deben enviarse a http://www.midominiowebtv.tv/api.php (se recomienda utilizar https!)

NOTA: Todas las solicitudes son realizadas utilizando GET y POST.

Seguridad

Información requerida

Cada solicitud que envíe al API debe tener la siguientes variables GET en la URL de la solicitud:

Ejemplo:
https://....../api.php?go=clips&do=get&iq=5&timestamp=1427282901&salt=1e05489590729c06363f6ddfff5c99ff&key=57a3f24f8abd71cdde44c3e3fb675bc7&signature=Y98d2tB3oMPKwIJ8PJEZXG72Nd1zqn27yUCUsP8phHs%3D

Autenticación: Firma de Verificación

Excepto en los casos cuando ha permitido las solicitudes sin firma, todas las solicitudes al API requieren una firma de verificación. La firma (hash) es generada a partir de la concatenación de "salt" y "timestamp", utilizando base64 + HMAC SHA256 junto con la "Clave Secreta (Compartida)".

Ejemplo en Pseudocode:

firma = URL ENCODE ( base64 ( HMAC SHA256 ( ( "salt" + "timestamp" ) , KEY SECRET ) ) )

Ejemplo en PHP:

$API_KEY_SECRET = "clave secreta de la credencial";
$salt = md5(mt_rand());
$timestamp = time();
$signature = urlencode(base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_KEY_SECRET, true)));

Si está trabajando con otros lenguajes, pudiera interesarle el siguiente documento:
Ejemplos para crear hashes base64 usando HMAC SHA256 en diferentes lenguages

Recomendaciones Importantes

1. Asegure sus solicitudes utilizando HTTPS en las URLs de las solicitudes de API. Esto requiere tener un certificado SSL válido en el servidor de su WebTV. Esto es especialmente importante cuando realice solicitudes relacionadas con Usuarios.

2. En la Web, siempre evite enviar solicitudes al API utilizando una aplicación "Front-End".
Ejemplo: Si necesita utilizar Javascript para obtener información entonces evite realizar las solicitudes directamente desde Javascript. En su lugar, puede utilizar una aplicación Back-End (del lado del servidor) para realizar las solicitudes al API y luego enviar (solamente) el resultado apropiado a Javascript. Adicionalmente, nunca incluya la Clave Secreta (Compartida) en un Javascript ya que será públicamente accesible (!).

3. Nunca exponga la Clave Secreta (Compartida) del API y haga todo lo que pueda para protegerla. Si está usando una aplicación Front-End para enviar solicitudes al API (por ejemplo, una App móvil), entonces asegúrese de que la Clave Secreta está verdaderamente a salvo o utilice una aplicación Back-End para enviar las solicitudes al API y el resultado a la App. Además, siempre utilice HTTPS y evite manejar información sensible desde la App.

Formato de Respuesta

Por defecto, el API devolverá los resultados en formato JSON; sin embargo, puede pedir el resultado en formato JSONP (con callback), añadiendo las variables GET "format" y "callback" a la URL de las solicitud.
Ejemplo:
https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&format=jsonp&callback=myfunction

Caché

Para un mejor rendimiento, el sistema almacena en caché las solicitudes tipo "OBTENER". En caso de que Ud. no desee (y sea realmente necesario) el resultado del caché, puede pedirlo añadiendo la variable GET "cache" a la URL de la solicitud.
NOTA: Para modificar la "vida" del caché, puede hacerlo desde Configuración > Ajustes > Caché y modifique el ajuste "Vida del caché de API".
Ejemplo:
https://....../api.php?go=clips&do=get&iq=5&key=57a3f....&cache=0

IMPORTANTE: Asegúrese de que la carpeta api/temp/cache tiene permisos de escritura. Puede verificar esto con la Herramienta de Diagnóstico de la WebTV.

Mensajes de Error Generales

Los siguientes son errores que pueden ser devueltos por cualquier solicitud:

• REQUEST_ERROR | Missing signature:
Los permisos de la Credencial sólo permiten solicitudes firmadas y no se ha suministrado una firma.

• REQUEST_ERROR | Invalid request (missing required info):
Falta toda, o parte, de la información requerida (variables GET) en la URL de la solicitud.

• REQUEST_ERROR | Invalid API Key ID:
La IP de Clave de API no se encontró en el sistema.

• REQUEST_ERROR | Invalid request (time out):
La solicitud es más antigua que el "Tiempo expiración solicitudes" especificado en la Credencial.

• REQUEST_ERROR | Permission error (GET, MODIFY, CREATE, DELETE):
La Credencial no tiene el permiso requerido para realizar la solicitud.

• REQUEST_ERROR | Wrong signature:
La firma suministrada no coincide con la firma esperada.

• REQUEST_ERROR | Not allowed:
La Credencial no permite solicitudes realizadas desde esa referencia (referer).