API REST — autenticación

Toda solicitud a la API REST de Personyze debe autenticarse con una clave de API, transmitida por HTTPS. No hay endpoints públicos ni sin autenticar.

Si aún no la ha leído, empiece por la descripción general e inicio rápido de la API REST para ver la forma general de cada solicitud.

Dónde encontrar su clave de API

En la GUI de administración de Personyze, vaya a Configuración → Integraciones → API. Cada cuenta de Personyze a la que tiene acceso tiene su propia clave — no son intercambiables.

Cómo enviar la clave

Use la autenticación HTTP Basic con el nombre de usuario api y la clave como contraseña. Dos formas habituales de hacerlo:

Atajo de curl — credenciales en la URL

Práctico para pruebas puntuales y scripts de shell:

curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'

Cabecera Authorization — la opción preferida para el código de producción

La mayoría de las bibliotecas cliente HTTP no analizan de forma fiable user:pass@host en las URL, y poner credenciales en la URL las filtra a los registros del servidor web y al historial del navegador. En el código de producción, construya la cabecera Authorization explícitamente:

Authorization: Basic <base64("api:" + API_KEY)>

Curl con cabecera explícita

curl https://app.personyze.com/rest/users/where/internal_id=42 \
     -H "Authorization: Basic $(printf 'api:%s' YOUR_API_KEY | base64)"

Python (requests)

import requests

r = requests.get(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    auth=('api', YOUR_API_KEY),
)
r.raise_for_status()
data = r.json()

JavaScript (fetch)

const r = await fetch(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    { headers: { Authorization: 'Basic ' + btoa('api:' + API_KEY) } }
);
const data = await r.json();

Códigos de error de autenticación

Acceso a varias cuentas / multiinquilino

La clave de API codifica en qué cuenta de Personyze opera la solicitud. La URL del endpoint nunca nombra la cuenta — se deduce de la clave. Para trabajar con varias cuentas desde el mismo cliente, tenga una clave por cuenta y elija la correcta antes de cada solicitud.

Los ID de objeto también son propios de cada cuenta: la acción 42 de la cuenta A no tiene nada que ver con la acción 42 de la cuenta B. Si su código guarda ID de Personyze junto a sus propios datos, conviene que guarde también el ID de la cuenta (o al menos qué clave de API los creó), para poder volver a lanzar después las solicitudes contra la cuenta correcta.

Límite de frecuencia y tiempos de espera

• Las solicitudes rápidas del tracker y del SDK tienen un presupuesto de 10 segundos de ejecución. Las solicitudes más largas se desconectan a la fuerza con un error de tipo 503. La mayoría de las llamadas a la API REST no pasan por esta vía rápida, pero tenga en cuenta que las consultas complejas sobre tablas grandes pueden necesitar una buena indexación para no superar el límite.
• POST /rest/users se limita por cuenta: como máximo una inserción en curso a la vez. Pasado un segundo de espera en la cola, las solicitudes se rechazan con 400 Too many simultaneous requests. Reintente con espera exponencial. (Se documenta con más detalle en la página del objeto users.)
• Los demás endpoints no tienen actualmente límite de frecuencia a nivel de aplicación — pero trate la API como un recurso compartido y evite saturarla desde muchos procesos en paralelo cuando bastarían llamadas secuenciales.

Próximos pasos