La API REST de Personyze es la forma en que las aplicaciones de terceros leen y modifican datos de su cuenta: perfiles de clientes, catálogos de productos y de artículos, placeholders, acciones, listas de audiencia, resúmenes diarios de informes — los mismos datos con los que trabaja la GUI de Personyze. Usa HTTPS estándar, acepta y devuelve JSON, y admite los cuatro verbos estándar (GET, POST, PUT, DELETE).
Esta página es el punto de partida. Para la configuración completa paso a paso, consulte Autenticación. Para la sintaxis de los parámetros de ruta (el patrón where/columns/order_by/limit que recorre todos los endpoints), consulte Parámetros de ruta. Para las listas de columnas y los métodos admitidos por cada objeto, consulte la Referencia de objetos.
Inicio rápido
Obtener el usuario con el ID interno 42:
curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'Esa es toda la forma de cada solicitud:
https://api:<API_KEY>@app.personyze.com/rest/<object>[/<modifier>/<value>...]- Solo HTTPS. El HTTP sin cifrar recibe
401 Unauthorized— incluso con proxies enlocalhosto de desarrollo. - Autenticación HTTP Basic con el nombre de usuario
apiy su clave de API como contraseña (o pásela en línea, como en el ejemplo decurlde arriba). - Todos los argumentos de la ruta se decodifican como URL antes de analizarlos — los valores de columna que contienen
/,=,&, o%deben codificarse con porcentajes.
Métodos HTTP
| Método | Finalidad | Cuerpo | Devuelve |
|---|---|---|---|
GET |
leer | ninguno | Array de registros (o un solo registro en la forma de un solo id) |
POST |
crear | Objeto JSON | ID numérico del nuevo registro |
PUT |
actualizar | Objeto JSON | Número de filas afectadas |
DELETE |
eliminar | ninguno | Número de filas afectadas |
POST y PUT : sus cuerpos usan Content-Type: application/json. application/x-www-form-urlencoded se acepta como alternativa para clientes antiguos, pero se prefiere JSON.
Códigos de respuesta
| Código | Significado |
|---|---|
200 OK |
Correcto — el cuerpo depende del método (consulte la tabla de métodos HTTP de arriba). Las columnas de tipo fecha se serializan como YYYY-MM-DD HH:MM:SS; las marcas de tiempo son segundos Unix en UTC. |
400 Bad Request |
Se ha rechazado su entrada. El cuerpo es una descripción legible en texto plano (p. ej. «Cannot do this operation on whole table: column ‘uset_id’ is not indexed.»). Causas habituales: una errata en el nombre de una columna, falta la cláusula where en una tabla grande, un cuerpo JSON mal formado. |
401 Unauthorized |
Clave de API incorrecta o ausente, o la solicitud no se hizo por HTTPS. |
500 Internal Server Error |
Fallo inesperado en la API — el mensaje va en el cuerpo. Vale la pena reintentarlo al cabo de unos segundos; si persiste, contacte con soporte. |
503 Service Unavailable |
Fallo transitorio (bloqueo mutuo, conexión perdida con la base de datos, etc.). Se puede reintentar con espera progresiva. |
Convenciones comunes a los endpoints
id frente a internal_id
La mayoría de los objetos exponen dos identificadores:
id— la clave primaria numérica interna de Personyze, asignada automáticamente al insertar. Estable para siempre, pero solo tiene sentido dentro de Personyze.internal_id— el identificador externo que usted aporta (el SKU de su e-commerce, el ID de usuario de su CRM, etc.). Se expone en los objetos en los que importa la correspondencia con un sistema externo:users,products,articles.
En la mayor parte del código de integración le conviene usar internal_id — así el mismo código sigue funcionando aunque los mismos datos se vuelvan a importar en Personyze con nuevos ids.
Columnas indexadas obligatorias en las tablas grandes
Los endpoints que envuelven tablas grandes (users, events, sessions_archive, summary_actions, etc.) rechazan los recorridos de tabla completa. Debe incluir una cláusula where o un order_by sobre una columna indexada. Los mensajes de error indican las columnas o combinaciones indexadas disponibles — consulte Parámetros de ruta → Requisito de columna indexada para ver todas las reglas.
Índices compuestos
Los índices compuestos aparecen en los mensajes de error como [col1, col2, col3]. Solo la columna inicial de un índice compuesto se puede usar como filtro de una sola columna. Las demás columnas solo resultan útiles combinadas con la columna inicial.
Las claves de API son por cuenta
Cada cuenta de Personyze a la que tiene acceso tiene su propia clave de API — no son intercambiables. Cambiar de cuenta significa cambiar de clave.
Límites y paginación
- Máximo de 1.000 filas por solicitud. Use
limit/<count>olimit/<offset>,<count>para controlar el tamaño de la página. - Es preferible la paginación por cursor a los desplazamientos profundos. Recorrer la columna indexada de
order_bycon condicioneswherede tipo cursor es mucho más rápido que usar valores altos deoffset, que vuelven a leer todas las filas omitidas.
where en lugar de paginar por desplazamiento. Por ejemplo, después de obtener 1.000 usuarios ordenados por last_session_time de forma descendente, la página siguiente debe usar where/last_session_time<<last_seen_value> en lugar de limit/1000,1000.Más a fondo
curl/Python/JS, y acceso a varias cuentas. Leer →where / columns / order_by / limit con todos los operadores y la composición AND/OR. Leer →Guías relacionadas
- Configuración por tipo de sitio — seguimiento, feeds e integraciones — elija su punto de partida según el tipo de sitio.
- Guía de la acción JavaScript — para escribir acciones personalizadas de Personyze que se ejecutan en el navegador.
- Acceder a los datos de campaña en el lado del cliente — leer los ID y las variables de campaña desde JavaScript en la página.