MDIrector - APIs de Integración

Transcripción

1 MDIrector - APIs de Integración INTRODUCCIÓN MDirector utiliza un API REST para poder actualizar los contactos de su BBDD. La dirección base para los servicios del API es es " Este API REST se utiliza mediante el protocolo HTTP. Esto quiere decir que según el método del protocolo utilizado (GET, POST, PUT, DELETE), el api realizará acciones diferentes. Por ejemplo, en una llamada al modulo de contactos (api_contact): Llamando al api con POST: Creará el contacto. Llamando al api con DELETE: Eliminará al contacto. El sistema de autenticación que utiliza el api externo de MDirector está basado en el sistema two legged de OAuth. Para la firma de las peticiones deberá usar un consumer-key que será el identificador de su empresa y un consumer-secret que será una contraseña de acceso generada desde mdirector para su identificación mediante oauth. Si decide usar el lenguaje de scripting PHP, le recomendamos que use la librería oauth-php por su sencillez de uso. Puede descargarla en el enlace que le ofrecemos a continuación: A continuacion mostramos un ejemplo de una llamada a un servicio del api MDirector usando la librería oauth-php: <?php include_once "./oauth-php/library/oauthstore.php"; include_once "./oauth-php/library/oauthrequester.php"; $key = '2325'; // Este es su identificador de empresa $secret = 'mdirector_secret'; // Esta es la clave de api que MDirector le ha proporcionado $options = array( 'consumer_key' => $key, 'consumer_secret' => $secret ); OAuthStore::instance("2Leg", $options ); $url = " // Url del servicio del api externo al que atacar $method = "POST"; // metodo REST // Parámetros $params = array( 'dataid' => 'valor_del_parametro_generado_dataid', 'PRODUCTO' => 'Cesta001# ', 'IMPORTE' => '670.50', 'CANTIDAD' => '2',

2 'SEND-NOTIFICATIONS' => '1' ); try $request = new OAuthRequester($url, $method, $params); $result = $request->dorequest(); $response = $result['body']; echo $response. "\n"; catch(oauthexception2 $e) die( $e->getmessage() ); Todos los servicios de MDirector devuelven objetos JSON, en caso de error tendrá una salida semejante a la siguiente: "response":"error", "message":"contact not found", "code":1142 Y en caso de acierto: "response":"ok", "message": "?" "data":?

3 ACCESO Dentro de la plataforma Mdirector siempre tendrá disponibles sus claves de acceso al API y las estadísticas de uso. Acceda al menu Preferencias Información API Información General donde podrá encontrar estos datos: Información de acceso consumer-key: 4470 consumer-secret: xuxxxxv12alm3456 Estadísticas de uso Llamadas a servicios de api hoy: 21 Llamadas a servicios de api este mes: 84 Llamadas a servicios de api totales: 2156

4 API Contactos A continuación se describen los métodos y los parámetros para acceder a los servicios de API de contactos. La url del servicio a atacar eshttp:// Lista de métodos soportados: POST Se usa para crear nuevos contactos. 'listid' : (opcional) Identificador de la lista (Se usa la lista por defecto en caso de no especificarse) 'allow-unsubscribed' : (opcional) TRUE / FALSE. Por defecto FALSE Determina si el contacto se daría de alta incluso aunque ya estuviera en la lista de bajas. 'send-notifications' : (opcional) TRUE / FALSE. Por defecto FALSE Determina si, en caso de haber una campaña de registro vigente, se enviaría al contacto tras darse de alta. 'name' : (opcional) Nombre para el contacto. 'surname1' : (opcional) Primer apellido. 'surname2' : (opcional) Segundo apellido 'sex' : (opcional) M/F/X (Masculino/Femenino/Sin especificar) 'birthday' : (opcional) Fecha de nacimiento en formato DD-MM-AAAA 'reference' : (opcional) Referencia ' ' : (obligatorio) O bien " " o bien "movil" deben ser especificados.

