Para ingresar los datos de contactos o prospectos (en adelante lo llamaremos Lead para simplificar la lectura) producto de formularios completados en sitios de eCommerce como Mercado Libre, De Motores, Autofoco, etc; o en landings o campanas de mailing, Pilot® cuenta con mecanismos automáticos además de permitir la carga manual de los datos vía la interfaz de la aplicación.
Cada "lead" ingresado en Pilot® tiene que cumplir con una determinada estructura de parámetros, los cuales no son todos requeridos:
| Nombre | Se obtiene de la cuenta que envía el mail si es posible | |
| Apellido | Apellido del Lead | |
| Teléfono | teléfono del Lead | |
| Celular | Celular del Lead | |
| Tipo de Contacto | es el medio por el cual se contacta la persona y puede ser: 1- electrónico | 2- telefónico | 3- entrevista | |
| Tipo de negocio | canal de venta: (1) Convencional / 0km | (2) Usados |(3) Plan de Ahorro | |
| Origen | Es un agrupador del identificador de donde se obtiene el Lead. Solo se usa en la interfaz gráfica de Pilot®, y su uso esta deprecado en las interfaces automáticas. | |
| Suborigen | Identifica el origen primario del Lead, la lista de los suborígenes se obtiene de la instancia de cada cliente y se puede ver en el informe de las tablas del sistema llamado "Origen de los datos". | |
| Vendedor Asignado | Indica el vendedor al cual asignar el Lead directamente. Por el momento este parámetro solo se usa en la interfaz gráfica de Pilot®. | |
| Notas | Comentarios u observaciones que deja el Lead en las páginas donde se registra. En el caso de los eCommerce como De Motores, De Autos, Autofoco, Autocosmos, etc envían en este parámetro el interés de la persona (vehículo/financiación/etc). |
Nuestra documentación explica las nociones básicas del uso de llamadas Web/HTTP y Pilot® en particular. Si Ud. no está familiarizado con estas técnicas o no ha trabajado antes con llamadas Web/HTTP, por favor tome un momento para hacerlo antes de comenzar con el trabajo.
https://api.pilotsolution.com.ar/webhooks/welcome.php
IMPORTANTE: cualquier respuesta que no sea status 200 HTTP es un error.
action |
Valor fijo "create" | |
appkey |
Es un valor alfanumérico ej: 9715fc4b-17a8-4e56-ac7a-6deb5fd46u71 que se puede pedir a la cuenta de soporte de Pilot u obtenerlo de la configuración de Pilot. | |
debug |
Código numérico, flag, que permite testear el servicio sin ingresar el Lead en Pilot®. 0 = no debug, se ejecuta el servicio en modo normal. 1 = en modo debug, no se ingresa el Lead en Pilot®. Ej: 0 (no debug) | |
notification_email |
cuenta de mail para recibir una copia del dato ingresado. | |
pilot_firstname |
nombre del Lead | |
pilot_lastname |
apellido del Lead | |
pilot_phone |
teléfono del Lead | |
pilot_cellphone |
teléfono celular del Lead | |
pilot_email |
email del Lead | |
pilot_contact_type_id |
código numérico del tipo de contacto del dato.
1: Electrónico, 2: Telefónico , 3: Entrevista |
|
pilot_business_type_id |
código numérico del tipo negocio del dato.
1: 0km , 2: Usados, 3: Plan de Ahorro |
|
pilot_origin_id |
Deprecado | |
pilot_suborigin_id |
Código numérico del suborigen del Lead, que se obtiene de la lista de orígenes de datos en el módulo de administración Ej: 1 (Landing) | |
pilot_notes |
Notas de Lead | |
pilot_assigned_user |
Cuenta de usuario de Pilot a la que se le quiere asignar el dato. En este caso la asignación manual del dato tiene prelación por sobre los grupos de captura de datos Ej: cuentausuario@dominio.com | |
pilot_car_brand |
Marca del vehículo de interés Ej: Ford | |
pilot_car_modelo |
Modelo del vehículo de interés Ej: Fiesta | |
pilot_city |
Ciudad de ubicación del dato Ej: Capital Federal | |
pilot_province |
Provincia de ubicación del dato Ej: Buenos Aires | |
pilot_country |
País de ubicación del dato Ej: Argentina | |
pilot_vendor_name |
Nombre del proveedor del dato | |
pilot_vendor_email |
Email del proveedor del dato | |
pilot_vendor_phone |
Teléfono del proveedor del dato | |
pilot_product_code |
Código de Producto según la lista de precios de Pilot. Esto hace que el sistema genere automáticamente una oferta de interés para el lead. La lista de productos se puede obtener del endpoint masters/read.php Los productos y códigos pueden variar de mes a mes según el alta o baja de las marcas y la agencia. |
|
pilot_provider_service |
Nombre del servicio que provee el datos. Es un descriptivo del origen. | |
pilot_provider_url |
URL del servicio que recolecto el dato. | |
pilot_client_identity_document |
Documento de Identidad del Lead | |
pilot_tracking_id |
Código de seguimiento | |
pilot_client_ip |
Ip del cliente | |
pilot_best_contact_time |
Horario de contacto preferido del Lead |
OBLIGATORIO
Cada llamada exitosa a la API retorna un mensaje en formato JSON con información de la ejecución del servicio o los errores del mismo. Ejemplo devolución en caso de error:
{
"success":valor boolean - true o false,
"message":mensaje del resultado,
"data":detalle del error
}
Ejemplo:
{
"success":false,
"message":"Error",
"data":"El parametro requerido appkey no fue seteado"
}
Ejemplo de devolución en caso de ejecución correcta:
{
"success":valor boolean - true o false,
"message":mensaje del resultado,
"data":{
"message": resultado,
"assigned_user_id": id del usuario Pilot asignado. Si no se asigna el tag no es enviado,
"success":valor boolean - true o false indica que se inserto en la base correctamente,
"id": identificador del dato dado de alta. Es un valor numerico
}
}
Ejemplo:
{
"success":true,
"message":"Success",
"data":{
"message":"(3.2) El servicio de carga de datos se ejecuto correctamente.",
"assigned_user_id":80,
"success":true,
"id":8855
}
}
Copiar y pegar el siguiente código en un archivo con extensión .PHP
Luego modificar los parámetros de configuración y probar con un formulario que tenga como acción esta página
También puedes bajar un ejemplo de código de formulario para agregar la creatividad aquí
Bajar código<?php //VARIABLES DE CONFIGURACION $serviceURL = "https://api.pilotsolution.com.ar/webhooks/welcome.php"; $appKey = "aqui la key de la instancia correspondiente"; $tipoNegocio = "1"; $origendeldato = "7A2E4184"; $landing_link = "Landing Promo Mes"; //CAPTURA DE PARÁMETROS que pueden venir de un formulario $encoded = ""; $encoded .= urlencode('action').'=create&'; $encoded .= urlencode('appkey').'='.urlencode($appKey).'&'; $encoded .= urlencode('pilot_firstname').'='.urlencode(request("nombre",false,"n/a")).'&'; $encoded .= urlencode('pilot_lastname').'='.urlencode(request("apellido",false,"")).'&'; $encoded .= urlencode('pilot_phone').'='.urlencode(request("telefono",false,"n/a")).'&'; $encoded .= urlencode('pilot_cellphone').'='.urlencode(request("celular",false,"")).'&'; $encoded .= urlencode('pilot_email').'='.urlencode(request("email",false,"")).'&'; $encoded .= urlencode('pilot_contact_type_id').'='.urlencode('1').'&'; //electronico $encoded .= urlencode('pilot_business_type_id').'='.urlencode($tipoNegocio).'&'; $encoded .= urlencode('pilot_notes').'='.urlencode(request("comentarios",false,"Sin comentarios");).'&'; $encoded .= urlencode('pilot_suborigin_id').'='.urlencode($origendeldato).'&'; $encoded .= urlencode('pilot_provider_url').'='.urlencode($landing_link).'&'; $ch = curl_init($serviceURL); curl_setopt($ch, CURLOPT_FAILONERROR, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $encoded); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $output = curl_exec($ch); curl_close($ch); echo $output; die() ; // Levanta los parámetros por post o get function request($param, $required=true, $default="") { $result = $default; //veo si esta seteado el parametro POST if (isset($_POST[$param])) { if($_POST[$param]!="") { $result = $_POST[$param]; } else { if ($required) { throw new Exception("El parametro requerido ".$param." no fue seteado"); } } } else if(isset($_GET[$param])) { if($_GET[$param]!="") { $result = $_GET[$param]; } else { if ($required) { throw new Exception("El parametro requerido ".$param." no fue seteado"); } } } else { if ($required) { throw new Exception("El parametro requerido ".$param." no fue seteado"); } } return $result; } ?>
El formato del mail es un ADF (xml de información) que tiene el siguiente contenido. En este caso la información que se puede enviar en el mail es más amplia y con mayor información.
Formato del mail: preferentemente texto plano.
Los datos consignados son a modo de ejemplo para que se entienda el contenido.
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf>
<prospect>
<requestdate>2013-06-27 11:26:24</requestdate>
<vehicle>
<brand>PEUGEOT</brand>
<model>207</model>
</vehicle>
<customer>
<contact>
<name part="full">nombre complete del prospecto</name>
<name part="first">nombre</name>
<name part="last">apellido</name>
<email>mail@domionio.com</email>
<phone>1147899000</phone>
<cellphone>1160403456</cellphone>
<address>
<city>Cuidad Autónoma de Buenos Aires</city>
<province>Buenos Aires</province>
<country>Argentina</country>
</address>
</contact>
<comments>
<![CDATA["Estoy interesado en comprar un Ford Fiesta"]]>
</comments>
</customer>
<vendor>
<contact>
<name part="full"></name>
<email></email>
<phone></phone>
</contact>
</vendor>
<provider>
<name>proveedor de datos</name>
<service>Landing Venta Ford Fiesta</service>
<notification_email></notification_email >
<debug>0</debug>
</provider>
</prospect>
<format>
<formtype>pilot</formtype>
<formversion>1</formversion>
<key></key>
</format>
</adf>
Los parámetros informados en azul son constantes y no deben cambiarse.
Los parámetros informados en verde son opcionales y sirven para ampliar la información para el vendedor
Los parámetros informados en rojo son los básicos del mensaje y son obligatorios
Si algún dato no se envía, el tag tiene que informarse en blanco. O sea, el mensaje debe ser completo
Ej: <make></make>
NOTA: El asunto de el Email no es tenido en cuenta para la integración. Sin embargo te recomendamos usar un asunto que te sirva de referencia para ubicarlo rápidamente en el caso que necesites verlo en la bandeja de entrada.
Descripción de los parámetros del proveedor del Lead.
<name> |
nombre del proveedor del dato |
<service> |
nombre del proveedor del dato |
<name> |
nombre del servicio que originó el dato. Ej: nombre de la landing) |
<notification_email> |
cuenta de mail para recibir una copia del dato ingresado. |
<debug> |
Código numérico, flag, que permite testear el servicio sin ingresar el Lead en Pilot. 0 = no debug, se ejecuta el servicio en modo normal. 1 = en modo debug, no se ingresa el Lead en Pilot. Ej: 0 (no debug) |
<url> |
Es la cuenta que envía el mail |
<?php
enviar_a_Pilot();
die();
function enviar_a_Pilot()
{
$REQUERIDO = true;
$NO_REQUERIDO = false;
$nombre = request("nombre",$REQUERIDO);
$apellido = request("apellido", $NO_REQUERIDO);
$telefono = request("telefono", $NO_REQUERIDO);
$celular = request("celular", $NO_REQUERIDO);
$email = request("email",$REQUERIDO);
$modeloAuto = request("modelo",$NO_REQUERIDO);
$comentarios = "Comentario:".request("comentarios", $NO_REQUERIDO);
$provider = "Nombre del proveedor de datos";
$landing = "Formulario de Contacto Tipo";
$linkLanding = "http://www.misitio.com/landing.php";
$provincia = request("region",$NO_REQUERIDO);
$to = "..."; //esta cuenta se configura en PILOT CRM
$subject = "Nuevo conctacto de ".$nombre;
$cuerpoDelMail = armarCuerpoDelMail($nombre, $apellido, $telefono, $celular, $email, $modeloAuto, $comentarios, $landing, $linkLanding, $provincia, $provider);
//aqui se puede usar
if (enviarElMail("mi_cuenta@mail.com", $to, $subject, $cuerpoDelMail)){
echo "Su consulta fue enviada satisfactoriamente.";
}else{
echo "No hemos podido enviar su consulta. Intente más tarde por favor.";
}
return true;
}
// Levanta los parámetros por post o get
function request($param, $required=true, $default="")
{
$result = $default;
//veo si esta seteado el parametro POST
if (isset($_POST[$param])) {
if($_POST[$param]!="")
{
$result = $_POST[$param];
} else {
if ($required)
{
throw new Exception("El parametro requerido ".$param." no fue seteado");
}
}
}
else if(isset($_GET[$param]))
{
if($_GET[$param]!="")
{
$result = $_GET[$param];
} else {
if ($required)
{
throw new Exception("El parametro requerido ".$param." no fue seteado");
}
}
}
else
{
if ($required)
{
throw new Exception("El parametro requerido ".$param." no fue seteado");
}
}
return $result;
}
//Funcion para el envio de mails
function enviarElMail($de, $para, $asunto, $cuerpodelmail)
{
//aqui implementar la funcion de envio de mail que se disponga en el servidor.
}
//Esta funcion retorna el contenido del cuerpo del mail con los valores ya reemplazados
function armarCuerpoDelMail($nombre, $apellido, $telefono, $celular, $email, $modeloAuto, $comentarios, $landing, $linkLanding, $provincia, $provider)
{
$result = '
<?xml version="1.0" encoding="UTF-8"?>
<?adf version="1.0"?>
<adf>
<prospect>
<requestdate>'.date("Y-d-m H:i:s").'</requestdate>
<vehicle>
<id></id>
<year></year>
<make>RENAULT</make>
<model>'.$modeloAuto.'</model>
<vin></vin>
<stock></stock>
<trim></trim>
<price type="asking"></price>
</vehicle>
<customer>
<contact>
<name part="full"></name>
<name part="first">'.$nombre.'</name>
<name part="last">'.$apellido.'</name>
<email>'.$email.'</email>
<phone>'.$telefono.'</phone>
<cellphone>'.$celular.'</cellphone>
<international_phone></international_phone>
<address>
<street></street>
<city>'.$provincia.'</city>
<regioncode></regioncode>
<postalcode></postalcode>
<country>Argentina</country>
</address>
</contact>
<comments>
<![CDATA["'.$comentarios.'"]]>
</comments>
</customer>
<vendor>
<vendorname></vendorname>
<contact>
<name part="full"></name>
<email></email>
<phone></phone>
</contact>
</vendor>
<provider>
<name>'.$provider.'</name>
<service>'.$landing.'</service>
<notification_email></notification_email >
<debug>0</debug >
<url><![CDATA["'.$linkLanding.']]></url>
</provider>
</prospect>
<format>
<formtype>pilot</formtype>
<formversion>1</formversion>
<key></key>
</format>
</adf>';
return $result;
}
?>