API

Introducción al sistema de APIs

API (Application Program Interface o Programa de Aplicación de Interfaz) es un sistema que le permitirá controlar algunos datos del sistema desde cualquier plataforma, o bien integrar el funcionamiento y datos de eCronos con cualquier otro programa. A través de estas API podrá enviar y recibir datos de su instalación de eCronos con una interfaz de uso común y a través del protocolo HTTP

1) APIs: principio básico

La API utilizan el protocolo HTTP, comúnmente utilizado para la WEB. 
Como si fuera una base de datos, usted enviará consulta a eCronos y el mismo devolverá los datos correspondiente a esa consulta. Las consultas enviadas a eCronos podrán ser de carácter informativo, para recibir información, o bien consultas para la modificación de datos.

Los datos enviados a eCronos se harán con el método POST y los datos devueltos en la respuestas estarán en formato JSON.

Las API estan disponibles unicamente para el administrador y los user-manager (o revendedores), salvo las API de suscripción. El uso de estas API requiere de los datos de login del admin o user-manager, segun corresponde (usuario y contraseña).

Todas las funciones requiere de almenos 3 parametros en la consulta POST, que son:


login_username: representando al nombre de usuario del admin o user-manager. 


login_password: representando la contraseña del admin o user-manager
.

función: representando el nombre de la función que se desea ejecutar.

En caso de que alguna consulta devuelva un error, la respuesta contendrá el código de error numérico y mensaje de error (en ingles).
En cada función se detallan los parámetros requeridos para la consulta, los valores devueltos y los posibles errores con su correspondiente código numérico.

Algunos ejemplos

Ejemplo en PHP utilizando sockets mediando la libreria "http":

 

Ejemplo en PHP utilizando cURL:

 

Respuesta a este ejemplo en caso de exito:

 

Respuesta a este ejemplo en caso de error:

 

Ejemplo en Javascript utilizando la libreria Jquery:

  

2) Funciones disponibles

ListUsers: Lista los usuarios creados en el sistema. Si la consulta es ejecutada por el administrador, la lista de usuarios incluirá sus usuarios individuales, los resellers (o user-manager) y los sub usuarios de cada reseller.

GetUser: Obtiene los datos específicos de un usuario, así como también sus limites y estadísticas de uso.

CreateUser: Permite la creación de usuarios.

AddCredit: Agrega credito para envio de emails a un usuario. Esta funcion solo es valida para usuarios con asignacion de envios "Unica vez".

DeleteUser: Elimina un usuario.

ChangePassword: Cambia la contraseña de acceso de un usuario.

SuspendUser: Suspende un usuario inhabilitándolo para acceder al sistema.

UunsuspendUser: Quita la suspensión de un usuario.

ListCaps: Obtiene la lista de campañas/mensajes activas y finalizadas.

GetCamp: Obtiene los detalles de una determinada campaña/mensajes y sus reportes.

Haga click en el nombre de la función para mas información de la misma.

 

3) Suscripcion y desuscripción API

Esta API te permite suscribirse, desuscribirse u obtener el status del suscriptor directamente

El metodo del pedido puede ser POST o GET

Ejemplos:

Suscripción: http://ecronos.com/api.php?apikey=db2542df8c4b08d&action=subscribe&email=user@domain.com&name=John

Desuscripción: http://ecronos.com/api.php?apikey=db2544df8c4b08d&action=unsubscribe&email=user@domain.com

Suscripción con fecha de vencimiento: http://ecronos.com/api.php?apikey=db2542df8c4b08d&action=subscribe&email=user@domain.com&unsus_date=1326314118

 

Parametros:

apikey: la API Key de la lista especificada.

action: suscribir, desuscribir o status

email: mandar email para suscribir, desuscribir o recibir status

name: valor opcional solo para la suscripción

unsus_date: valor opcional solo para suscripcion. Terminos de suscripcion en formato UNIX (ejemplo: 1323722118)

success_url: la url a la que va si es exitoso

error_url: la URL a la que va en caso de error.  Las variables "error" and "errno" se pasan con el metodo GET.

 

Valores de retorno:

status: emails añadidos en caso de suscripción exitosa

status: emails desuscriptos en caso de desuscripción exitosa

 

Para solicitar status:

email: email del suscriptor

name: nombre del suscriptor

creation_date: fecha de creación del suscriptor en formato UNIX

unsus_date: fecha en la que finaliza la suscripcion del suscriptor en formato UNIX

active: status del suscriptor, 1=activo, 0=inactivo (no va a recibir mails aquellos suscriptores con status inactivos)

 

Códigos de error:

1101: Lista o api key invalida

1102: acción no reconocida. Nombre de acción invalida

1103: dirección de mail invalida

1104: cuota de suscriptores excedida. O la lista se encuentra repleta o ha llegado al limite de suscriptores permitidos

1105: se encontró mail ya existente en la lista al intentar de suscribirlo

1106: se encontró que el mail a suscribir ya se desuscribió en el pasado

1107: se encontró que el mail a desuscribir no existe en la lista

1107: el mail a ingresar se encuentra en lista negra. Se debe suscribir mediante un doble formulario opt-in

 

Ejemplo de script PHP: