PipSync

Inicio rápido

Guarda tu clave, llama a /v1/me para verificar la autenticación y luego comienza a leer señales o trades. Cinco minutos desde cero hasta la primera respuesta de la API.

curl https://app.pipsync.io/api/v1/me \
  -H "Authorization: Bearer $PIPSYNC_KEY"

Cada respuesta está envuelta en { "data": … }. Los endpoints paginados además devuelven un objeto "meta" con total, page, totalPages y hasMore.

Autenticación

Todas las solicitudes a la API requieren un token bearer en el encabezado Authorization. Las claves son por entorno (live / sandbox), por alcance, y con límite de tiempo solo si eliges establecer una expiración.

EncabezadoAuthorization: Bearer pipsync_live_<32 alnum chars>

Obtención de una clave de API

El acceso a la API requiere el plan Enterprise. Una vez en Enterprise:

1. Navega a Configuración → Claves de API en tu espacio de trabajo.
2. Haz clic en Crear clave, elige un nombre (p. ej. prod-signal-reader) y selecciona los alcances que necesites.
3. Copia la clave: se muestra solo una vez. Guárdala en un gestor de secretos (AWS Secrets Manager, Vault, Doppler, etc.).
4. Para rotar: crea una clave de reemplazo, migra el tráfico, revoca la clave anterior. No hay tiempo de inactividad si superpones un ciclo de implementación.

Alcances de clave

Alcance	Acceso	Endpoints
signals:read	Solo lectura	GET /v1/signals
trades:read	Solo lectura	GET /v1/trades
reports:read	Solo lectura	GET /v1/reports, GET /v1/reports/trades
account:read	Solo lectura	GET /v1/me, GET /v1/account/usage
webhooks:write	Escritura	Gestionar suscripciones de webhook (solo panel)

Seguridad de claves

⚠

Nunca expongas una clave live en código del lado del cliente. Las claves incrustadas en paquetes de navegador, aplicaciones móviles o repositorios públicos están comprometidas. Usa claves sandbox para prototipos. Revoca una clave filtrada de inmediato desde Configuración → Claves de API y crea un reemplazo.

Refuerzo adicional disponible en Enterprise: lista de permitidos por IP (restringe qué rangos CIDR pueden usar una clave) y lista de bloqueados por IP. Ambos se configuran por clave desde la misma página de configuración.

Límites de tasa

Los límites son por clave de API por ventana móvil de 60 segundos. Los webhooks tienen límites de tasa separados en su superficie de entrega entrante.

Plan	Solicitudes API / min	Webhooks / min	Ráfaga	Notas
Basic	60	10	1×	Sin margen de ráfaga
Pro	300	60	2×	Ventana de ráfaga corta (5 s)
Business	1000	200	3×	Ráfaga de hasta 3 000 RPM por ≤ 5 s
Enterprise	Personalizado	Personalizado	Personalizado	SLA negociado, concurrencia personalizada

Encabezados de respuesta

Cada respuesta de la API incluye encabezados de límite de tasa para que tu integración se mantenga dentro de los límites sin prueba y error:

Encabezado	Valor
X-RateLimit-Limit	Máximo de solicitudes permitidas en la ventana actual
X-RateLimit-Remaining	Solicitudes restantes en la ventana actual
X-RateLimit-Reset	Marca de tiempo ISO 8601 de cuándo se restablece la ventana
Retry-After	Segundos de espera antes de reintentar (solo en 429)

ℹ

Las respuestas 429 se pueden reintentar. Siempre lee Retry-After y respétalo. No codifiques una duración fija de espera: la ventana exacta depende de tu plan y la carga actual.

Retroceso exponencial

Implementa retroceso exponencial con jitter cada vez que recibas un 429. Este patrón evita problemas de avalancha si tu flota realiza llamadas en paralelo:

