Sincroniza personas desde tu propia API

La fuente Custom API conecta Polzy con un sistema propio: una herramienta interna de RR. HH., un CRM, una base de datos detrás de una API. Funciona de dos maneras, y puedes usar ambas:

• Lectura (pull). Polzy lee, con la programación que elijas, un endpoint HTTPS que devuelve a tus personas en JSON.
• Envío (push). Tu sistema envía una persona a Polzy en cuanto cambia, firmada con un secreto compartido, y Polzy la aplica al momento.

En ambos casos, la misma asignación de campos convierte tus registros en las personas de Polzy.

Antes de empezar

Necesitas:

• Ser administrador del espacio de trabajo de Polzy, en Team o superior, con Sincronización de personas activada en Configuración → General → Qué hace este espacio de trabajo.
• Un endpoint en internet, servido por HTTPS, que devuelva una lista JSON de personas, y un desarrollador que pueda modificarlo. Polzy no llama a direcciones privadas ni internas.
• Un id único para cada persona. Polzy lo usa para reconocer a las personas de una sincronización a otra.
• Los campos por los que quieres agrupar los resultados, ya añadidos en Polzy.

Un espacio de trabajo sincroniza desde una sola fuente a la vez. Si hay otra fuente conectada, desconéctala primero. Si tu organización aprovisiona personas mediante SCIM, no se puede conectar ninguna fuente; consulta SCIM.

Qué devuelve tu endpoint

Una petición GET a tu endpoint devuelve a las personas, como lista al principio de la respuesta o en una ruta dentro de ella:

{
  "data": {
    "users": [
      {
        "id": "4821",
        "email": "anouk@acme.com",
        "first_name": "Anouk",
        "last_name": "Jansen",
        "phone": "+31612345678",
        "is_active": true,
        "department": "Sales",
        "manager_email": "rahul@acme.com"
      }
    ]
  },
  "meta": { "next_cursor": "eyJwYWdlIjoyfQ" }
}

Aquí, Ruta de datos (JSON) es data.users; si la lista está al principio de la respuesta, déjala vacía. Las rutas también pueden entrar en listas, como results[0].people.

Cada petición tiene 30 segundos para responder. Si tu endpoint pagina, dile a Polzy cómo:

• Con un enlace o un cursor. Escribe el campo que lo contiene en Campo de página siguiente, como meta.next_cursor. Una dirección completa se llama tal cual; un cursor se añade a la dirección de tu endpoint como ?cursor=…, o con el nombre que pongas en Parámetro de página. Polzy se detiene cuando el campo está vacío.
• Con un número de página. Deja vacío Campo de página siguiente y escribe el nombre del parámetro en Parámetro de página, como page. Polzy pide las páginas 2, 3 y así sucesivamente, y se detiene en la primera página vacía.

Polzy lee como máximo 500 páginas por sincronización.

Conecta tu API en Polzy

1. Abre Contactos → Sincronización y campos.
2. En Fuentes disponibles, busca Custom API y elige Conectar. Se abre un panel con tres pasos: Conexión, Ajustes de sincronización y Asignación de campos.
3. Escribe la URL del endpoint de la API y, si los necesitas, la Ruta de datos (JSON) y los campos de paginación.
4. Elige el Tipo de autenticación y rellena lo que pida: un Bearer Token; un Nombre de la cabecera API Key y un Valor de la API Key; un Nombre de usuario y una Contraseña para la Autenticación básica; o nada con Ninguno. Añade cualquier otro encabezado que necesite tu endpoint en Encabezados personalizados.
5. Para el envío, escribe una cadena larga y aleatoria como Secreto de firma de webhooks y da la misma cadena a tu desarrollador. Si no, déjalo vacío.
6. Elige Probar conexión. Successfully connected to API. Found N users. significa que Polzy pudo leer tu endpoint.
7. Elige Siguiente, revisa los ajustes de sincronización, vuelve a elegir Siguiente, asigna los campos (más abajo) y luego elige Conectar.

