Contactos

Tus contactos son lo más importante: los suscriptores de tus newsletters, los compradores de tus productos, los seguidores de tu blog, los fans de tu marca.

A través del nuevo API de Perfit, vas a poder gestionar contactos de forma sencilla, integrando a tu sitio el alta de contactos y la administración de listas para, por ejemplo, agregar un contacto a tu base cada vez que recibís un comentario en tu blog.

¿Cómo hacerlo? Vamos a verlo a continuación.

Agregar un contacto

Así como podés agregar un contacto de forma manual a través del Panel de Control de Perfit, podés hacerlo a través del API.

Para crear un elemento, utilizamos un pedido de tipo POST a contacts enviando los siguientes parámetros:

  • firstName: Nombre del contacto. Por ejemplo, “Juan”.
  • lastName: Apellido del contacto. Por ejemplo, “Perez”.
  • email: Email del contacto. Por ejemplo, “juanperez@empresa.com”

Recordá que para poder utilizar el API, tu usuario debe estar autenticado y tener un token válido, que deberás incluir en la llamada. El ejemplo completo quedaría así:

$contact = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/contacts',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n" .
                    "X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s",
        'content' => http_build_query([
            'firstName' => 'Juan',
            'lastName' => 'Perez',
            'email' => 'juanperez@empresa.com'
        ])
    ]])
);
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    headers: {
        'X-Auth-Token': 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    data: {
        firstName: 'Juan',
        lastName: 'Perez',
        email: 'juanperez@empresa.com'
    },
    success: function (response) {
        var data = response.data;
    }
});

En caso de haber enviado los datos correctamente, el API nos responderá con un status 201 Created y un contenido como el siguiente:

{
    "href": "/cuenta1/contacts",
    "success": true,
    "data": {
        "id": 2,
        "email": "juanperez@empresa.com",
        "firstName": "Juan",
        "lastName": "Perez",
        "gender": "",
        "language": "",
        "preferredFormat": "HTML",
        "source": "MANUAL",
        "state": "ACTIVE",
        "quality": 0,
        "lastMailed": null,
        "lastAction": null,
        "created": "2015-04-30T13:48:40.924+0000",
        "inactivated": null,        
        "customFields": [],
        "interests": [],
        "lists": []
    }
}

En la respuesta podemos encontrar los datos de nuestro nuevo contacto, dentro del parámetro data. Como ven, tiene el email, nombre y apellido que definimos. Aún no tiene listas, intereses ni campos personalizados: veremos esos detalles más adelante.

Además, nos encontramos con un dato muy importante: su ID, un número que lo identifica a un elemento de forma unívoca y permanente. Un ID nunca cambia, por más que actualicemos los datos del contacto (ya sea desde el API o desde el Panel de Control). Un ID nunca se repite, siempre refiere a un sólo elemento. Por lo tanto, nos vá a servir para indicar sobre qué usuario queremos trabajar si queremos hacer cambios (por ejemplo, modificar su nombre).

También se incluyen en la respuesta todos los valores por defecto de los demás campos del contacto.

Campos

Tus contactos pueden contener mucha información además de su email y nombre. Podés completar los siguientes campos:

  • firstName y lastName: Nombre y apellido del contacto, respectivamente. Muy útil para usar como variable de reemplazo al personalizar tus envíos.
  • gender: Sexo del contacto. Las opciones posibles son M, F o vacío.
  • language: El idioma del contacto. Puede ser: de (alemán), en (inglés), es (español), fr (frances), it (italiano), pt (portugués), o vacío. Este campo es muy útil al enviar campañas internacionales, con un contenido diferente según idioma.
  • preferredFormat: Formato preferido del contacto. Las opciones son TEXT o HTML. En la actualidad, casi todos los clientes de correo soportan HTML sin problemas. Pero, en casos especiales, se puede definir TEXT para que las campañas lleguen como sólo texto.

