Campos

Muchas veces necesitás guardar más información sobre tus contactos para segmentar tu base de forma más efectiva, poder identificar contactos más fácilmente y poder personalizar más tus envíos.

Para eso podés hacer uso de los campos personalizados, campos que vos mismo podés definir para completar esa información en todos tus contactos. Por ejemplo: el número de documento de un contacto, su dirección, su teléfono, su fecha de nacimiento, su número de cliente o cualquier otro campo importante que necesites.

Como vimos antes, al crear tu cuenta ya disponés de ciertos campos de los que podés hacer uso, como nombre, apellido, email, género, idioma, etc. Pero, para hacer más precisa la información sobre tus suscriptores, podés crear hasta 200 campos personalizados.

Al crear un campo personalizado, todos los contactos podrán almacenar esa información. Veamos a continuación cómo crear el campo personalizado "Número de cliente" y cómo completar ese dato en un contacto.

Crear un campo personalizado

Para agregar un campo personalizado, enviamos un POST a fields con su name y tag (es decir, el identificador que tendrá al utilizarlo como variable de reemplazo).

$customField = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/fields',
    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([
            'name' => 'Número de cliente',
            'tag' => 'NUMERODECLIENTE'
        ])
    ]])
);
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/cuenta1/fields',
    headers: { X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s' },    
    data: {
        name: 'Número de cliente',
        tag: 'NUMERODECLIENTE'
    },
    success: function (response) {
        var data = response.data;
    }
});

La respuesta que recibiremos será algo así:

{
    "href": "/cuenta1/fields",
    "success": true,
    "data": {
	"id": 13,
	"name": "Número de Cliente",
	"tag": "NUMERODECLIENTE",
	"format": "TEXT",
	"custom": true,
	"readOnly": false
    }
}

Por defecto, el format del nuevo campo es TEXT. Otros valores posibles son INT o DATE.

Una vez que creamos el campo, al pedir la información de un contacto veremos ese dato dentro de customFields como muestra el ejemplo a continuación:

{
    "href": "/cuenta1/contacts/2",
    "success": true,
    "data": {
        "id": 2,
        "email": "juanperez@empresa.com",
        "firstName": "Juan",
        "lastName": "Perez",
        "customFields": [
            {
                "id": 10,
                "name": "Número de cliente",
                "tag": "NUMERODECLIENTE",
                "value": ""
            }
        ]
    }
}

Por supuesto, apenas agreguemos un campo personalizado, éste aparecerá vacío en todos los contactos. Para completarlo, debemos hacer un PUT a contacts seguido del ID del contacto (en este caso /contacts/15) con un array de customFields, indicando en cada uno el id del campo y su nuevo valor en value.

$contact = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/contacts/15',
    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([
            'customFields' => [
                [
                    'id' => 10,
                    'value' => "14593"
                ]
            ]
        ])
    ]])
);
$.ajax({
    type: 'PUT',
    url: 'https://api.myperfit.com/v2/cuenta1/contacts/15',
    headers: { X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s' },        
    data: {
        customFields: {
            id: 10,
            value: '14593'
        }
    },
    success: function (response) {
        var data = response.data;
    }
});

Listar campos

Si queremos generar un listado de todos los campos disponibles para nuestra base, podemos hacer un GET a fields.

$customFields = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/fields?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/fields',
    data: {
        limit: 100,
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Recibiremos una respuesta 200 OK con un listado con todos los campos disponibles. Los primeros 9 corresponden a los campos generales disponibles para todas las cuentas, desde el lugar 10 en adelante se muestran los campos personalizados exclusivos de tu base (podés distinguirlos también por el valor del parámetro custom, que es true).

En este caso, veremos al final del listado el "Número de cliente" que acabamos de crear:

{
    "href": "/cuenta1/fields"
    "success": true,
    "paging": {
        "records": 10,
        "offset": 0,
        "limit": 100
    },
    "data": [    
        {
            "id": 1,
            "name": "Nombre",
            "tag": "FNAME",
            "format": "TEXT",
            "custom": false,
            "readOnly": false
        },
        {
            "id": 2,
            "name": "Apellido",
            "tag": "LNAME",
            "format": "TEXT",
            "custom": false,
            "readOnly": false
        },
        {
            "id": 3,
            "name": "Email",
            "tag": "EMAIL",
            "format": "TEXT",
            "custom": false,
            "readOnly": false
        },
        {
            "id": 4,
            "name": "Sexo",
            "tag": "GENDER",
            "format": "TEXT",
            "custom": false,
            "readOnly": false

        },
        {
            "id": 5,
            "name": "Idioma",
            "tag": "LANGUAGE",
            "format": "TEXT",
            "custom": false,
            "readOnly": false
        },
        {
            "id": 6,
            "name": "Origen",
            "tag": "SOURCE",
            "format": "TEXT",
            "custom": false,
            "readOnly": true
        },
        {
            "id": 7,
            "name": "Formato Preferido",
            "tag": "FORMAT",
            "format": "TEXT",
            "custom": false,
            "readOnly": false
        },
        {
            "id": 8,
            "name": "Creado",
            "tag": "CREATED",
            "format": "DATE",
            "custom": false,
            "readOnly": true
        },
        {
            "id": 9,
            "name": "Modificado",
            "tag": "MODIFIED",
            "format": "DATE",
            "custom": false,
            "readOnly": true
        },
        {
            "id": 10,
            "name": "Número de cliente",
            "tag": "NUMERODECLIENTE",
            "format": "TEXT",
            "custom": true,
            "readOnly": false
        }
    ]
}

Utilizar un campo

Para utilizar un campo personalizado en nuestras campañas, podemos escribir su tag en el cuerpo del email. En cada envío, el tag va a ser reemplazado por la información correspondiente. Por ejemplo:

¡Hola, ${CONTACT:FNAME}!

... sera visto en cada contacto como:

¡Hola, Juan!

Modificar un campo personalizado

Modificar un campo personalizado es muy sencillo. Sólo debemos hacer un PUT a customFields seguido del ID del campo personalizado con el nuevo name o tag.

$customField = file_get_contents(
    'https://api.myperfit.com/v2/cuenta1/fields/11',
    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([
            'name' => 'Código de cliente',
            'tag' => 'CODIGODECLIENTE'
        ])
    ]])
);
$.ajax({
    type: 'PUT',
    url: 'https://api.myperfit.com/v2/cuenta1/fields',
    headers: { X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s' },
    data: {
        name: 'Código de cliente',
        tag: 'CODIGODECLIENTE',
    },
    success: function (response) {
        var data = response.data;
    }
});

Eliminar un campo personalizado

Para eliminar un campo personalizado, debemos hacer un DELETE a la misma URL.

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

¡Cuidado! Al borrar un campo personalizado, la información sobre ese campo que hayamos guardado en cada contacto se perderá. Esta acción no puede recuperarse.