5 'movil' : (obligatorio) O bien " " o bien "movil" deben ser especificados. Móvil 'city' : (opcional) Localidad 'province' : (opcional) Provincia 'country' : (opcional) País 'cp' : (opcional) Código postal '...' : (opcional) '...' representa cualquier parámetro libre, la clave para el campo será el nombre del parámetro libre y tomará el valor que se asigne. DELETE Se usa para eliminar y dar de baja contactos. 'unsubscribe' : (opcional) TRUE / FALSE (por defecto FALSE) Determina si debe tratarse la baja como una desuscripción. 'reason' : (obligatorio) 'ip' : (opcional) Motivo de la baja Dirección ip que origina la baja ' ' : (obligatorio) Este campo es obligatorio si 'unsubscribe' es true. Dirección de correo. 'listid' : (obligatorio) Este campo es obligatorio si 'unsubscribe' es false. Identificador de la lista. 'mobile' : (obligatorio) Este campo es obligatorio si 'unsubscribe' es true. Número de móvil.

6 'conid' : (obligatorio) Este campo es obligatorio si 'unsubscribe' es false. Identificador del contacto. 'subid' : (opcional) Identificador del subenvío. PUT Se usa para modificar contactos existentes. 'listid' : (obligatorio) Identificador de la lista. 'conid' : (obligatorio) Identificador del contacto. 'name' : (opcional) Nombre para el contacto. 'surname1' : (opcional) Primer apellido. 'surname2' : (opcional) Segundo apellido 'sex' : (opcional) M/F/X (Masculino/Femenino/Sin especificar) 'birthday' : (opcional) Fecha de nacimiento en formato DD-MM-AAAA 'reference' : (opcional) Referencia ' ' : (opcional) 'movil' : (opcional) Móvil 'city' : (opcional)

7 Localidad 'province' : (opcional) Provincia 'country' : (opcional) País 'cp' : (opcional) Código postal '...' : (opcional) '...' representa cualquier parámetro libre, la clave para el campo será el nombre del parámetro libre y tomará el valor que se asigne. GET Se usa para consultar contactos existentes. 'listid' : (opcional) Identificador de la lista de contactos. ' ' : Obligatorio (O bien " " o bien "mobile" deben ser especificados) 'mobile' : Obligatorio (O bien " " o bien "mobile" deben ser especificados) Movil Ejemplos de respuesta: "response":"error", "message":"contact not found", "code":1142 "response":"ok", "data": "conid":"16411", " ":"user@antevenio.com", "movil":null, "reference":"", "name":"", "surname1":"", "surname2":"", "birthday":

8 " ", "sex":"x", "city":"", "province":"0", "country": "ES", "cp":"", "reputation":"3", "registerdate":"19\/10\/ :06", "registerdatesystem":" :06:39", "lastdeliveryopendate":"00\/00\/0000", "lastdeliveryclickdate":"00\/00\/0000", "numdeliveries":"10", "numopens":"0", "numopenspercent":"0", "numclicks":"0", "numclickspercent":"0", "lastdeliverydate":"00\/00\/0000", "lastdeliverysubject":"el asunto del test A\/B de creatividad", "lastdeliveryopensubject":null, "lastdeliveryclicksubject":null, "freeparams":[]

9 API Parámetros Libres (campos personalizados) El servico de parámetros libres se usa para manipular los parámetros libres de su empresa. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de parametros libres. La url del servicio a atacar es Lista de métodos soportados: GET Se usa para obtener la lista de parámetros libres en su empresa. Éste método no requiere ningún parámetro POST DELETE Se usa para dar de alta un nuevo parámetro libre en su empresa. 'type' : (obligatorio) Tipo para el parámetro libre. Valores aceptados: 1: Texto 2: Num érico 3: Fecha 'name' : (obligatorio) El nombre para el nuevo parámetro libre. Se usa para eliminar un parámetro libre de su empresa. Tenga en cuenta que al eliminar parámetros libres de su empresa, todos los contactos que albergaran información en este campo la perderán de forma irreversible 'parid' : (obligatorio) O bien "parid" o bien "name" deben ser especificados. Identificador del parámetro libre en el sistema. 'name' : (obligatorio) O bien "parid" o bien "name" deben ser especificados. Nombre del parámetro libre en e l sistema.

