API REST
Con la API puedes crear píxeles desde tu CRM, tu herramienta de email o tus scripts, y consultar sus aperturas y estadísticas sin entrar en el panel. Está incluida en el plan Pro.
URL base
https://pixhook.io/api/index.php?/api/v1/public
Cada endpoint se añade a continuación, por ejemplo …/public/pixels.
Como la URL base ya lleva ?, los parámetros se añaden con &:
https://pixhook.io/api/index.php?/api/v1/public/pixels&page=2&limit=50
Formato
- Peticiones y respuestas en JSON (
Content-Type: application/json). - Las respuestas correctas son
{"success": true, "data": …}; los listados añadenpagination. - Las fechas van en UTC con formato ISO 8601 (
2026-10-20T20:03:04Z). Los filtrosdate_fromydate_tousanAAAA-MM-DDy también se interpretan en UTC.
Autenticación
Crea una clave en Dashboard → API y envíala en la cabecera
X-API-Key en cada petición:
curl "https://pixhook.io/api/index.php?/api/v1/public/account" \
-H "X-API-Key: pt_live_…"
También se acepta Authorization: Bearer pt_live_…. La clave no se acepta en la URL,
porque quedaría guardada en logs de servidores y proxies.
- La clave completa solo se muestra al crearla. Guárdala en un lugar seguro.
- Úsala solo desde tu servidor, nunca en código que se ejecute en el navegador de tus clientes.
- Si se filtra, revócala o regénérala desde el panel: deja de funcionar al momento.
- Puedes tener hasta 3 claves activas, cada una con caducidad opcional.
Permisos
| Permiso | Permite |
|---|---|
pixels:read | Listar y consultar píxeles. |
pixels:write | Crear, modificar y borrar píxeles. |
stats:read | Consultar aperturas, estadísticas y el heatmap. |
Al crear una clave puedes darle solo los permisos que necesite. Por ejemplo, una clave para un panel de informes solo necesita stats:read.
Límites
| Límite | Plan Pro | Si se supera |
|---|---|---|
| Peticiones por minuto (por clave) | 60 | 429 rate_limited con cabecera Retry-After |
| Peticiones al mes (por cuenta) | 10.000 | 429 monthly_quota_exceeded hasta el día 1 |
Cada respuesta incluye el estado de tus límites:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 53
X-RateLimit-Monthly-Limit: 10000
X-RateLimit-Monthly-Remaining: 9988
Los límites de tu plan (número de píxeles, eventos al mes, webhooks…) se aplican igual que en el panel. Si tu suscripción deja de incluir la API, las claves dejan de funcionar hasta que vuelvas al plan Pro.
Errores
Los errores devuelven el código HTTP correspondiente y este formato:
{
"success": false,
"error": {
"code": "conflict",
"message": "Ya tienes un pixel con ese nombre"
}
}
| HTTP | code | Significado |
|---|---|---|
| 401 | missing_api_key | No se ha enviado la cabecera X-API-Key. |
| 401 | invalid_api_key | Clave inexistente, revocada o caducada. |
| 403 | plan_without_api | Tu plan actual no incluye la API. |
| 403 | insufficient_scope | La clave no tiene el permiso necesario. |
| 403 | limit_reached | Has llegado al máximo de píxeles de tu plan. |
| 403 | feature_not_available | La función no está incluida en tu plan. |
| 404 | not_found | El recurso no existe o no es tuyo. |
| 409 | conflict | Ya existe un píxel con ese nombre. |
| 422 | validation_error | Datos no válidos (falta un campo, URL incorrecta…). |
| 429 | rate_limited / monthly_quota_exceeded | Límite de peticiones superado. |
| 500 | server_error | Error interno. Reintenta pasados unos segundos. |
Píxeles
El objeto píxel
{
"id": "a2dd44d0646892e5573342f1471cf0ee",
"name": "Propuesta ACME",
"pixel_url": "https://pixhook.io/api/v1/pixels/a2dd44d0646892e5573342f1471cf0ee/track",
"img_tag": "<img src=\"https://pixhook.io/api/v1/pixels/a2dd…/track\" width=\"1\" height=\"1\" alt=\"\" style=\"display:none\">",
"is_active": true,
"redirect_enabled": false,
"redirect_url": null,
"webhook_enabled": false,
"webhook_url": null,
"email_notifications": false,
"notification_email": null,
"notification_frequency": "daily",
"tags": [],
"total_opens": 0,
"unique_opens": 0,
"last_open_at": null,
"created_at": "2026-11-01T10:45:56Z"
}
Inserta img_tag en el HTML de tu email. Si activas la redirección, usa pixel_url como enlace:
se registra el clic y se redirige a redirect_url.
is_active es false si el píxel quedó desactivado por superar el límite de tu plan.
Lista tus píxeles, del más reciente al más antiguo.
| Parámetro | Descripción |
|---|---|
page | Página (por defecto 1). |
limit | Resultados por página, de 1 a 50 (por defecto 20). |
tag_id | Solo los píxeles con esta etiqueta. |
{
"success": true,
"data": [ { …píxel… } ],
"pagination": { "page": 1, "limit": 20, "total": 7, "total_pages": 1 }
}
Crea un píxel. Responde 201 con el objeto píxel.
| Campo | Descripción |
|---|---|
name * | Nombre del píxel. No puede repetirse en tu cuenta. |
redirect_enabled | true para usar el píxel como enlace con redirección. |
redirect_url | URL http(s) de destino. |
webhook_enabled | true para avisar a tu servidor en cada apertura. |
webhook_url | URL http(s) pública que recibirá el aviso. |
email_notifications | true para recibir resúmenes por email. |
notification_email | Email de los resúmenes. Si no es el de tu cuenta, recibirá un enlace de confirmación. |
notification_frequency | daily o weekly. |
curl -X POST "https://pixhook.io/api/index.php?/api/v1/public/pixels" \
-H "X-API-Key: pt_live_…" \
-H "Content-Type: application/json" \
-d '{"name": "Propuesta ACME"}'
Si el webhook no se puede activar por el límite de tu plan, el píxel se crea sin él y la respuesta incluye un campo warning.
Devuelve un píxel.
Modifica un píxel. Envía solo los campos que quieras cambiar: los mismos que al crear, más
tag_ids (lista de IDs de tus etiquetas; sustituye las actuales). Responde con el píxel actualizado.
curl -X PUT "https://pixhook.io/api/index.php?/api/v1/public/pixels/a2dd44d0…" \
-H "X-API-Key: pt_live_…" \
-H "Content-Type: application/json" \
-d '{"name": "Propuesta ACME (v2)", "email_notifications": true}'
Borra el píxel y todas sus aperturas. No se puede deshacer.
{ "success": true, "data": { "deleted": true } }
Aperturas
Lista las aperturas de un píxel, de la más reciente a la más antigua.
| Parámetro | Descripción |
|---|---|
page, limit | Paginación (limit de 1 a 100, por defecto 50). |
date_from, date_to | Rango de fechas AAAA-MM-DD (UTC). |
device_type | desktop, mobile o tablet. |
{
"success": true,
"data": [
{
"id": 330,
"opened_at": "2026-10-20T20:03:04Z",
"ip_address": "188.78.241.237",
"country": "Spain",
"city": "Ávila",
"device_type": "mobile",
"browser": null,
"os": null,
"user_agent": "Mozilla/5.0 (Linux; Android 10; K) …",
"referer": null,
"utm_source": null,
"utm_medium": null,
"utm_campaign": null
}
],
"pagination": { "page": 1, "limit": 50, "total": 38, "total_pages": 1 }
}
Algunos proveedores de correo (como Gmail o Apple Mail) descargan las imágenes desde sus propios servidores, así que la IP y la ubicación pueden ser las del proveedor y no las del destinatario.
Estadísticas
Resumen de un píxel. Por defecto, los últimos 30 días; usa date_from y date_to para cambiar el rango.
{
"success": true,
"data": {
"pixel_id": "344655dd652e5cbcfe3ff83ba182bc2f",
"date_range": { "from": "2026-10-01", "to": "2026-10-31" },
"timezone": "UTC",
"summary": {
"total_opens": 38,
"unique_opens": 8,
"first_open_at": "2026-10-16T08:13:51Z",
"last_open_at": "2026-10-20T20:03:04Z"
},
"daily": [ { "date": "2026-10-16", "opens": 18, "unique_opens": 8 } ],
"hourly": [ { "hour": 8, "opens": 4 } ],
"devices": [ { "device_type": "desktop", "opens": 36 } ],
"countries": [ { "country": "United States", "opens": 30 } ],
"browsers": [ { "browser": "Chrome", "opens": 38 } ],
"utm": {
"sources": [ { "source": "Directo", "opens": 38, "unique_opens": 8 } ],
"mediums": [ { "medium": "Ninguno", "opens": 38 } ],
"campaigns": []
}
}
}
unique_opens cuenta direcciones IP distintas.
Heatmap de horarios
Aperturas por día de la semana y hora. Sin pixel_id, agrega todos tus píxeles.
Por defecto, los últimos 90 días (máximo 366).
| Parámetro | Descripción |
|---|---|
pixel_id | Opcional: solo este píxel. |
date_from, date_to | Rango de fechas AAAA-MM-DD. |
{
"success": true,
"data": {
"pixel_id": null,
"date_range": { "from": "2026-08-04", "to": "2026-11-01" },
"total": 84,
"timezone": "UTC",
"grid": [ [0,0,0,0,0,0,0,2,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0], … ],
"buckets": [ { "hour_start": "2026-10-16T08:00:00Z", "opens": 3 }, … ]
}
}
grid tiene 7 filas (de lunes a domingo) y 24 columnas (de 0 a 23 h) en UTC.
Para mostrarlo en tu zona horaria, usa buckets: cada elemento es una hora exacta en UTC con sus aperturas.
Cuenta
Tu plan, sus límites, el uso de la API este mes y los permisos de la clave. Útil para comprobar que la clave funciona.
{
"success": true,
"data": {
"plan": { "code": "pro", "name": "Pro" },
"limits": {
"pixels": 100,
"events_monthly": 100000,
"data_retention_days": 365,
"api_requests_per_minute": 60,
"api_requests_per_month": 10000
},
"usage": { "api_requests_this_month": 5 },
"api_key": { "name": "Integración CRM", "scopes": ["pixels:read", "pixels:write", "stats:read"] }
}
}
En limits, -1 significa ilimitado.
Ejemplos
PHP
<?php
$apiKey = getenv('PIXHOOK_API_KEY');
$base = 'https://pixhook.io/api/index.php?/api/v1/public';
function pixhook(string $method, string $path, ?array $body = null) {
global $apiKey, $base;
$ch = curl_init($base . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . $apiKey, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
if (empty($res['success'])) {
throw new RuntimeException($res['error']['message'] ?? 'Error de la API');
}
return $res['data'];
}
// Crear un píxel para una propuesta y meterlo en el email
$pixel = pixhook('POST', '/pixels', ['name' => 'Propuesta ACME']);
$html = '<p>Hola, te envío la propuesta…</p>' . $pixel['img_tag'];
// Más tarde: ¿la han abierto?
$stats = pixhook('GET', '/pixels/' . $pixel['id'] . '/stats');
echo $stats['summary']['total_opens'] . " aperturas\n";
Node.js
const BASE = 'https://pixhook.io/api/index.php?/api/v1/public';
async function pixhook(method, path, body) {
const res = await fetch(BASE + path, {
method,
headers: { 'X-API-Key': process.env.PIXHOOK_API_KEY, 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
});
const json = await res.json();
if (!json.success) throw new Error(json.error.message);
return json.data;
}
const pixel = await pixhook('POST', '/pixels', { name: 'Newsletter noviembre' });
console.log(pixel.img_tag);
const opens = await pixhook('GET', `/pixels/${pixel.id}/opens&limit=100`);
console.log(`${opens.length} aperturas`);
Python
import os, requests
BASE = "https://pixhook.io/api/index.php?/api/v1/public"
HEADERS = {"X-API-Key": os.environ["PIXHOOK_API_KEY"]}
r = requests.get(f"{BASE}/stats/heatmap", headers=HEADERS)
r.raise_for_status()
grid = r.json()["data"]["grid"] # 7 × 24, UTC
dias = ["lunes", "martes", "miércoles", "jueves", "viernes", "sábado", "domingo"]
d, h = max(((d, h) for d in range(7) for h in range(24)), key=lambda x: grid[x[0]][x[1]])
print(f"Mejor franja: {dias[d]} a las {h}:00 UTC")
¿Dudas o necesitas un endpoint que no está aquí? Escríbenos a [email protected].