← Guides

Sincronizar contactos con un ERP

Mantén los contactos del CRM sincronizados con tu sistema ERP usando paginación y sincronización incremental.

Requisitos previos

  • Un Service Account (Client ID + Client Secret)
  • Un sistema ERP con API o base de datos de contactos
  • Una tarea programada o cron para ejecutar la sincronización periódicamente

Paso 1: Autenticar

Obtén un token de acceso con las credenciales del cliente:

cURL
curl -X POST https://magnetcustomer.net/realms/platform/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"

Paso 2: Leer contactos con paginación

Usa los parámetros page y limit para recorrer todos los contactos:

cURL
curl "https://minha-empresa.platform-api.magnetcustomer.com/api/contacts?page=1&limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 200
{
  "docs": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "lifeCycle": "customer",
      "fullname": "Joao Silva",
      "email": "joao@empresa.com.br",
      "phones": [{ "number": "11988880000", "typePhone": "cellphone", "ddi": "+55" }],
      "updatedAt": "2026-01-15T14:30:00Z"
    }
  ],
  "total": 1147,
  "pages": 12,
  "page": 1,
  "limit": 100
}

Paso 3: Mapear los campos al formato del ERP

Transforma la estructura de contacto del CRM para que coincida con el esquema de tu ERP:

Node.js
function mapCrmToErp(contact: CrmContact): ErpContact {
  return {
    erpId: contact._id,
    name: contact.fullname,
    email: contact.email,
    phone: contact.phones?.[0]?.number ?? null,
    // Map custom fields
    taxId: contact.customFields?.find(f => f.k === 'cpf')?.v ?? null,
    updatedAt: contact.updatedAt,
  };
}

Paso 4: Sincronización incremental con updatedAt

El listado de contactos no tiene filtro por fecha. Ordena por el cambio más reciente y detente al llegar a un contacto anterior a la última sincronización:

cURL
# Most recently changed first: stop when you reach a contact older than the last sync
curl "https://minha-empresa.platform-api.magnetcustomer.com/api/contacts?page=1&limit=100&sortBy=updatedAt&sortType=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ciclo de sincronización completo (Node.js)

Node.js
import { MagnetCustomer } from '@magnetcustomer/sdk';

const crm = new MagnetCustomer({
  account: 'minha-empresa',
  clientId: process.env.MAGNET_CLIENT_ID,
  clientSecret: process.env.MAGNET_CLIENT_SECRET,
});

async function syncContactsToErp(lastSyncAt?: string) {
  const startedAt = new Date().toISOString();

  for (let page = 1; ; page++) {
    const { data } = await crm.contacts.listContacts({
      page,
      limit: 100,
      sortBy: 'updatedAt',
      sortType: 'desc',
    });

    for (const contact of data.docs ?? []) {
      // Sorted by most recent change: everything from here on was already synced
      if (lastSyncAt && contact.updatedAt <= lastSyncAt) return finish(startedAt);
      await erp.contacts.upsert(mapCrmToErp(contact));
    }

    if (page >= (data.pages ?? 0)) return finish(startedAt);
  }
}

// Persist sync timestamp for next run
async function finish(startedAt: string) {
  await db.set('lastContactSync', startedAt);
}

Siguiente: Aprende a configurar webhooks para recibir las actualizaciones de contactos en tiempo real en lugar de consultar periódicamente.