Sincronización de personas

Conectar Custom API

Las claves se cifran y solo se usan en tu nombre.

2 de 2 obligatorios

ConexiónAjustes de sincronizaciónAsignación de campos

Campo de página siguienteOpcional

Parámetro de páginaOpcional

Secreto de firma de webhooksOpcional

URL del endpoint de la APIObligatorio

Tipo de autenticaciónObligatorio

Bearer TokenOpcional

Cifrado en reposoCancelarProbar conexiónSiguiente

Los tokens, las contraseñas, el secreto de firma y el valor de cada encabezado personalizado se guardan cifrados y solo se usan para llamar a tu endpoint.

Ajustes de sincronización

Que tus personas lleguen como miembros o como contactos depende del público de tu espacio de trabajo: miembros en un espacio para empleados, que pueden iniciar sesión y ocupan plaza; contactos en uno para clientes, usuarios de un producto o asistentes a eventos, que solo responden.

Asigna los campos

La asignación predeterminada lee email, first_name, last_name, phone e is_active. El resto lo asignas tú: activa Asignación de campos personalizada y escribe, para cada campo, la ruta de tus registros que lo rellena: department, manager_email, plan, profile.country. La lista sugiere nombres habituales, y las rutas se escriben igual que en Ruta de datos. Cada fila tiene también un valor Si está vacío, usar, que se escribe cuando un registro no tiene nada para ese campo; un valor que tu API sí envía nunca se sobrescribe.

Sincronización de personas

Conectar Custom API

Las claves se cifran y solo se usan en tu nombre.

ConexiónAjustes de sincronizaciónAsignación de campos

Asignación de campos personalizada

Asignación personalizada activa Elige qué campo de tu sistema de RR. HH. alimenta cada campo de participante.

Campos principales

Campo del participanteDesde la fuenteSi está vacío, usar

Correo electrónicoObligatorio

Ejemplo: anouk@acme.com, rahul@acme.com

NombreObligatorio

Ejemplo: Anouk, Rahul

ApellidoObligatorio

Ejemplo: Jansen, Mehta

Campos del espacio de trabajo

Campo del participanteDesde la fuenteSi está vacío, usar

Departamento

Ejemplo: Ventas, Operaciones

Cifrado en reposoAtrásConectar

Conviene saber:

• Ejemplos reales. Una vez conectado, elige Ajustes en Sincronización y campos y vuelve a abrir Asignación de campos: las sugerencias incluyen entonces todas las rutas de cinco registros reales, cada una con un Ejemplo.
• Estado activo. Un valor false, 0, no, inactive, terminated, leave, disabled, suspended o archived desactiva a la persona; cualquier otro valor, o ninguno, la mantiene activa.
• Responsables. Asigna Responsable a un campo con la dirección de correo, el ID de empleado o el id en tu API del responsable. El vínculo se crea cuando el responsable también está en Polzy. Los responsables necesitan Líneas de reporte activado en el espacio de trabajo.
• Solo se rellenan los campos de tu espacio de trabajo. Añade un campo con Añadir campo en Sincronización y campos antes de asignarlo. Para comparar resultados por él, conviértelo en un campo Lista y activa Grupos.

Previsualiza y lanza la primera sincronización

1. En Sincronización y campos, elige Previsualizar sincronización en Historial de sincronización. Polzy calcula qué añadiría, actualizaría y desactivaría una sincronización, sin cambiar nada, y abre el registro donde el resultado aparece como Vista previa.
2. Revisa la vista previa, corrige la asignación en Ajustes si hace falta y luego elige Sincronizar ahora.

Sincronización y campos

Custom APIConectadoÚltima sincronización hace 5 minutos · se ejecuta cada hora · 152 personas · 9 gruposAjustesSincronizar ahora

Historial de sincronizaciónPrevisualizar sincronización

Hoy, 09:12Correcto2 añadidos · 5 actualizados

Hoy, 08:10Parcial1 actualizado · 3 omitidos