10 API Ventas El pixel de venta es un servicio que permite hacer un seguimiento de las ventas iniciadas en alguno de los enlaces trackeados desde la plataforma de mdirector. El funcionamiento se lleva a cabo en dos pasos: 1. Activación del link a trackear como link de venta. Desde de la pantalla en la que se identifican los links detectados en una creatividad debemos marcar el link como link de venta, para ello marcamos el checkbos que encontramos a tal efecto en cada link. De esta manera le decimos a la plataforma que marque el enlace como una venta y le haga un seguimiento de forma especial. 2. Notificación de la venta La url del servicio a atacar es Para notificar a la plataforma que se ha llevado a cabo una venta, debemos enviar, usando el api rest los siguientes parametros con información de la venta que se ha llevado a cabo: dataid - Es el parametro dataid generado por la plataforma de mdirector y que debe ser arrastrado durante todo el proceso de venta PRODUCTO - Nombre o referencia de la cesta, servira para identificar la venta en el entorno del cliente IMPORTE - Importe total de la venta CANTIDAD - Número de productos que conforman la cesta. SEND-NOTIFICATIONS - Si este parametro llega con valor 1 y el cliente tiene configurada la funcionalidad de mail automatico de venta, se enviara un correo al contacto que realiza la compra. Lo ideal es hacer esto desde la página de venta terminadao "página de gracias" de cada venta que se lleve a cabo, a continuación se muestran un ejemplo de como llamar al API utilizando PHP

11 API Estadísticas El servicio de estadísticas se usa para consultar los datos de resultados de sus envíos. Puede solicitar un resumen general o una informe de una sección específica de su envío. A si mismo puede optar entre recuperar los resultados en formato JSON o CSV. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de estadísticas. La url del servicio a atacar es Lista de métodos soportados: GET Para obtener el informe de resultados de su envío. 'envid' : (obligatorio) Identificador del envío. 'data' : (opcional, toma el valor "summary" por defecto). Tipo de informe a solicitar. Posibles valores: 'summary' Devuelve el informe resumen del envío. 'opens' Devuelve el informe de aperturas del envío. 'unsubscriptions' Devuelve el informe de bajas del envío. 'failures' Devuelve el informe de fallidos del envío. 'sales' Devuelve el informe de ventas del envío. 'clicks' Devuelve el informe de clicks del envío. 'format' : (opcional, toma el valor "json" por defecto). Formato de representación de la información. Posibles valores: 'json' Devuelve el informe en formato JSON 'csv' Devuelve el informe en formato CSV

12 API Bajas El servico de bajas se usa para manipular la lista de bajas de su empresa. Puede dar de alta, eliminar y consultar los contactos de esta lista. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de bajas. La url del servicio a atacar es Lista de métodos soportados: GET Se usa para determinar si existe un conctacto en su lista de bajas. ' ' : (obligatorio) O bien " " o bien "movil" deben ser especificados. 'movil' : (obligatorio) O bien " " o bien "movil" deben ser especificados. Móvil POST DELETE Se usa para insertar un nuevo conctacto en su lista de bajas. ' ' : (obligatorio) O bien " " o bien "movil" deben ser especificados. 'movil' : (obligatorio) O bien " " o bien "movil" deben ser especificados. Móvil Se usa para eliminar un conctacto de su lista de bajas. ' ' : (obligatorio) O bien " " o bien "movil" deben ser especificados. 'movil' : (obligatorio) O bien " " o bien "movil" deben ser especificados. Móvil También existe la posibilidad de descargar un listado con las bajas de su empresa. Para este caso la url del servicio a atacar es:

13 Lista de métodos soportados GET Se usa para obtener un listado de bajas entre dos fechas Parámetros 'date' : (obligatorio) Fecha de inicio del listado, formato: "YYYY - MM - DD" 'enddate' : (opcional, si no se especifica toma el mismo valor que "date") Fecha de fin del listado, formato: "YYYY - MM - DD". 'format' : (opcional, toma el valor "json" por defecto). Formato de representación de la información Posibles valores: 'json' Devuelve el listado en formato JSON 'csv' Devuelve el listado en formato CSV