Además, al leer la información de un contacto podrás encontrar campos que el sistema asigna de forma automática y no son editables:

  • id: El ID del Contacto
  • state: El estado del contacto. Puede ser ACTIVE, BOUNCED, UNSUBSCRIBED o COMPLAINED.
  • quality: La calificación del contacto, expresada de 0 a 1.
  • lastMailed: Fecha de último envío al contacto.
  • lastAction: Fecha de última acción del contacto.
  • created: Fecha de creación del contacto.
  • inactivated: Fecha de inactivación del contacto (desuscripción, queja o rebote).
  • source: Fuente de ingreso del contacto. Las opciones son MANUAL, OPTIN_FORM, IMPORTED_CSV, IMPORTED_YAHOO, IMPORTED_GMAIL, IMPORTED_EXCEL.

Podés agregar más información sobre cada contacto utilizando campos personalizados, como veremos más adelante.

Listar contactos

Para obtener un listado de todos los contactos de nuestra base, debemos hacer un pedido GET a contacts. De esa forma, obtendremos los datos de todos los contactos de nuestra base, tanto los que hayan sido creados a través del Panel de Control como del API.

En el listado de contactos no se incluye la información sobre suscripciones a listas e intereses. Por defecto, sólo se incluyen el id y el email. Para que la respuesta incluya más campos, se deben indicar mediante el parámetro fields, separando por coma los campos necesarios, o indicando _all para obtener todos los campos estándar. Para incluir también campos personalizados en la respuesta, se debe indicar customfields[id], siendo id el id del campo personalizado, o customfields[_all] para incluir a todos los existentes.

Veamos un ejemplo:

$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s',
        fields: 'firstName,lastName,customfields[10]'
    },
    success: function (response) {
        var data = response.data;
    }
});

La respuesta sería similar a la siguiente:

{
    "href": "/cuenta1/contacts",
    "success": true,
    "paging": {
        "offset": 0,
        "limit": 20,
        "results": 2,
        "total": 2
    },
    "data": [
        {
            "id": 1,
            "email": "albertogomez@empresa.com",
            "firstName: "Alberto",
            "lastName: "Gomez",
            "customFields": [
                {
                    "id": 10,
                    "value": "Buenos Aires"
                }
            ]
        },
        {
            "id": 2,
            "email": "juanperez@empresa.com",
            "firstName: "Juan",
            "lastName: "Perez",
            "customFields": [
                {
                    "id": 10,
                    "value": "Rosario"
                }
            ]
        }
    ]
}

¡Perfecto! En data encontraremos un array de contactos, cada uno conteniendo datos similares a los que obtuvimos al darlo de alta.

Ahora podemos continuar nuestro código recorriendo el listado de contactos que nos devuelve el API y, por ejemplo, crear una tabla mostrando los resultados:

<?php
$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts?fields=firstName,lastName',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);

$contacts = json_decode($contacts, true);
?>
<!DOCTYPE HTML>
<html lang="en-US">
<head>
    <title>Contactos</title>
</head>
<body>
    <table>
        <tr>
            <th>Nombre</th>
            <th>Apellido</th>
            <th>Email</th>
        </tr>
        <?php foreach ($contacts['data'] as $contact):?>
            <tr>
                <td><?=$contact['firstName']?></td>
                <td><?=$contact['lastName']?></td>
                <td><?=$contact['email']?></td>
            </tr>
        <?php endforeach; ?>
    </table>
</body>
</html>
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s',
        fields: 'firstName,lastName'
    },
    success: function (response) {
        var html = '<table>';
        $.each(response.data, function (index, contact) {
            html += '<tr><td>' + contact.firstName + '</td><td>' + contact.email + '</td></tr>';
        });
        html += '</table>';
        $('body').html(html);
    }
});

Opciones de paginación

Por defecto, el listado devuelve los primeros 20 resultados. Si queremos obtener los siguientes 20, debemos especificar el parámetro offset, un número que indica a partir de qué elemento queremos empezar a listar. Para obtener la segunda página, offset debería ser 20. Para obtener la tercera, offset debería ser 40, y así sucesivamente.

$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts?offset=20',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        offset: 20,
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Si queremos obtener más resultados por página, debemos indicar el parámetro limit. Si en lugar de obtener 20 resultados por página queremos obtener 100, podemos indicarlo de esta forma:

$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts?limit=100',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        limit: 100,
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Al enviar tanto offset como limit, podemos definir el paginado que querramos para nuestros listados.

Opciones de ordenamiento

