PLAN PRO

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ñaden pagination.
  • Las fechas van en UTC con formato ISO 8601 (2026-10-20T20:03:04Z). Los filtros date_from y date_to usan AAAA-MM-DD y 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

PermisoPermite
pixels:readListar y consultar píxeles.
pixels:writeCrear, modificar y borrar píxeles.
stats:readConsultar 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ímitePlan ProSi se supera
Peticiones por minuto (por clave)60429 rate_limited con cabecera Retry-After
Peticiones al mes (por cuenta)10.000429 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"
  }
}
HTTPcodeSignificado
401missing_api_keyNo se ha enviado la cabecera X-API-Key.
401invalid_api_keyClave inexistente, revocada o caducada.
403plan_without_apiTu plan actual no incluye la API.
403insufficient_scopeLa clave no tiene el permiso necesario.
403limit_reachedHas llegado al máximo de píxeles de tu plan.
403feature_not_availableLa función no está incluida en tu plan.
404not_foundEl recurso no existe o no es tuyo.
409conflictYa existe un píxel con ese nombre.
422validation_errorDatos no válidos (falta un campo, URL incorrecta…).
429rate_limited / monthly_quota_exceededLímite de peticiones superado.
500server_errorError 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.

GET/pixelspixels:read

Lista tus píxeles, del más reciente al más antiguo.

ParámetroDescripción
pagePágina (por defecto 1).
limitResultados por página, de 1 a 50 (por defecto 20).
tag_idSolo los píxeles con esta etiqueta.
{
  "success": true,
  "data": [ { …píxel… } ],
  "pagination": { "page": 1, "limit": 20, "total": 7, "total_pages": 1 }
}
POST/pixelspixels:write

Crea un píxel. Responde 201 con el objeto píxel.

CampoDescripción
name *Nombre del píxel. No puede repetirse en tu cuenta.
redirect_enabledtrue para usar el píxel como enlace con redirección.
redirect_urlURL http(s) de destino.
webhook_enabledtrue para avisar a tu servidor en cada apertura.
webhook_urlURL http(s) pública que recibirá el aviso.
email_notificationstrue para recibir resúmenes por email.
notification_emailEmail de los resúmenes. Si no es el de tu cuenta, recibirá un enlace de confirmación.
notification_frequencydaily 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.

GET/pixels/{id}pixels:read

Devuelve un píxel.

PUT/pixels/{id}pixels:write

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}'
DELETE/pixels/{id}pixels:write

Borra el píxel y todas sus aperturas. No se puede deshacer.

{ "success": true, "data": { "deleted": true } }

Aperturas

GET/pixels/{id}/opensstats:read

Lista las aperturas de un píxel, de la más reciente a la más antigua.

ParámetroDescripción
page, limitPaginación (limit de 1 a 100, por defecto 50).
date_from, date_toRango de fechas AAAA-MM-DD (UTC).
device_typedesktop, 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

GET/pixels/{id}/statsstats:read

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

GET/stats/heatmapstats:read

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ámetroDescripción
pixel_idOpcional: solo este píxel.
date_from, date_toRango 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

GET/accountcualquier clave

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].