Ayer, 16:40Vista previa152 añadidos

Las personas se emparejan por su id y, después, por dirección de correo, así que alguien a quien ya habías añadido a mano se actualiza en lugar de añadirse dos veces.

Envía los cambios en cuanto ocurren

El envío manda a Polzy una persona cada vez, firmada, siempre que cambia. Las sincronizaciones programadas siguen funcionando a la vez y recogen lo que se haya perdido un envío, así que Polzy sigue necesitando el endpoint de arriba, aunque devuelva una lista vacía.

1. En Polzy, abre Integraciones, luego Custom API, y copia la dirección que aparece en Recepción. Está creada para tu conexión y termina en /api.
2. Comprueba que el mismo secreto está guardado en Secreto de firma de webhooks, en Ajustes, y en tu sistema.
3. Desde tu sistema, envía un POST a esa dirección con la persona en JSON y tres encabezados:

El cuerpo es la persona, con los mismos nombres de campo que devuelve tu endpoint, para que se aplique la misma asignación. También puede ir envuelto como { "user": { … } } o { "employee": { … } }. Debe llevar el id y los campos que han cambiado: un cuerpo con solo un id se acepta pero no cambia nada. Para desactivar a alguien, envíalo con "is_active": false, o con lo que tu asignación lea para Estado activo.

En Node.js:

import crypto from 'node:crypto';

const body = JSON.stringify({
  id: '4821',
  email: 'anouk@acme.com',
  first_name: 'Anouk',
  last_name: 'Jansen',
  department: 'Operations',
  is_active: true,
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', process.env.POLZY_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

await fetch(process.env.POLZY_RECEIVING_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Polzy-Timestamp': timestamp,
    'X-Polzy-Signature': signature,
    'X-Polzy-Event-Id': 'person-4821-2026-10-31T09:12:00Z',
  },
  body,
});

En Python:

import hashlib, hmac, json, os, time, requests

body = json.dumps({"id": "4821", "email": "anouk@acme.com", "department": "Operations", "is_active": True})
timestamp = str(int(time.time()))
signature = hmac.new(
    os.environ["POLZY_SIGNING_SECRET"].encode(),
    f"{timestamp}.{body}".encode(),
    hashlib.sha256,
).hexdigest()

requests.post(
    os.environ["POLZY_RECEIVING_URL"],
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Polzy-Timestamp": timestamp,
        "X-Polzy-Signature": signature,
        "X-Polzy-Event-Id": "person-4821-2026-10-31T09:12:00Z",
    },
)

Firma exactamente los bytes que envías: serializa el cuerpo una sola vez y envía esa misma cadena. Lo que responde Polzy:

Si tu espacio de trabajo está en pausa por superar su plan, las llamadas se confirman pero no se aplica nada.

Llamadas firmadas sin marca de tiempo

La primera versión del envío firmaba solo el cuerpo, sin X-Polzy-Timestamp. Esas llamadas se siguen aceptando por ahora, y mientras tu sistema las envíe, Configuración → API → Webhooks muestra un aviso con la fecha a partir de la cual se rechazarán. Desde esa fecha, Polzy les responde con 401 y Calls without X-Polzy-Timestamp are refused since seguido de esa fecha. Cambia antes a la firma de arriba; consulta Webhooks.

Solución de problemas

Conviene saber

• Límites. Una sincronización que superaría tus plazas o tus contactos importa a las personas que caben, se detiene ahí y avisa a los administradores. Consulta Uso y límites.
• Una persona por envío. Envía una llamada distinta por cada persona que cambie.
• Desconectar o eliminar. En Ajustes, Desconectar detiene la sincronización y conserva los ajustes y el historial, para que puedas volver a conectar más tarde; Eliminar borra la conexión. En ambos casos, las personas ya sincronizadas se quedan en Polzy y dejan de actualizarse, y los envíos se rechazan.
• El resto de la API. Para leer resultados o crear acciones desde tu sistema, usa una clave de API y la referencia de la API.