14 API Fallidos Con este servicio puede descargar un listado con los rebotes generados en la subcuenta. Para este caso la url del servicio a atacar es: Lista de métodos soportados GET Se usa para obtener un listado de fallidos entre dos fechas Parámetros 'date' : (obligatorio) Fecha de inicio del listado, formato: "YYYY - MM - DD" 'enddate' : (opcional, si no se especifica toma el mismo valor que "date") Fecha de fin del listado, formato: "YYYY - MM - DD". 'format' : (opcional, toma el valor "json" por defecto). Formato de representación de la información Posibles valores: 'json' Devuelve el listado en formato JSON 'csv' Devuelve el listado en formato CSV

15 API Envíos El servicio de envíos se usa para crear y programar campañas de forma automática sin interactuar con el frontal web. Puede crear campañas, especificando todos sus parámetros incluyendo la creatividad y las segmentaciones, para mas tarde programarlas o enviarlas en el momento actual. También puede cancelar la programación de un envío. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de envíos. La url del servicio a atacar es Lista de métodos soportados: POST Se usa para crear envíos. 'type' : (obligatorio) Define el tipo de envío a crear. Acepta los valores " " y "sms" 'name' : (obligatorio) El nombre para identificar el envío. 'subject' : (obligatorio) El asunto para el envío. 'campaign' : (obligatorio si no se especifica 'campaignname') El identificador de la campaña para el envío. 'campaignname' : (obligatorio si no se especifica 'campaign') El nombre de la campaña para el envío. MDirector buscará la campaña con el nombre especificado y si la encuentra asociará el envío a la campaña existente. En caso de no encontrarla, creará una nueva campaña con el nombre especificado y asociará de igual manera el envía a la nueva campaña. 'language' : (obligatorio) El idioma para el envío. Acepta códigos de dos letras; Por ejemplo: es, de, br, pt... etc. 'creativity' : (obligatorio) El contenido de la creatividad codificado en base64. Al igual que al crear envíos desde el frontal se aceptarán los mismos formatos de archivo (html y zip). Es imprescindible que el contenido del fichero se envíe codificado en el sistema base64.

16 'segments' : (obligatorio) La lista de identificadores de segmento para el envío. La lista debe estar codificada en JSON, por ejemplo: [ "1", "66", "99" ] Es posible especificar listas y grupos de segmentos prefijando el identificador con las etiquetas "LIST-" y "GROUP-", por ejemplo: [ "LIST-23", "GROUP-1", "88" ] En este último ejemplo estaríamos especificando que el envío debe realizarse a la lista 23, al grupo 1 y al segmento 88. 'addheader' : (opcional) Acepta los valores "1" y "0", determina si se ha de añadir la cabecera al envío. 'addspamheader' : (opcional) Acepta los valores "1" y "0", determina si se ha de añadir la cabecera de spam al envío. 'addgalinks' : (opcional) Acepta los valores "1" y "0", determina si se ha de añadir las variables necesarias para sincronizar con Google Analytics 'tags' : (opcional) Determina los tags que clasificarán a este envió. El parametro debe ser especificado como un array de JSON. Por ejemplo: [ "Noviembre", "Invierno", "Moda" ] 'fromname' : (opcional) Especifica en "nombre" del remitente para el envío. Este es el nombre que le aparecerá a sus contactos como remitente del envío. 'replytoname' : (opcional) Especifica en "nombre" que aparecerá cuando sus contactos decidan responder a este envío. 'replyto ' : (opcional) Especifica la dirección de correo de respuesta para este envío. 'creativitytext' : (opcional) Contiene la versión en texto plano para la creatividad. 'autocreativitytext' : (opcional) Acepta los valores '0' o '1'. Determina si MDirector creará una versión en texto de la creatividad de forma automática. Si se especifica éste parámetro como 1 se igonará cualquier posible contenido que tuviera el parámetro 'creativitytext'

