- 1 Documentación API REST DMDS v2 con el código PHP
- 1.1 – Devuelve información de un contacto
- 1.2 – Listar contactos inválidos
- 1.3 – Listar las variables globales y sus valores
- 1.4 – Listar la campañas
- 1.5 – Crear de nuevo o actualizar un contacto
- 1.6 – Invalidar un contacto
- 1.7 – Enviar un correo
- 1.8 – Crear variables globales
- 1.9 – Crear un grupo
- 1.10 – Listar los filtros
- 1.11 – Añadir un número de teléfono a un contacto
- 1.12 – Enviar sms
- 1.13 – Enviar un mensaje en whatsapp con número de teléfono
- 1.14 – Enviar un mensaje en whatsapp con correo electrónico
- 1.15 – Crear un recordatorio de cita
Documentación API REST DMDS v2 con el código PHP
En este tutorial se van a mostrar diferentes ejemplos de como llamar la api rest del DMDS (Data-Mining and Delivery Services) con el código php . Siempre tener en cuenta que método (GET, POST, DELETE, etc) se usa para cada llamada, que encabezados se pasa y la estructura del json que se tiene que formar, en este caso la data, que para diferentes llamadas esta parte será vacía y para otras hay que rellenar este campo con la información necesaria para la llamada que se realiza correctamente.
La ejecución del fichero php se puede hacer de dos maneras simples. La primera es subir este fichero a su dominio y el la url llamar a este. Y la segunda manera es trabajar de forma local, donde hay que configurar el servidor, de manare que se pueden interpretar los archivos php. En el caso de este tutorial, las llamadas se han probado desde la parte local.
Las respuesta de cada llamada se muestra por el navegador.
Importante: recordar que Authorization es propio de cada uno y el nombre del host.
– Devuelve información de un contacto
En esta llamada se realiza con el método GET, con el cual podemos obtener toda la información de un contacto indicando sólo el correo de la persona, de la cual se quiere obtener la información. La información resultante nos muestra como el nombre de la persona, su apellido, las campañas en que ha participado, los grupos a que perteneces, etc..
<?php
$data = array();
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/email');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Listar contactos inválidos
Con esta parte de código se nos va a mostrar todos los usuarios que están inválidos.
<?php
$data = array();
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contactos/invalidos/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Listar las variables globales y sus valores
En la api hay definidas una serie de variables globales. Para ver cuales son estas variables y sus valores podemos ver el siguiente código.
<?php
$data = array();
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/global/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
El resultado que se muestra por el navegador es el siguiente. También en la imagen se ve como llamamos el fichero php.
– Listar la campañas
Con la misma estructura, como listar los contactos inválido o listar las variables globales, podemos lista todas las campañas existentes. Para esto se utiliza el método get.
<?php
$data = array();
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/campania/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Crear de nuevo o actualizar un contacto
Con el siguiente parte de código se puede crear un contacto de nuevo o actualizar uno existente.
La primera variable que se define es el correo electrónico, para entenderlo es como una primary key en la base de datos. Siempre para actualizar algún contacto nos basaremos en su email ya que es único.
También podemos cambiar su nombre, su apellido, etc. Todos los campos que se quieren cambiar.
<?php
$data = array("email"=>"xxxxxx","nombre"=>"xxxx","apellido"=>"xx","sexo"=>"x","edad"=>"xxxxx","invalido"=>"0");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Invalidar un contacto
En la misma actualización de un contacto, se puede invalidar o validar un contacto. Por defecto la variable invalido siempre está en cero. Pero en el caso que un usuario se quiere desuscribir o invalidar, poniendo esa variable a uno, (invalido: 1), nos permite definir que este contacto esta en la lista de los inválido.
<?php
$data = array("email"=>"xxxxxx","nombre"=>"xxxxx","apellido"=>"xxxxx","sexo"=>"x","edad"=>"xx","invalido"=>"1");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Enviar un correo
Para enviar un correo vamos a diferenciar los tipos que queremos enviar. Primero hay dos diferentes llamadas para enviar un correo a uno sólo destinatario y un correo a varios destinatarios. Para eso el cambio es muy básico, cambiar contacto por contactos. Otras dos llamadas se diferencian en enviar un html inline o un html mediante uri.
Llamada genérica
<?php
$data = array("campana_id"=>"xxxxxxxxxxxxxxxxxxxxxxxxxxxx","email"=>true, "contacto"=>array("email"=>"xxxxxx","nombre"=>"xxxxxx","apellido"=>"xxxxxx"));
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/enviar/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
Enviar un correo a uno sólo destinatario con html uri
Para realizar este envío es necesario definir algunos campos, como por ejemplo: el campo de email tiene que ser siempre verdadero, ya que esto nos permite enviar el correo. SI este valor esta en falso, no se podrán enviar mensajes. Otros valores a definir son la id de la campaña y el correo destinatario. Los otros valores como nombre, apellido, asunto son opcionales. En el caso que quiera enviar un html mediante uri, este se añade en la apartad de html_url. En el apartado de headers, recordar definir su valor de autorización.
<?php
$data = array("campana_id"=>"xxxxxxxxxxxxxxxxxxxx","email"=>true, "contacto"=>array("email"=>"xxxxxxxxxm","nombre"=>"xxxxxxxx","apellido"=>"xxxxxx"), "html_url"=>"xxxxxxxxxxxx")
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_one_uri/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxx',
'Content-Length: ' . strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
Enviar un correo a uno sólo destinatario con html inline
La diferencia de la llamada previa esta es como definir el html dentro del código. Hay dos maneras de enviar un correo con html inline.
Una es definir el código html dentro del script:
<?php
$data = array("campana_id"=>"xxxxxxxx","email"=>true, "contacto"=>array("email"=>"xxxxx","nombre"=>"xxxxx","apellido"=>"xxxxx"), "html"=>"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_one_inline/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
Enviar un correo a más de un destinatario con html uri
Para esta llamada vamos a seguir el mismo concepto que para las otras a la hora de enviar un mensaje. En este caso queremos enviar a mucho destinatarios, para esto vamos a definir un array de usuarios que quienes queremos enviar y cambiar contacto por contactos. En el ejemplo que se muestra más abajo, enviamos un correo a dos personas, pero su puede definir muchas más personas.
<?php
$data = array("campana_id"=>"xxxxxxxxx","email"=>true, "contactos"=>array(["email"=>"email1","nombre"=>"xxxxx","apellido"=>"xxxxxx"],["email"=>"email2","nombre"=>"xxxxxx","apellido"=>"xxxxxx"]), "html_url"=>"xxxxxxxxx");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_many_uri/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
Enviar un correo a más de un destinatario con html inline
<?php
$data = array("campana_id"=>"xxxxxxxxxxx","email"=>true, "contactos"=>array(["email"=>"email1","nombre"=>"xxxxxxxxxx","apellido"=>"xxxxxxx"],["email"=>"email2","nombre"=>"xxxxxxx","apellido"=>"xxxxxxxxx"]), "html"=>"<html><head><title>Page Title</title></head><body><h1>This is a Heading</h1><p>This is a paragraph.</p></body></html>");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/send_many_inline/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Crear variables globales
Siempre podemos crear las variables globales. Para la creación vamos a usar el método post, donde le pasamos un variable, cual nos va a indicar el nombre de la variable global.
<?php
$data = array('nombre'=>'loreipsum2', 'valor'=>"43244654");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/global/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Crear un grupo
Como hemos visto anteriormente, cuando creamos o modificamos un usuario podemos asignarle un grupo. Para poder asignar un grupo, hay que ver si este grupo existe, sino existe, podemos crearlo de la siguiente manera.
<?php
$data = array('nombre'=>'loreipsum');
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/grupo/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Listar los filtros
En el sistema de la api, se pueden crear diferentes filtros, que ayudan a especificar los envíos.
Para ver esta lista de filtros existentes, seguimos el código mencionado abajo.
<?php
$data = array();
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/filtros/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: BqSVfREsuYwWGLxE',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Añadir un número de teléfono a un contacto
Con la siguiente llamada, podemos asociar un número de teléfono a un contacto, indicando su email.
<?php
$data = array("email"=>"lxxxxx", "tlf"=>"+xx xxxxxxxxxxxx");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/contacto/telefono/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: xxxxxxxx',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Enviar sms
Con la siguiente llamada, podemos enviar mensajes a un número de teléfono. Indicando el número y el mensaje a enviar.
<?php
$data = array("tlf"=>"+xx xxxxxxx", "msg"=>"Buenas tardes");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/sms/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: BqSVfREsuYwWGLxE',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Enviar un mensaje en whatsapp con número de teléfono
Primero de todo hay que registrar su número de teléfono en Twilio, es un proceso muy fácil y rápido. El proceso consiste en añadir a conctactos el número +14155238886 y en la aplicación de Whatsapp abrir un chat con este número y escribir join charcoal-shark. Si hemos realizado bien este paso, la respues de Twilio es la siguiente:
Para la llamada tenemos que definir, el número que esta registrado en twilio, el paso anterior y el mensaje que se quiere enviar.
Importante: el número de teléfono, todas las cifras tiene que estar juntas.
<?php
$data = array("tlf"=>"+xxxxxx", "msg"=>"Buenas tardes");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-host/v1/envio/whatsapp/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: BqSVfREsuYwWGLxE',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Enviar un mensaje en whatsapp con correo electrónico
De la misma manera que podemos enviar mensajes mediante whatsapp usando número de teléfono, podemos hacer la misma acción sabiendo su correo electrónico. En este paso es importante tener un número asignado a un email, porque si no, no podremos usar esta llamada. Para asignar número de teléfono a un usuario usamos la llamada “Añadir un número de teléfono a un contacto”. Si tenemos esos pasos hechos la llamada consiste en definir el correo a quien se quiere enviar y el mensaje en si.
<?php
$data = array("email"=>"lidiya@planisys.com", "msg"=>"Buenas tardes");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-planicorp.planisys.net/v1/envio/whatsapp/suscripto/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: BqSVfREsuYwWGLxE',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
– Crear un recordatorio de cita
Con la llamada Api que se muestra a continuación, se puede enviar un recordatorio de una cita al usuario. Recordar que previamente el número de teléfono tiene que estar asignado a un correo electrónico, este paso se hace con la llamada “Añadir un número de teléfono a un contacto”.
<?php
$data = array("email"=>"lidiya@planisys.com", "fecha"=>"Abril 26", "hora"=>"11:30");
$data_string = json_encode($data);
$ch = curl_init('https://api-dmds-planicorp.planisys.net/v1/envio/whatsapp/template/appointment/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Authorization: BqSVfREsuYwWGLxE',
'Content-Length: '.strlen($data_string))
);
$result = curl_exec($ch);
echo ($result);
?>
