# Agregar un prospecto

Este servicio permite agregar un prospecto a la base de datos de una tienda (en PlazaMundial.Net) desde una página Web externa; generalmente una 'landing page'; ya sea a través de una solicitud POST o Ajax.


End point: https://pm.api.induxsoft.net/leads/

## Consumir a través de un formulario HTML
``` html
<form action="https://pm.api.induxsoft.net/leads/" method="post">
    <!--Campos ocultos de control-->
    <input type="hidden" name="storeid" value="EL ID DE TU TIENDA">
    <input type="hidden" name="subject" value="Asunto de ejemplo">

    <!--Redirecciones en caso de éxito o error-->
    <input type="hidden" name="_on_success_redirect" value="exito.html">
    <input type="hidden" name="_on_fail_redirect" value="error.html">

    <!--Campos de datos mínimos requeridos-->
    <label>Nombre:</label>
    <input type="text" name="name" >

    <label>Correo electrónico:</label>
    <input type="text" name="email" >

    <label>Teléfono:</label>
    <input type="text" name="phone" >

    <!--Envío del formulario-->
    <button type="submit">Enviar</button>
</form>
```

Si consume el servicio desde un formulario HTML, debe especificar una URL de redirección para el éxito o el fracaso
definiendo los campos ocultos ```_on_success_redirect``` y ```_on_fail_redirect``` respectivamente.

Las url de redirección pueden incluir datos del registro usando marcadores de posición en la forma ```@nombre_del_campo```, por ejemplo para
redirigir cuando se ha agregado el prospecto e incluir en la URL su clave primaria y nombre indicado use: 
```
https://miurldesalida.tld/?clave_primaria=@sys_pk&nombre=@name
```

Se le sugiere validar las entradas del usuario a través de Javascript antes de enviar el formulario.

## Consumir a traves de AJAX
```
Method: POST
Content-Type: application/json;charset=utf-8
{
  "storeid":"Id de la tienda",
  ... datos del prospecto ...
}
```

Cuando se consume el servicio al estilo AJAX, se agrega el encabezado HTTP ```Access-Control-Allow-Origin: *``` a la respuesta para que pueda utilizarlo directamente desde el código Javascript de la página en su propio dominio.

El contenido de la respuesta HTTP en caso de éxito consistirá en los datos del prospecto agregado, similar a:

```
Content-Type: application/json;charset=utf-8
{
  ... datos del prospecto ...
}
```

En caso de error, se devolverá el código de estado HTTP 500 (Error interno del servidor) y en el cuerpo estará disponible el mensaje explicativo provisto por el servicio.

## Campos disponibles

Los datos (campos) del prospecto requeridos son:

* subject. Cadena con el asunto o título del prospecto
* name. Cadena con el nombre del prospecto
* email. Cadena con el correo electrónico del prospecto

Los siguientes campos son opcionales:

* recived. Cadena de fecha y hora en formato yyyy-MM-ddThh:mm:ss que corresponde a le fecha y hora de recepción del prospecto
* next_contact. Cadena de fecha y hora en formato yyyy-MM-ddThh:mm:ss que corresponde a le fecha y hora del próximo contacto programado
* agent_id. Cadena con el Id del perfil del agente (colaborador) al que está asignado el prospecto
* lead_status. Numérico con la clave del estado en el que está el prospecto.
* remarks. Cadena con los comentarios o mensaje del prospecto
* color. Numérico que indica el color asignado al prospecto (0-Blanco, 1-Rojo, 2-Verde, 3-Azul, 4-Morado y 5-Amarillo)
* phone. Cadena con el número telefónico del prospecto
* organization. Cadena con el nombre de la empresa u organización del prospecto
* position. Cadena con el nombre del puesto del prospecto en la organización

Ejemplo para agregar un prospecto

Solicitud 
```
Method: POST
Content-Type: application/json;charset=utf-8
{
  "storeid":"Id de la tienda o una clave de API de una tienda",
  "name":"Juan López",
  "email":"correodejuan@servidordejuan.com",
  "phone":"5555555555",
  "subject":"prueba",
  "remarks":"Algún mensaje de prueba",
  "organization":"Empresa de juan",
  "position":"Puesto de juan en su empresa"
}
```

Respuesta

```
Content-Type: application/json;charset=utf-8
{
    "sys_pk": 168726,
    "sys_dtcreated": "2022-03-16T13:20:05",
    "sys_timestamp": "2022-03-16T13:20:05",
    "sys_guid": "9f0d74762562407da30b73ce2148832b",
    "recived": "2022-03-16T13:20:05",
    "next_contact": "",
    "last_contact": "",
    "last_attempt": "",
    "agent_id": "",
    "leadstatus": 0,
    "subject": "prueba",
    "color": 0,
    "name": "Juan L\u00F3pez",
    "email": "correodejuan@servidordejuan.com",
    "phone": "5555555555",
    "organization": "Empresa de juan",
    "remarks": "Alg\u00FAn mensaje de prueba",
    "position": "Puesto de juan en su empresa",
}
```

### Campos adicionales

Si un formulario requiere indicar campos adicionales (que no están considerados como parte de un lead), es posible concatenarlos como pares 'clave/valor'
en el campo 'remarks' si el 'name' del 'input' html inicia con el caracter ```:```.

Por ejemplo:

```html
...
<select name=":empleados" required>
  <option value="micro">Menos de 10 empleado"</option>
  <option value="pequeña">Más de 10 y hasta 50 empleados"</option>
  ...
</select>
```

En el código anterior, el campo "Comentarios" del lead tendría concatenado al final algo como 'empleados:pequeña' si el usuario eligió esa opción.

## Paso de parámetros a la redirección

Una vez que se ha completado el registro del Lead, la URL indicada en el campo oculto _on_success_redirect puede modificarse con los valores
del elemento insertado si se usa un caracter ```@``` antepuesto al nombre de un campo.

Por ejemplo:

```html
...
<input type="hidden" name="_on_success_redirect" value="/pagina-de-exito/?lead=@sys_guid">

```

Redigirigiría a la URL ```/pagina-de-exito/?lead=xyz``` si la SYS_GUID del nuevo lead fuese 'xyz'