API de importación

Connectif permite automatizar importaciones masivas de contactos, productos y cupones mediante la API de Importación.

Caso de uso

Esta API cubre el siguiente caso de uso:

  • Quiero de forma periódica (ej: diaria o semanal) automatizar la sincronización de todos o gran parte de mis contactos o productos.
  • Quiero importar cupones a un set de cupones porque se están agotando.

Operativa

Crear Api Key

Antes de todo, para poder utilizar el API de importación necesitaremos crear una API KEY con los permisos para gestionar importaciones. Para ello nos iremos a API Keys:

mceclip1.png

y crearemos una nueva API Key marcando los permisos para gestionar importaciones:

mceclip3.png

Ahora copiamos el API Key para más tarde utilizarlo en nuestro script de automatización.

Crear Importación

Para crear la importación necesitaremos realizar una petición HTTP POST multipart/form-data. En dicha petición enviaremos el fichero CSV y los diferentes metadata (por ejemplo el delimitador, el tipo de importación, etc...).

El fichero CSV tiene que respetar las siguientes características:

  • Encoding UTF-8
  • Tener la primera línea con las cabeceras.
  • Las cabeceras tienen que coincidir con el identificador de los campos de contactos y productos.
    • Para los contactos podemos ver estos identificadores en Connectif > Campos del contacto:mceclip4.png

Un ejemplo podemos verlo en el siguiente CSV. Este es correcto ya que _email, _name y _points corresponden con los identificadores de los campos de sistema Email, Nombre y Puntos.

_email,_name,_points
john@example.org,John,10
micheal@example.org,Micheal,10
steve@example.org,Steve,20
mark@example.org,Mark,12
carl@example.org,Carl,10
    • Para productos los nombres de los campos coinciden con los documentados en el Modelo de Producto en el artículo Notificar evento de producto visitado.
    • Para cupones tendremos una única cabecera "code". Ejemplo:
code
0WXN3
APwNO
uscCN
3WgVd
OEn57
EWh1F
Lcgai
EiR2n
QedEt
s2J98

Ejemplo

A continuación podemos ver un ejemplo básico de script en Node.js para automatizar la importación de contactos.

const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');

const apiKey = process.env.API_KEY;
const filePath = process.env.FILE_PATH;

async function main() {
    const form = new FormData();
    form.append('type', 'contacts')
    form.append('delimiter', ',')
    form.append('overrideExisting', 'true')
    form.append('updateOnlyEmptyFields', 'false')
    form.append('file', fs.createReadStream(filePath));

    const response = await fetch('https://api.connectif.cloud/imports', {
        method: 'POST',
        headers: {
            'Authorization': `apiKey ${apiKey}`,
            ...form.getHeaders()
        },
        body: form
    });

    if (!response.ok) {
        console.error(response.status, await response.json());
        process.exit(1);
    }

    const { id, total } = await response.json();

    while(true) {
        const getResponse = await fetch(`https://api.connectif.cloud/imports/${id}`, {
            method: 'GET',
            headers: {
                'Authorization': `apiKey ${apiKey}`
            }
        });
        const { success, errors, status } = await getResponse.json();
        console.log(`completed ${success + errors} of ${total}`);

        if (status === 'finished') {
            console.log('Success 🎉 🎉 🎉 🎉 🎉 🎉 🎉');
            process.exit(0);
        }
        await new Promise(resolve => setTimeout(resolve, 2000));
    }
}

main().catch(error => {
    console.error(error);
    process.exit(1);
});

El script crea una importación a partir de un fichero csv cuya ruta se establece por variable de entorno. Tras crear la importación comprueba el estado de la misma cada 2 segundos y termina cuando el estado de la importación es igual a finished

 

F.A.Q.

¿Cual es el tamaño máximo de ficheros a importar?

Los ficheros CSV a importar no pueden superar los 50 MB de tamaño.

¿Cuantas importaciones pueden estar encolada a la vez?

Es posible encolar un máximo de 10 importaciones a la vez. Llegado a este limite habrá que esperar a que una importación se complete para encolar la siguiente.

¿Las importaciones que realizo vía API se pueden consultar desde la aplicación Connectif?

Sí, el motor de importación es el mismo que utiliza la aplicación Connectif. Por lo tanto las importaciones hechas vía API y app están ambas disponibles en el listado de importaciones.

¿Puedo borrar una importación encolada o en progreso?

Actualmente, es posible borrar importaciones solo en los estados finished o error.

 

¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0