17 'reminder' : (opcional) Acepta los valores "1" y "0", determina si se ha de enviar un recordatorio con un resumen de las estadísticas del envío a las direcciones especificadas en 'reminderaddresses' el día especificado en 'reminderdate'. 'reminderdate' : (opcional) Fecha del recordatorio, formato: "YYYY-MM-DD". 'reminderaddresses' : (opcional) Direcciones de que recibirán el recordatorio. Debe ser una lista separada por comas (ejemplo: 1@ .com, 2@ .com). La respuesta en caso de creación satisfactoria incluye la información de los identificadores de envío, subenvio y las versiones de la creatividad parseadas (html y texto). A continuación se muestra un ejemplo de salida satisfactoria: "response": "ok", "message": "The delivery was successfully created", "data": "envid": "180", "subid": "238", "html": "This is the html version", "plaintext": "This is the text version." PUT Se usa para programar un envío para una fecha determinada o enviarlo en el momento. DELETE 'envid' : (obligatorio) Identificador del envío 'date' : (obligatorio) Fecha de programación del envío, formato: "YYYY-MM-DD HH:MM" o "now". Si se especifica "now" el envío saldrá inmediatamente. Se usa para cancelar la programación de un envío. Reseteará el estado del envío a "Borrador". Solo se pueden resetear envíos en estado "Programado". En caso contrario se devolverá un error. 'envid' : (obligatorio) Identificador del envío

18 API Listas El servicio de listas se usa para manipular la listas de contactos de su empresa. Puede dar de alta, eliminar y consultar las listas de su empresa. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de listas. La url del servicio a atacar es Lista de métodos soportados: GET Se usa para recuperar todas las listas activas en su empresa. POST Este método no acepta parámetros. Se usa para crear una nueva lista en su empresa. Este método no acepta parámetros. PUT 'listname' : (obligatorio) El nombre de la lista a crear debe ser especificado. listname Se usa para cambiar el nombre a una lista ya existente. Este método no acepta parámetros. DELETE 'listname' : (obligatorio) El nuevo nombre de la lista a modificar. listname 'listid' : (obligatorio) El id de la lista a modificar. listid Se usa para eliminar un lista de contactos en su empresa. Este método no acepta parámetros. 'listname' : (obligatorio) El nombre de la lista a crear debe ser especificado. listname

19 API Campañas El servicio de campañas se usa para manipular la lista de campañas de tu empresa. Puedes consultar, dar de alta, modificar, eliminar, archivar y reactivar las campañas de tu empresa. A continuación se describen los métodos y los parámetros para acceder a los servicios de API de campañas La url del servicio a atacar es Lista de métodos soportados: GET Se usa para recuperar la lista de campañas en la empresa o para consultar una en particular. 'id' : (opcional) Identificador de la campaña. Si se especifica este parámetro, MDirector recuperará la información relativa a la campaña cuyo identificador coincide con el especificado. Ejemplo de respuesta: "response":"ok", "data": "campaignid":"143", "campaignname":"test Campaign", "campaigncreationdate":"01\/12\/2014", "targets":[ ] 'type' : (opcional) Tipo para el listado de campañas. Usando este parámetro puedes especificar si deseas obtener el listado de campañas activas o archivadas. Puede tomar los valores 'visible' para campañas activas, o 'closed' para campañas archivadas. Se toma el valor 'visible' por defecto si el parámetro no es especificado. Ejemplo de respuesta: "response":"ok", "data":[ "id":"3", "campaignname":"campaign number three", "id":"2", "campaignname":"campaign number two"

20 , "id":"1", "campaignname":"campaign number one" ] POST Se usa para crear una nueva campaña o reactivar una campaña archivada. 'id' : (obligatorio) O bien "id" o bien "name" deben ser especificados. Identificador de la campaña. Si se especifica este parámetro, MDirector recuperará la campaña archivada asociada y volverá a ponerla en estado activo. Si no existe campaña con este identificador o ya está activa, MDirector devolverá un error. Ejemplo de respuesta: "response":"ok", "message":"the campaign was successfully enabled back" 'name' : (obligatorio) O bien "id" o bien "name" deben ser especificados. El nombre para la campaña. Si se especifica este parámetro, MDirector creará una nueva campaña con este nombre. Ejemplo de respuesta: "response":"ok", "message":"the campaign was successfully created", "data": "camid":"147" PUT Se usa para modificar el nombre de una campaña existente. 'id' : (obligatorio) El identificador de la campaña a modificar. 'name' : (obligatorio) El nuevo nombre para la campaña Ejemplo de respuesta: "response":"ok", "message":"the campaign was successfully modified"

21 DELETE Se usa para archivar una campaña activa. 'id' : (obligatorio) El identificador de la campaña a archivar. Ejemplo de respuesta: "response":"ok", "message":"the campaign was successfully closed."