API

La documentación sobre API está orientada a usuarios del servicio que deseen integrar e-planning ad server con sus propios sistemas propietarios.

La API (Application Programming Interface) permite realizar operaciones básicas sobre los objetos gestionados por e-planning ad server, como ser pautas, anunciantes, espacios, etc.  Las operaciones posibles pueden ser la creación de nuevos objetos, modificación, listados, etc. La API, permite, por ejemplo, que un sistema de gestión interno de la empresa cree automáticamente las pautas en e-planning ad server y lleve su control para poder realizar la facturación.

La API funciona utilizando HTTPS como protocolo de comunicación y como formato de intercambio de datos XML o JSON. Para acceder a la API es necesario tener creado un usuario en e-planning ad server, el cual se puede crear en la solapa Usuarios (VER - Usuario de Acceso API)

Objetos

Los objetos disponibles a través del API son los mismos que se pueden administrar a través de la interfaz web, con ciertas limitaciones. Los atributos accesibles son los mismos que se ven en la interfaz web.  Cualquier objeto creado a través del API se puede ver instantáneamente en la interfaz web y viceversa. 

Identificadores

Cada objeto gestionable a través del API tiene un identificador único de tipo numérico.  Por ejemplo, para una pauta, el identificador se llama pauta_id y su valor es un número entero.  Ej: 54435.  Cada vez que en el API se debe realizar una operación sobre un objeto específico, se lo referencia mediante su identificador.   

Funcionamiento

El acceso al API se puede realizar mediante cualquier lenguaje de programación que permita realizar requests HTTPS y parsear archivos XML o JSON.  Por ejemplo, Java, Perl, C#, C, etc.   

Autenticación

Se utiliza la autenticación básica del protocolo HTTP (Basic Authentication). 

Acceso

Para acceder al API, primero hay que conocer el URL base.  Éste depende de cuál es el data center de e-planning desde el cual se brinda el servicio:

- Estados Unidos: https://admin.us.e-planning.net/ *

- Europa: https://admin.eu.e-planning.net/

Para acceder a la interfaz, no es necesario realizar un login explícito.  Basta con realizar el primer request de una operación particular para quedar logueado en la interfaz. 

Lo que sí es necesario al terminar la sesión es desconectarse de la interfaz.:

• En caso de que estar logueado por cookies, la operación se realiza mediante un request al URL:

https://admin.e-planning.net/login?op=logout

https://admin.us.e-planning.net/login?op=logout  ( o https://api.us.e-planning.net/logout) 

https://admin.eu.e-planning.net/login?op=logout

• En casos en que no se esté logueado por cookies, la operación se realiza mediante un request al URL

/admin/?relogin=<random>&o=xml

Deberá reemplazar <random> por un número al azar, como puede ser la cantidad de segundos del día actual, u otro número entero.  Ej:

/admin/?relogin=43242341&o=xml

Para cada una de las operaciones, se deberá combinar la URL de la operación que se desea realizar, con el URL base.  Por ejemplo, si se utiliza el servicio del data center de Estados Unidos, y se desea obtener un listado de pautas, el URL se va a formar de la siguiente manera:

URL base:

https://admin.ar.e-planning.net/

URL de la operación:

/admin/adnet/pub/admin/pautas.html?op=l

- URL completo:

https://admin.ar.e-planning.net/admin/adnet/pub/admin/pautas.html?op=l

Algunas operaciones disponibles

• Listado de espacios
• Borrar un espacio
• Listado de secciones
• Listado de sitios
• Listado de anunciantes
• Listado de pautas
• Información de una pauta
• Creación de anunciante
• Creación de pauta

Cada operación tiene un URL y parámetros posibles.

Todos los parámetros se deben especificar en el URL con el formato url-encoded.

Los nombres de los parámetros se deben especificar en minúsculas, tal como se muestra en los ejemplos.

Las operaciones que consultan datos se realizan mediante el método GET.  Las que modifican datos, mediante POST.  En este caso (POST), los parámetros se deben enviar en el cuerpo del mensaje (Request Body).

En los listados se pueden especificar filtros, mediante parámetros. Si no se especifican parámetros, por default se muestran todos los objetos disponibles.