async function fetchWithRetry(url, key, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, {
      headers: { Authorization: \`Bearer ${key}\` },
    });
    if (res.status !== 429) return res.json();

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const backoff = retryAfter * 1000 * Math.pow(2, attempt) + Math.random() * 200;
    await new Promise(r => setTimeout(r, backoff));
  }
  throw new Error("Rate limit retries exhausted");
}

Códigos de error

Todos los errores usan RFC 7807 Problem Details (application/problem+json):

{
  "type": "https://app.pipsync.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid API key"
}

Estado HTTP	Significado	Acción
400	Solicitud incorrecta	Corrige el cuerpo de la solicitud / parámetros de consulta
401	No autorizado	Verifica el valor de la clave y el formato del encabezado Authorization
403	Prohibido	La clave carece del alcance requerido para este endpoint
404	No encontrado	El recurso no existe o fue eliminado
422	No procesable	Pasa el esquema pero falló la validación de reglas de negocio
429	Límite de tasa	Retrocede y reintenta (ver Retry-After)
5xx	Error del servidor	Transitorio: reintenta con retroceso; consulta pipsync.io/status

GET /v1/me

Devuelve el perfil del propietario del espacio de trabajo asociado con la clave de API.

GET/v1/ me Pruébalo ↗

curl https://app.pipsync.io/api/v1/me \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/signals

Devuelve señales de trading analizadas para el espacio de trabajo. Las señales son la salida normalizada del analizador, listas para procesamiento posterior.

GET/v1/ signals Pruébalo ↗

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
since	ISO 8601	No	Devuelve señales recibidas en o después de esta hora
limit	número	No	Máximo de resultados por página (predeterminado 25, máximo 100)
page	número	No	Número de página (basado en 1)
instrument	cadena	No	Filtrar por instrumento, p. ej. EURUSD
status	cadena	No	Filtrar por estado: parsed | pending | invalid

curl "https://app.pipsync.io/api/v1/signals?limit=10" \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/trades

Devuelve registros de trades (posiciones abiertas, cerradas, parcialmente cerradas) para el espacio de trabajo. Paginado; trades más recientes primero.

GET/v1/ trades Pruébalo ↗

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
since	ISO 8601	No	Solo trades abiertos en o después de esta hora
limit	número	No	Máximo de resultados por página (predeterminado 25, máximo 100)
page	número	No	Número de página (basado en 1)
instrument	cadena	No	Filtrar por instrumento
status	cadena	No	Filtrar por estado: open | closed | pending

curl "https://app.pipsync.io/api/v1/trades?limit=25" \
  -H "Authorization: Bearer $PIPSYNC_KEY"

GET /v1/reports

Enumera informes de trades generados y enlaces de descarga. Usa /v1/reports/trades para obtener la exportación detallada de partidas CSV/PDF.

GET/v1/ reports Pruébalo ↗

✦

La especificación completa de OpenAPI 3.1 (con esquemas de solicitud / respuesta para cada endpoint) está disponible en /api/v1/openapi.json. Impórtala en Postman, Insomnia, o usa el playground interactivo para probar cada endpoint en vivo.

Transmisión en tiempo real

Para paneles de navegador y monitoreo en vivo, suscríbete a /api/trading/stream con EventSource. Este es el respaldo SSE incluido cuando las actualizaciones de WebSocket no están disponibles; mantén los webhooks firmados para automatización servidor a servidor.

Webhooks

Suscríbete a eventos push desde Configuración → Webhooks. PipSync envía un payload JSON firmado a tu endpoint cada vez que ocurre un evento. La entrega se intenta hasta 5 veces con retroceso exponencial.

POSTtu-servidor.com/pipsync — firmado por X-PipSync-Signature

Evento	Cuándo	Tipo de payload
signal.received	Se analizó una señal de cualquier fuente	SignalIntent
signal.parsed	El analizador normalizó el mensaje fuente	ParsedSignal
trade.opened	Se abrió una posición de broker	TradeOpened
trade.closed	Se cerró una posición de broker	TradeClosed
trade.tp_hit	Se alcanzó el take profit	TradeClosed
trade.sl_hit	Se alcanzó el stop loss	TradeClosed
subscription.upgraded	La suscripción subió a un nivel superior	Subscription
subscription.canceled	Se programó la cancelación	Subscription

Verificación de firmas

Cada entrega de webhook incluye un encabezado X-PipSync-Signature con el formato t=<unix-ts>,v1=<hex-hmac-sha256>. Verifica antes de confiar en el payload:

import crypto from "crypto";

export function verifyWebhook(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=")),
  );
  const signed = parts.t + "." + rawBody;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1 ?? ""),
  );
}

⚡

Siempre verifica la marca de tiempo. Rechaza payloads donde t tenga más de 5 minutos de antigüedad: esto previene ataques de repetición. Compara Math.abs(Date.now() / 1000 - Number(parts.t)) > 300.

Clientes OpenAPI

El contrato incluido es la especificación OpenAPI 3.1 en /api/v1/openapi.json. Genera un cliente tipado en tu entorno de ejecución, o usa el playground interactivo para solicitudes ad-hoc.

✦

Prefiere el playground interactivo para pruebas ad-hoc con tu clave real. Abrir Playground →