Cada módulo del API tiene un órden por defecto. En el caso de los contactos, se ordena por el campo email. Para listar los contactos en un orden diferente, podemos indicar los parámetros sortby (el campo por el cual queremos ordenar) y sortdir (el sentido en el que queremos ordenar, siendo asc para ascendente o desc para descendente).

En el caso de los contactos, podemos ordenar por email o quality.

Veamos un ejemplo:

$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts?sortby=quality&sortdir=desc',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        sortby: 'quality',
        sortdir: 'desc',
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Opciones de filtrado

Además, tenemos disponibles opciones para filtrar nuestra base. Por ejemplo, quizás necesitamos ver sólo los contactos desuscriptos, o sólo aquellos cuyo dominio es “gmail.com”. Para eso podemos utilizar los filtros.

En el listado de contactos, tenemos los siguientes filtros disponibles:

state

Para filtrar por estado. Sus valores pueden ser:

  • active: contactos activos
  • unsubscribed: contactos que se hayan desuscripto
  • complained: contactos que han marcado alguna campaña como SPAM
  • bounced: contactos cuya dirección de correo ha rebotado alguna campaña
  • inactive: contactos inactivos (incluye unsubscribed, complained y bounced)

domain

Para filtrar por el dominio de la dirección de email del contacto. Por ejemplo, si indicamos “gmail.com” obtendremos todos los contactos que tienen un email de Gmail.

interest

Para filtrar por interés. Se indica el ID del interés deseado.

list

Para filtrar por lista. Se indica el ID de la lista deseada.

Los filtros deben enviarse dentro de un array llamado filter. A continuación, veamos un ejemplo con algunos de estos filtros:

$contacts = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/contacts?filter[state]=active&filter[domain]=gmail.com&filter[list]=1',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts',
    data: {
        filter: {
            state: 'active',
            domain: 'gmail.com',
            list: 1
        },
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Los filtros son acumulativos, por ende, en este caso obtendremos todos los contactos de Gmail cuyo estado sea activo y pertenezcan a la lista 1.

Modificar un contacto

Para modificar un contacto, debemos hacer una llamada de tipo PUT a contacts seguido del ID del contacto. Es decir, si queremos modificar el contacto 2, la URL completa sería la siguiente:

https://api.myperfit.com/v2/cuenta1/contacts/2

Debemos indicar los campos que querramos actualizar. Los campos que no se indiquen no serán modificados. Por ejemplo, podemos cambiar el apellido y agregar el género de nuestro contacto:

$contact = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/contacts/2',
    false,
    stream_context_create(['http'=> [
        'method'=> 'PUT',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n" .
                    'X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s',
        'content' => http_build_query([
            'lastName' => 'Perez Alvarez',
            'gender' => 'M'
        ])
    ]])
);
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts/2',
    headers: { X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s' }
    data: {
        method: 'PUT',
        lastName: 'Perez Alvarez',
        gender: 'M'
    },
    success: function (response) {
        var data = response.data;
    }
});

Como respuesta, recibiremos el id y los campos que hayan sido actualizados:

{
    "href": "/cuenta1/contacts/2",
    "success": true,
    "data": {
        "id": 2,
        "lastName": "Perez Alvarez",
        "gender": "M",
    }
}

La dirección de email es el único campo que no puede ser modificado una vez creado el contacto. En caso de cometer un error se debe eliminar el contacto y crear uno nuevo.

Eliminar un contacto

Para eliminar un contacto, debemos hacer una llamada de tipo DELETE a las misma URL. No hace falta indicar ningún parámetro, solamente nuestro token. ¡Tené en cuenta que esta operación no se puede deshacer!

$contact = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/contacts/2',
    false,
    stream_context_create(['http'=> [
        'method'=>'DELETE',
        'header' => 'X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    ]])
);
$.ajax({
    type: 'DELETE',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts/2',
    headers: { X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s' },
    success: function (response) {
        var data = response.data;
    }
});

Como respuesta, recibimos una confirmación de la eliminación:

{
    "href": "/cuenta1/contacts/2",
    "success": true
}

Si luego de eliminarlo, se vuelve a crear un nuevo contacto con el mismo email, se conservará su estado anterior. Por ejemplo si estaba desuscripto, por más que lo eliminemos y volvamos a crear, seguirá en ese mismo estado.